Мобильный SDK: ошибки, причины и решения

Обновлено: 13 октября 2026 · 7 мин чтения

Шаги

1. 1

   Ошибки ключа и подключения

   • Строка лога, начинающаяся с api_key, о том, что ключ неверный или не для этой платформы (сервер 401 invalid_api_key; SDK пишет эту строку на азербайджанском). Причина: ключ скопирован неверно, отозван, прошло больше 7 дней после создания нового, или это ключ другой платформы. Решение: на Android ключ android_…, на iOS ios_…; сравните начало ключа в разделе «Installation», при необходимости «New key».
   • Та же ошибка на iOS с верным ключом. Причина: «iOS Bundle ID» канала отличается от Bundle ID приложения, который iOS SDK отправляет при каждом подключении. Bundle ID вводится в мастере при создании канала, и в панели нет места, где его потом изменить. Решение: напишите Clomni AI правильный Bundle ID приложения, команда Clomni его исправит.
   • call Clomni.initialize first. Причина: метод вызван до initialize. Решение: вызывайте initialize при запуске, на Android в Application.onCreate, с классом, указанным в манифесте через android:name.
   • initialize was called before; the first call stays. Решение: вызывайте один раз; чтобы сменить ключ, перезапустите приложение.
   • this App SDK inbox is switched off in Clomni. Причина: канал в аккаунте выключен или аккаунт не активен. Messenger не открывается. Решение: напишите Clomni AI, он проверит и при необходимости передаст команде Clomni.
   • Нет подключения в корпоративной сети. Причина: прокси или список разрешённых хостов. Решение: разрешите app.clomni.ai для HTTPS и WebSocket.
2. 2

   Идентификация пользователей

   • Строка лога, начинающаяся с user_hash, о том, что хеш неверный (сервер 403 identity_verification_failed). Причина: хеш не совпадает. Решение: хеш строится из той же строки user_id, что и в loginUser, текущим секретом, в hex нижнего регистра. Без userId из e-mail без пробелов по краям, в нижнем регистре. «Security» › «Test a hash» называет причину: «It does not match», «The hash is in upper case», «The hash must be 64 hex characters».
   • После смены секрета входы отклоняются. Причина: после «Make a new secret» старый секрет работает только 7 дней. Если «Test a hash» отвечает «Correct, but made with the old secret», сервер ещё на старом секрете. Решение: переведите сервер на новый секрет.
   • В режиме «Enforced» вход без хеша отклоняется. Решение: отправляйте хеш или вернитесь к «Recommended», пока его не отправляют все версии приложения.
   • Следующий пользователь телефона видит диалоги предыдущего. Причина: не вызывается logout. Решение: вызывайте Clomni.logout() вместе с выходом из приложения.
   • Оператор не видит имя пользователя. Решение: передавайте name и email в loginUser, для последующих изменений updateUser.
3. 3

   Push не приходит

   Начните с «Test push» в разделе Push канала: ответ является ответом самого FCM или APNs, он разобран в статье «Ключи push для мобильного SDK».

   • iOS: BadEnvironmentKeyInToken. Причина: ключ APNs только для Sandbox или только для Production. Работает из Xcode, но не из TestFlight (или наоборот). Решение: создайте в Apple Developer новый ключ с «Environment: Sandbox & Production» и загрузите его.
   • Устройства нет в списке «Test push». Причина: токен не дошёл до Clomni. Решение: разрешите уведомления на телефоне, проверьте вызов setDeviceToken, один раз откройте Messenger.
   • Android 13+: уведомления нет, в логе notification not shown (POST_NOTIFICATIONS?). Решение: объявите POST_NOTIFICATIONS в манифесте и запросите его. SDK сам его не запрашивает.
   • Android: в панель загружен google-services.json. Панель пишет «The file has no project_id». Решение: загрузите файл из Firebase › Project settings › Service accounts › «Generate new private key».
   • Android: SENDER_ID_MISMATCH. Причина: service account из другого проекта Firebase. Решение: service account того же проекта, что и google-services.json приложения.
   • Android: уведомления приходят только при открытом приложении. Причина: data-сообщение обрабатывается только на экране. Решение: ClomniPush.handle в FirebaseMessagingService; в React Native setBackgroundMessageHandler в index.js; во Flutter onBackgroundMessage до runApp; в Unity свой ListenerService.
   • iOS: нет capability. Причина: не добавлена capability Push Notifications, токен не выдаётся. Решение: Xcode › Signing & Capabilities › + Capability › Push Notifications.
   • iOS с React Native или Flutter: нажатие на уведомление Clomni открывает только приложение, не диалог. Причина: push Clomni на iOS приходят напрямую из APNs, библиотека Firebase их не видит. Решение: нативный UNUserNotificationCenterDelegate (ClomniNotifications) и токен APNs через getAPNSToken, как в статье платформы.
   • iOS: InvalidProviderToken (неверный Key ID или Team ID), DeviceTokenNotForTopic (Bundle ID в Push не совпадает с приложением).
   • iOS: приложение падает при нажатии с «Call must be made on main thread». Решение: сделайте методы делегата @MainActor.
   • Android: иконка в виде серого квадрата. Решение: белая силуэтная иконка через setNotificationIcon.
   • Android: в логе push token not registered: …. Причина: токен не дошёл до сервера. Решение: проверьте сеть, вызов setDeviceToken и service account JSON в панели.
