Устранение неполадок

Возникли проблемы? Вы находитесь в нужном месте. Этот гид охватывает самые распространенные проблемы, с которыми сталкиваются разработчики при интеграции виджета, а также пошаговые решения. Большинство проблем можно решить всего за несколько минут.

Виджет не загружается

Если виджет вообще не появляется на вашей странице, выполните следующие шаги по устранению неполадок в порядке:

❌ Проблема: Скрипт виджета не загружается

✅ Решение: Проверьте необходимые атрибуты

Убедитесь, что все необходимые атрибуты данных присутствуют в теге скрипта:

<script src="https://widget.companin.tech/widget.js" data-widget-key="YOUR_WIDGET_KEY" data-locale="en"></script>

❌ Проблема: Ошибка аутентификации

✅ Решение: Проверьте конфигурацию OAuth

Проблемы с аутентификацией обычно легко исправить. Пройдите через эти проверки:

• Убедитесь, что client_id правильный в вашем приложении OAuth - Скопируйте его прямо из вашей панели управления, чтобы избежать опечаток
• Убедитесь, что приложение OAuth активно и не отключено в вашей панели управления
• Проверьте, что у приложения OAuth настроены правильные URI перенаправления - Домен виджета должен быть разрешен
• Убедитесь, что домен виджета разрешен в настройках CORS на вашем сервере
• Если вы недавно сгенерировали учетные данные, убедитесь, что вы используете новые значения

Все еще застряли? Попробуйте создать новое приложение OAuth в вашей панели управления. Иногда начало с нуля решает неясные проблемы конфигурации.

❌ Проблема: /api/v1/auth/widget-token возвращает 400 (Источник не разрешен)

✅ Решение: Совместите источник хоста и белый список OAuth

