Перейти к основному содержимому
Версия: 5.9.0

Решение проблем

Руководство по диагностике и устранению проблем при интеграции и работе ChatCenterUI SDK.

Включите подробное логирование

Для всех сценариев ниже включите ChatLoggerConfig(logLevel: .all) — без него SDK не выводит ни сетевые запросы, ни WebSocket-события (logLevel: .off — значение по умолчанию). Подробнее — в разделе Настройки логирования.

Сначала проверьте настройки канала в АРМ администратора

Многие наблюдаемые в SDK проблемы вызваны не кодом приложения, а конфигурацией канала на сервере. Прежде чем углубляться в чеклисты ниже, сверьтесь с АРМ:

Симптом в SDKЧто проверить в АРМ
Пуши не приходят / приходят не из всех окруженийПодключение iOS-канала → APNs, Шаблоны пуш-уведомлений
Чат показывает «нерабочее время» / автоответРежим работы канала
Не приходит уведомление о сборе персональных данных, согласие, опросУведомления для клиента, Уведомления о сборе ПД, Опросы клиентов
Тред уходит не тому агенту/ботуСегментация тредов, Маршрутизация
Уведомления показываются не на всех клиентахУведомления в веб-чате и мобильных приложениях

Полный обзор админки — АРМ администратора.

SDK не инициализируется​

Симптомы​

  • Приложение падает при создании ChatCenterUISDK
  • SDK создаётся, но методы не работают

Чеклист​

  1. Фреймворк подключён корректно?

    • В General → Frameworks and Libraries фреймворк ChatCenterUI.xcframework добавлен с режимом Embed & Sign
    • При использовании CocoaPods проект открыт через .xcworkspace, а не .xcodeproj

  2. providerUid указан верно?

    • Значение получено от edna при интеграции
    • Нет лишних пробелов или переносов строк

  3. ChatTransportConfig содержит корректные URL?

    // URL должны быть полными, с протоколом
    let transport = ChatTransportConfig(
        rest: "https://your-host.edna.ru",
        webSocket: "wss://your-host.edna.ru/socket",
        dataStore: "https://your-host.edna.ru/files"
    )

    // Или для облачных клиентов (без https://):
    let transport = ChatTransportConfig(cloudHost: "your-host.edna.ru")

  4. Экземпляр SDK сохранён?

    • ChatCenterUISDK должен быть сохранён как свойство — иначе ARC освободит его сразу после выхода из метода, и delegate, наблюдатели за UIApplication-уведомлениями и WebSocket развалятся
    // Неверно — SDK освобождается после выхода из метода
    func setup() {
        let sdk = ChatCenterUISDK(...)
    }

    // Верно — SDK живёт всё время работы приложения
    var chatCenterSDK: ChatCenterUISDK?
    func setup() {
        chatCenterSDK = ChatCenterUISDK(...)
    }

Чат не загружается​

Симптомы​

  • При вызове getChat() выбрасывается ошибка
  • Экран чата показывает индикатор загрузки бесконечно
  • Отображается ошибка подключения

Чеклист​

  1. Пользователь авторизован?

    // getChat() выбросит ChatCenterUIError.userNotAuthorized если забыли:
    chatCenterSDK.authorize(user: ChatUser(identifier: "user_id"))

  2. Сервер доступен?

    • Откройте REST URL в браузере — ожидаемый ответ HTTP 200 или 401/403 (требует auth); 5xx или таймаут означают недоступность сервера
    • Проверьте, что устройство/симулятор имеет доступ к сети
    • При использовании VPN убедитесь, что трафик маршрутизируется корректно

  3. SSL-сертификат валиден?

    • Для тестовых серверов с самоподписанным сертификатом: 
      var networkConfig = ChatNetworkConfig()
      networkConfig.sslPinning.allowUntrustedSSLCertificate = true // только для тестов!
      let chatConfig = ChatConfig(transportConfig: transport, networkConfig: networkConfig)
    • Для продакшена используйте sslPinning.trustedCertificates с резервными сертификатами

  4. Версия API совпадает с сервером? Значение по умолчанию .api17 подходит для ChatCenter 6.x и выше. Точное значение для вашего сервера — в таблице Версии API.

Сообщения не отправляются​

Симптомы​

  • Сообщение показывает статус Не доставлено
  • send(message:) выбрасывает ошибку
  • Сообщения пропадают