4. 4

   Установка (Android, iOS, React Native, Flutter, Unity)

   • Сборка Android останавливается на слиянии манифестов: provider#androidx.core.content.FileProvider@authorities … collides with another value (например, с unity-webview в Unity). Причина: SDK 1.0.4 и более ранние объявляли класс FileProvider из androidx, который объявляет и приложение или другая библиотека. Решение: обновите SDK до 1.0.5 (Unity: #unity-1.0.5, затем resolve в EDM4U). Если Вы добавили tools:replace из-за этой ошибки, удалите его.
   • pod install не находит ClomniMessenger («Unable to find a specification»). Причина: SDK нет в CocoaPods trunk. Решение: pod 'ClomniMessenger', :git => 'https://github.com/clomni/clomni-mobile-sdk.git', :tag => '1.0.4'. В Unity меняйте эту строку в Podfile папки сборки после каждой сборки iOS.
   • React Native: pod install пишет «@clomni/react-native needs React Native 0.75 or later». Решение: обновите React Native до 0.75+ или добавьте строку pod 'ClomniMessenger' выше в Podfile.
   • React Native: ошибки линковки на символах ClomniMessenger. Решение: та же строка в Podfile и pod install.
   • React Native, Expo: «The package doesn't seem to be linked». Причина: Expo Go не загружает нативные модули. Решение: development build (npx expo prebuild, npx expo run:ios, сборка EAS).
   • Flutter: pod install останавливается с «clomni_flutter: the iOS SDK is not on CocoaPods trunk». Причина: Swift Package Manager выключен, а в Podfile нет строки. Решение: flutter config --enable-swift-package-manager или строка внутри target 'Runner'.
   • Flutter, Android: приложение падает при открытии Messenger, плавающая кнопка не видна. Решение: MainActivity должна наследовать FlutterFragmentActivity.
   • Unity: в редакторе ничего не происходит, это нормально. Xcode не находит модуль: откройте .xcworkspace.
5. 5

   Messenger, flow и язык

   • Messenger не открывается, лог пуст. Решение: включите отладочный лог; в Unity проверяйте на устройстве.
   • iOS: no window to present the messenger from yet. Решение: вызывайте present после показа экрана.
   • Messenger открывается, но остаётся пустым или показывает «Повторить». Причина: не удалась первая загрузка: нет интернета, app.clomni.ai заблокирован или ключ отклонён. Решение: найдите ошибку в логе.
   • Изменение в панели не видно в приложении. Причина: Appearance ещё в черновике. Решение: «Appearance» › «Publish».
   • startFlow ничего не делает. Причина: к событию не привязан опубликованный flow. Решение: в конструкторе flow триггер «App event», то же имя, flow опубликован. В разделе «Flows» должно быть видно «Event: …».
   • В startFlow передано название flow. Имя события и название flow не одно и то же: передайте имя из строки «Event: …» под flow в разделе Flows. Flow с триггером «When a conversation starts» через startFlow не запускается.
   • Flow нового диалога не работает. Причина: flow, выбранный в мастере, остался черновиком, «Overview» пишет «The new conversation flow is not published.» Решение: опубликуйте его в разделе «Flows».
   • {{data.…}} в тексте flow остаётся пустым. Решение: одинаковое имя ключа в данных startFlow и во flow.
   • Messenger говорит не на том языке. Причина: setLanguage выбрал язык, выключенный в панели, или язык не выбран, а языка телефона среди включённых нет. Решение: включите язык в «Appearance» › «Languages» и опубликуйте, или вызовите setLanguage("az").
   • Плавающая кнопка не видна. Причина: она выключена и в панели, и в коде. Решение: setLauncherVisible(true) или «Appearance» › «Theme» › «Floating button».
   • React Native: плавающая кнопка не появляется при холодном запуске. Причина: ошибка SDK 1.0.1, исправлено в 1.0.2. До этого открывайте Messenger своей кнопкой.
   • React Native, Android: открытый Messenger пропадает, когда приложение снова открывают по иконке. Причина: MainActivity с singleTask. Исправлено в SDK 1.0.2.
   • В логе setTheme: primaryColor "…" is not #RRGGBB. Причина: формат цвета. Решение: # и шесть hex-цифр, например #0A66C2.
   • iOS: font family "…" is not in the app; the system font stays. Причина: шрифта нет в бандле. Решение: добавьте файл шрифта в таргет и в UIAppFonts в Info.plist.
   • Оператор не видит диалоги из приложения. Решение: добавьте его в раздел канала «Collaborators».
   • «Overview»: «… devices run an old SDK version». Решение: выпустите приложение с новым SDK.
6. 6

   Если всё ещё не работает

   Напишите Clomni AI: платформа и версия SDK (Clomni.version в Kotlin и Swift), App ID, что показывает «Overview», отладочный лог в момент проблемы, для push ответ «Test push». Никогда не отправляйте Identity Secret, полный ключ API, файл .p8 или файл service account.

7. 7

   Полное руководство

   • PDF: руководство Clomni Mobile SDK, на русском языке.
   • Онлайн: Troubleshooting (на английском).
   • В панели: раздел «Guide» в колонке настроек канала.