• Добавьте источник вашей страницы встраивания (например, http://localhost:3000) в разрешенные источники OAuth.
• Используйте полный формат схемы + хоста (+ порта), без завершающего пути.
• При встраивании в iframe убедитесь, что вызовы токена содержат источник страницы хоста в X-Embed-Origin.
• Проверьте, что URL запроса - /api/v1/auth/widget-token (не устаревшие пути).

Совет по проверке: Проверьте вкладку сети браузера для заголовков запроса токена и сравните X-Embed-Origin с вашей записью разрешенных источников OAuth.

Виджет не виден

❌ Проблема: Виджет появляется свернутым, но кнопка невидима

✅ Решение: Проверьте позиционирование конфигурации

• Проверьте настройку позиции конфигурации виджета
• Проверьте наличие конфликтов CSS с position: fixed
• Убедитесь, что родительские контейнеры не имеют overflow: hidden

❌ Проблема: Виджет скрыт на мобильных устройствах

✅ Решение: Настройте мобильные настройки

Если hide_on_mobile включен в конфигурации, виджет будет скрыт на мобильных устройствах. Отключите эту настройку или настройте мобильную точку разрыва.

Проблемы со стилями

Визуальные проблемы распространены и обычно легко исправляются. Виджет разработан так, чтобы быть визуально изолированным от вашей страницы, но иногда могут возникать конфликты.

❌ Проблема: Цвета не применяются

✅ Решение: Очистите кэш и проверьте конфигурацию

Следуйте этим шагам, чтобы диагностировать проблемы с цветом:

• Очистите кэш браузера и перезагрузите страницу (Ctrl+Shift+R или Cmd+Shift+R для жесткой перезагрузки)
• Убедитесь, что значения цветов являются действительными шестнадцатеричными кодами (должны начинаться с # и содержать 6 символов, например, #FF5733)
• Проверьте, что конфигурация была сохранена в панели управления - Ищите подтверждение "сохранено"
• Убедитесь, что вы редактируете правильную конфигурацию - Проверьте, совпадает ли ID конфигурации с вашим тегом скрипта
• Подождите несколько секунд после сохранения - Изменения конфигурации могут занять 5-10 секунд для распространения

Совет по отладке: Откройте виджет в вашем браузере и используйте инструмент инспекции элементов, чтобы проверить, какие значения CSS действительно применяются. Это покажет вам, загружаются ли ваши цвета или переопределяются.

❌ Проблема: Шрифты не загружаются

✅ Решение: Конфигурация шрифта

• Убедитесь, что семейство шрифтов установлено на "system-ui" или безопасный веб-шрифт
• Пользовательские шрифты могут не загружаться из-за ограничений CORS
• Проверьте, поддерживаются ли значения font-weight

Проблемы с функциональностью

Когда виджет загружается правильно, но функции не работают так, как ожидалось, эти решения помогут.

❌ Проблема: Сообщения не отправляются

✅ Решение: Проверьте сессию и сеть

Проблемы с отправкой сообщений обычно связаны с сетевым подключением или истекшими сессиями. Диагностируйте систематически:

• Убедитесь, что конечные точки API доступны - Попробуйте получить доступ к URL API напрямую в вашем браузере
• Проверьте, действителен ли токен аутентификации - Ищите ошибки 401/403 во вкладке сети
• Убедитесь, что сессия не истекла - Сессии обычно длятся 30 минут бездействия
• Проверьте наличие проблем с сетевым подключением - Стабильно ли ваше интернет-соединение?
• Ищите ошибки CORS в консоли - Это указывает на то, что ваш домен может не быть в белом списке
• Убедитесь, что программное обеспечение брандмауэра/безопасности не блокирует API - Корпоративные сети иногда блокируют внешние API

Быстрый тест: Если сообщения работают в режиме инкогнито, но не в вашем обычном браузере, проблема, вероятно, связана с расширениями браузера или кэшированными данными аутентификации.

❌ Проблема: Потоки разговоров не работают

✅ Решение: Проверьте конфигурацию потока

• Проверьте, чтобы триггерные ключевые слова совпадали точно
• Убедитесь, что ответы потока правильно настроены
• Убедитесь, что действия кнопки действительны

Проблемы с производительностью

❌ Проблема: Виджет загружается медленно

✅ Решение: Оптимизируйте загрузку

• Используйте сборку для производства вместо разработки
• Включите кэширование браузера для статических ресурсов
• Минимизируйте пользовательский CSS и изображения
• Рассмотрите возможность ленивой загрузки, если это не критично

❌ Проблема: Высокое использование памяти

✅ Решение: Уменьшите использование ресурсов

• Ограничьте длину истории сообщений
• Оптимизируйте изображения и медиа
• Отключите неиспользуемые функции

Совместимость с браузерами

❌ Проблема: Виджет не работает в старых браузерах

✅ Решение: Проверьте поддержку браузера

Виджет требует современных функций браузера:

• Поддержка JavaScript ES6+
• API PostMessage
• CSS Grid и Flexbox
• Современные возможности iframe

Минимально поддерживаемые браузеры: Chrome 60+, Firefox 55+, Safari 12+, Edge 79+

Получение помощи

Когда вам нужна дополнительная помощь помимо этого руководства, эти инструменты и ресурсы помогут вам диагностировать проблемы или получить поддержку.

Режим отладки

Включите режим отладки, чтобы увидеть подробные журналы в консоли вашего браузера. Это дает представление о том, что делает виджет на каждом этапе:

<script  src="https://widget.companin.tech/widget.js"  data-widget-key="YOUR_WIDGET_KEY"  data-dev="true"></script>

Инструменты разработчика браузера

• Проверьте вкладку Консоль на наличие ошибок JavaScript
• Проверьте вкладку Сеть на наличие неудачных запросов
• Проверьте вкладку Приложение на наличие проблем с локальным хранилищем
• Используйте вкладку Элементы, чтобы проверить DOM виджета

Общие шаги отладки

1. Очистите кэш браузера и куки
2. Попробуйте в режиме инкогнито/приватного просмотра
3. Проверьте с различными браузерами
4. Проверьте сетевое подключение
5. Проверьте все значения конфигурации