Чеклист​

  1. Какая ошибка? Поймайте конкретный кейс ChatCenterUISendMessageError и сопоставьте его с причиной — таблица случаев и пример обработки в Справочнике ошибок. Самый частый случай при программной отправке — .webSocketNotActive (чат закрыт, WebSocket разорван).

  2. WebSocket-соединение активно?

    • При отправке из фона: установите chatConfig.keepSocketActive = true и chatConfig.shouldUseRemoteConfig = false (иначе серверный конфиг переопределит локальное значение). См. предупреждение в Настройках SDK.
    • Проверьте наличие сети на устройстве.

  3. Размер вложения не превышает лимит? Для изображений SDK проверяет размер до отправки и бросает ChatCenterUISendMessageError.messageImageTooLarge при превышении. Лимит по умолчанию — 30 МБ; сервер может переопределить его. Точное значение для вашего тенанта — у поддержки edna.

  4. send(message:) не бросает ошибку, но сообщение не дошло? Метод подтверждает только отправку в WebSocket, а не доставку серверу. REST-сбои (загрузка истории и файлов) приходят отдельно через делегат didReceiveNetwork(error:); обрывы WebSocket в делегат не приходят (см. Делегат SDK).

Пуш-уведомления не приходят​

Симптомы​

  • Устройство не получает пуши от ChatCenter
  • Пуш приходит, но чат не открывается

Чеклист​

  1. Токен устройства передан через ChatCenterUISDK.setDeviceToken(_:)? Полный пример вызова — в разделе Уведомления.

  2. Разрешения на уведомления запрошены через UNUserNotificationCenter.requestAuthorization? Без этого APNs не выдаст токен.

  3. Пуши настроены на сервере edna? Ключ APNs (.p8) или сертификат (.p12), Bundle ID, тип окружения (sandbox/production) задаются в АРМ — см. Подключение мобильного чата iOS → Настройка пуш-уведомлений. Шаблон APNs payload (поля aps, плейсхолдеры) — в Шаблонах пуш-уведомлений. Если у вас нет доступа к АРМ — support@edna.ru.

  4. Уведомление от ChatCenter, а не от вашего приложения?

    if let userInfo = userInfo as? [String: Any],
       ChatCenterUISDK.isChatCenterNotification(userInfo) {
        // Это уведомление от ChatCenterUI SDK
    }

  5. Обработка уведомления реализована? Оба метода объявлены как throws(ChatCenterUIError) — обязательно используйте try:

    • Чат открыт → try chatCenterSDK.handleNotification(userInfo: userInfo) (контекст в уже открытый чат не подставляется — см. Уведомления)
    • Чат закрыт → try chatCenterSDK.getChat(userInfo: userInfo) + показать ViewController

Подробнее — в разделе Уведомления.

Проблемы с темой / кастомизацией​

Симптомы​

  • Стили применяются с задержкой (с первого кадра видна дефолтная тема)
  • Светлая тема работает, тёмная — нет
  • Шрифт в пузырях сообщений не меняется

Чеклист​

  1. Тема задана до getChat()? Тема считывается при открытии чата.
  2. Порядок присваивания theme и darkTheme корректный? Назначайте chatCenterSDK.darkTheme после chatCenterSDK.theme. Присваивание theme сбрасывает darkTheme — если выставить тёмную тему первой, светлая её затрёт.
  3. Шрифт в пузырях — это typography.message, а не typography.body (см. карту токенов в типографике).

Подробный FAQ по дизайн-системе — в разделе Troubleshooting дизайн-системы.

Долгая загрузка чата​

Симптомы​

  • В логах SDK (logLevel: .all) время REST-запроса истории (api/client/history или history для серверов с newRoutesEnabled: false) больше 1–2 секунд
  • Задержка воспроизводится в демо-приложении на тех же серверных данных

Чеклист​

  1. Проверьте сетевую задержку до сервера. Включите ChatLoggerConfig(logLevel: .all) и сравните время REST-запроса истории (api/client/history или history) с типичной задержкой до сервера.
  2. Размер страницы истории на scroll-up. При shouldUseRemoteConfig = false уменьшите chatConfig.historyLoadingCount (по умолчанию — 30). При shouldUseRemoteConfig = true значение задаётся сервером — настройка через поддержку edna.
  3. Не пересоздавайте ChatTheme перед каждым открытием чата — храните как свойство и переиспользуйте.

Диагностика с помощью демо-приложения​

  1. Воспроизведите проблему в демо-приложении с вашими серверными данными.
  2. Если проблема повторяется — причина в SDK или сервере; пришлите изолированный проект на support@edna.ru. Перед отправкой замените реальные providerUid и серверные URL на плейсхолдеры (см. Сообщить об ошибке).
  3. Если в демо проблемы нет — причина в настройках вашего проекта или способе интеграции.

Связанные разделы​

Последнее обновление