Как встроить Clomni Messenger в Ваше приложение для iOS и Android: канал в панели, ключи и user_hash, код для Android, iOS, React Native, Flutter и Unity, ключи push Firebase и APNs, решение проблем.

Статьи по документу

• Что такое мобильный SDK и кому он нужен Clomni Mobile SDK открывает Clomni Messenger внутри Вашего приложения для iOS или Android: пользователь пишет, не выходя из приложения, а диалог попадает к операторам в Clomni. Есть пакеты для Android, iOS, React Native, Flutter и Unity. Канал «Mobile app (App SDK)» включён не в каждом аккаунте: если его нет в каталоге, его включает команда Clomni.
• Как подключить мобильный SDK к приложению за 15 минут: с нуля до первого сообщения Создайте канал, сохраните ключи, добавьте пакет и вызовите initialize, выполните вход пользователя с user_hash, откройте Messenger со своей кнопки. Затем проверьте: устройство появилось в разделе Installation, «Test a hash» отвечает «Correct», «Test push» приносит уведомление, сообщение из приложения видно в Conversations.
• Как создать канал Mobile app (App SDK) и где его настройки «Settings › Workspace settings › Inboxes › Add Inbox» › «Mobile app (App SDK)» › «Connect». В мастере 6 шагов, обязателен только первый. На странице канала настройки находятся в отдельной колонке рядом с меню панели, вверху название канала и кнопка ←: APP (Overview, Installation, Security, Push, Guide), MESSENGER (Appearance, Flows, News, CSAT), INBOX (Settings, Collaborators, Business Hours, Analytics).
• Ключи мобильного SDK и идентификация пользователей (user_hash) App ID и ключ API хранятся в приложении, Identity Secret только на Вашем сервере. Сервер для каждого пользователя вычисляет user_hash = hex(HMAC-SHA256(identity_secret, user_id)), приложение передаёт его в loginUser. Режимы: Off, Recommended, Enforced. После создания нового секрета или нового ключа API старый работает ещё 7 дней.
• Как подключить мобильный SDK к приложению Android Добавьте пакет ai.clomni:messenger:1.0.5, вызовите Clomni.initialize в Application.onCreate, выполните вход пользователя через loginUser и открывайте Messenger со своей кнопки через Clomni.present. Для push в своём FirebaseMessagingService передавайте токен в Clomni.setDeviceToken, а сообщение в ClomniPush.handle, и запросите разрешение POST_NOTIFICATIONS на Android 13+.
• Как подключить мобильный SDK к приложению iOS Добавьте пакет ClomniMessenger через Swift Package Manager (или строкой :git в CocoaPods), вызовите Clomni.initialize в AppDelegate, выполните вход через loginUser и открывайте Messenger через Clomni.present после показа экрана. Для push нужны capability Push Notifications, setDeviceToken и handlePush в AppDelegate и ключ APNs Sandbox & Production в панели.
• Как подключить мобильный SDK к приложению React Native или Expo npm install @clomni/react-native, на iOS pod install. Вызовите Clomni.initialize в index.js с ключом платформы. В Expo нужен development build и config plugin пакета, не Expo Go. Push на Android: токен и setBackgroundMessageHandler через @react-native-firebase/messaging. Push на iOS не идёт через Firebase: нажатие ловит нативный делегат, токен APNs передаётся через getAPNSToken.
• Как подключить мобильный SDK к приложению Flutter flutter pub add clomni_flutter. На iOS SDK является Swift package: со включённым Swift Package Manager плагин берёт его сам, с CocoaPods в Podfile нужна строка :git. На Android MainActivity должна наследовать FlutterFragmentActivity. Clomni.initialize в main(), firebase_messaging для push на Android и нативный делегат уведомлений в Runner на iOS.
• Как подключить мобильный SDK к игре на Unity Добавьте пакет по git URL в Package Manager, нативные SDK приносит External Dependency Manager (EDM4U). После сборки iOS замените строку pod в Podfile на форму :git и откройте .xcworkspace. Вызывайте Clomni.Initialize через RuntimeInitializeOnLoadMethod. Push на Android через Firebase Unity SDK и свой ListenerService для закрытой игры, на iOS через пакет Mobile Notifications.
• Ключи push для мобильного SDK: Firebase (FCM) и APNs Для Android в панель загружается service account JSON проекта Firebase (Project settings › Service accounts › Generate new private key), а не google-services.json. Для iOS ключ APNs .p8 с Key ID, Team ID и Bundle ID; ключ должен быть создан с Environment: Sandbox & Production, иначе APNs отвечает BadEnvironmentKeyInToken. Проверка через «Test push» в разделе Push канала.
• Внешний вид мобильного Messenger, flow, новости, CSAT и заголовок push Изменения внешнего вида остаются в черновике, приложения видят их только после «Publish», без нового релиза. Flow сгруппированы по триггеру: «When a conversation starts», «App event» (startFlow), «By hand», «When the conversation status changes», «Reusable». Messenger запускает только опубликованный flow. Новости видны на главной Messenger, у редактора новостей своя страница. В разделах Flows и News ссылка «How does it look in the app?» показывает экраны SDK. CSAT включается в разделе CSAT канала. Заголовок уведомления выбирается в разделе Push.
• Мобильный SDK: ошибки, причины и решения Сначала смотрите «Overview» канала и отладочный лог SDK. Частые случаи: 401 invalid_api_key (ключ другой платформы, отозванный ключ, несовпадение iOS Bundle ID), неверный user_hash и 403 identity_verification_failed, APNs BadEnvironmentKeyInToken, разрешение на уведомления Android 13, загруженный в панель google-services.json, Firebase не видит push Clomni на iOS, ошибки pod install, flow не запускается, язык.
• Мобильный SDK: частые вопросы Минимальные версии, размер SDK (Android AAR около 2 МБ, iOS около 3,7 МБ), какие данные собираются, лицензия Apache-2.0, смена ключей и секрета (старый работает ещё 7 дней), сколько приложений в одном канале, тестовая и боевая среда, заголовок push, CSAT, работа без интернета, Expo и надпись «Powered by Clomni».
• Мобильный SDK: версии и что нового В 1.0.5 FileProvider камеры стал собственным классом SDK, поэтому сборка Android больше не конфликтует с библиотеками со своим FileProvider, например unity-webview; Android, React Native, Flutter и Unity в версии 1.0.5, iOS остаётся 1.0.4. В 1.0.4 сценарий решает, может ли клиент писать: поле ввода может оставаться под кнопками, а шаг «Turn off typing» держит разговор закрытым для ввода и после окончания сценария; все пакеты в версии 1.0.4. В 1.0.3 кнопка микрофона отвечает сразу при касании, а нажатие в одну секунду записывается; все пакеты в версии 1.0.3. В 1.0.2 появились голосовые сообщения, фото и видео с камеры, очередь сообщений без интернета и ряд исправлений; iOS тоже 1.0.2. Для голосовых сообщений Android-приложение объявляет `RECORD_AUDIO`. В 1.0.1 Android SDK отправляет имя пакета приложения, и Clomni сравнивает его с именем пакета Android в канале: если они не совпадают, ключ отклоняется. Android, React Native, Flutter и Unity в версии 1.0.1, iOS остаётся 1.0.0. Чтобы обновиться, смените версию пакета.