Клиентский SDK (iOS, Android, React Native)
Как добавить чат, сообщения и мобильные пуши GetMyBot в своё приложение. Подключение SDK, проверка пользователя и работа без сети.
На этой странице
SDK представляет собой библиотеку для разработчика вашего приложения. Она добавляет чат с поддержкой и сообщения внутри приложения (in-app контент). Например, клиент пишет из приложения iOS, а оператор отвечает в том же кабинете GetMyBot, где видит обращения с сайта.
Доступны iOS, Android и React Native. Ниже сначала перечислены возможности и настройка проекта, затем описаны подключение в коде, проверка пользователя и технический контракт. Чат использует веб-канал бота, а сообщения внутри приложения документы Студии контента.
Что делает SDK
- Устанавливается: приложение регистрируется один раз, получает долговременный токен установки и хранит его в Keychain или Android Keystore.
- Опознаёт пользователя: пока он анонимен, это один посетитель; после
identifyустановка объединяется с опознанным человеком и делит с ним историю во всех остальных разделах MyBot. - Копит работу офлайн: события, свойства профиля, набор текста и операции с пуш-токеном записываются локально и уходят упорядоченными пачками, когда появляется сеть.
- Ведёт чат: история, отправка, вложения, счётчик непрочитанного и курсор прочтения поверх того же диалога, с которым работают операторы.
- Обновляет чат сразу: новые сообщения, правки и удаления приходят по WebSocket. Для подключения используется одноразовое разрешение, тикет.
- Показывает in-app контент: документы поп-апов из Контент-студии с квитанциями показа, действия и конверсии.
- Получает мобильные пуши: регистрирует токен устройства для рассылок и кампаний; доставка зависит от настроек сервера и действующего токена.
Платформы: iOS (Swift, iOS 15+, с фасадом для Objective-C и необязательным UI-таргетом), Android (Kotlin, minSdk 24, с фасадом для Java) и React Native (TypeScript поверх двух нативных SDK). Все три реализуют одну спецификацию и проверяются одним набором эталонных фикстур: см. «Контракт».
Включите проект
SDK настраивается для каждого бота на отдельном экране в кабинете. При включении вы указываете, каким приложениям он разрешён, и получаете две сущности.
Списки приложений. Вы перечисляете bundle id для iOS и имена пакетов для Android (хотя бы один нужен, чтобы создать проект, максимум по 64 в каждом списке). Приложению не из списка сервер отвечает ровно так же, как на неизвестный ключ проекта, поэтому по ответу нельзя отличить «неверный ключ» от «верный ключ, чужое приложение».
Ключ проекта выглядит как sdk1_eu_<24 hex>_<32 hex>. Он публичный, как install-ключ виджета: попадает в сборку приложения, это нормально, и он не даёт читать диалоги или менять настройки. Регион внутри нужен, чтобы кабинет показывал, к какому развёртыванию относится проект. SDK передаёт ключ дословно и никогда его не разбирает.
Секрет личности: совсем другая сущность, и в приложение он не попадает никогда. Он показывается ровно один раз: при включении проекта и затем при каждой ротации. Скопируйте его в этот момент в хранилище секретов своего бэкенда: ни кабинет, ни API больше его не покажут.
Ротация секрета личности создаёт новый и оставляет предыдущий рабочим ещё сутки, чтобы у вас был цикл выкатки. Ничто из уже установленного ротацией не ломается: ключ проекта не меняется, устройства продолжают работать.
Отзыв устройства. В списке установок видны платформа, идентификатор приложения, версия SDK, локаль, часовой пояс, признак опознанного пользователя и время последней активности (до 200 недавних записей). Удаление записи немедленно лишает эту установку доступа.
Всплеск установок. Регистрация новой установки создаёт посетителя и попадает под тот же лимит на аккаунт, что и виджет на сайте: при всплеске ответ 429 с Retry-After: 60. Дальнейшая работа уже зарегистрированной установки идёт по её собственному токену и под это ограничение не попадает: но повторная регистрация (переустановка приложения, очищенное хранилище ключей) считается новой. См. Виджет на сайте.
Секрет развёртывания CUSTOMER_SDK_KEY_SECRET
Это третья сущность, помимо ключа проекта и секрета личности, и относится она не к вашему проекту, а ко всему развёртыванию MyBot. Ключ проекта не просто хранится в базе: он подписан этим секретом, и подпись проверяется при каждом запуске SDK.
Отсюда два следствия, о которых важно знать заранее.
На сервере должен быть задан секрет SDK. Если CUSTOMER_SDK_KEY_SECRET пуст, подпись ключа проекта не проходит проверку. Регистрация установки отвечает 401, как и при неизвестном ключе, а включение нового проекта отвечает 503. Рабочее развёртывание платформы без этого секрета не запускается; проверить настройку нужно администратору собственного или тестового сервера.
Ротация секрета обесценивает все ранее выпущенные ключи проектов. Подпись старого ключа новым секретом не сходится, а перевыпустить подписи нельзя: ключ хранится подписанным. Практически это значит: после смены CUSTOMER_SDK_KEY_SECRET каждое приложение с уже выпущенным ключом проекта начнёт получать 401, и лечится это только новым ключом проекта в новой сборке приложения, то есть релизом в сторах. Планируйте такую смену как несовместимое изменение, а не как рутинную гигиену секретов.
Секрет личности к этому не относится: он не подписан ключом развёртывания, и его ротация (со сроком перекрытия в сутки, см. выше) на выпущенные ключи проектов не влияет.
Установка и запуск клиента
Исходники SDK лежат в мобильном репозитории в каталоге customer-sdk/: Swift-пакет MyBotSDK (customer-sdk/ios), Gradle-модуль mybot-sdk в пространстве имён dev.gelfand.mybot.sdk (customer-sdk/android) и npm-пакет @mybot/customer-sdk-react-native (customer-sdk/react-native).
Для запуска клиента нужны ключ проекта, базовый адрес вашего развёртывания MyBot и идентификатор приложения. Хост у сборки один: SDK не выбирает другой адрес по региону из ключа.
let client = try await MyBotClient.start(
configuration: Configuration(
projectKey: "sdk1_eu_…",
baseURL: URL(string: "https://api.getmybot.dev")!,
appIdentifier: "dev.getmybot.example",
sdkVersion: "1.0.0"
)
)
val client = MyBotClient.start(
context,
MyBotConfiguration(
projectKey = "sdk1_eu_…",
baseUrl = "https://api.getmybot.dev",
),
)
const client = await MyBotClient.start({
projectKey: "sdk1_eu_…",
baseURL: "https://api.getmybot.dev",
appIdentifier: "dev.getmybot.example",
});
Первый запуск регистрирует установку и сохраняет её токен, все следующие: продолжают её. Токен выдаётся один раз; если он потерян или есть подозрение на утечку, SDK обновляет его на месте, не меняя личность.
Личность: подписывает ваш бэкенд, а не устройство
Устройство не имеет права само заявлять, кто его пользователь. Опознание: это утверждение, подписанное вашим собственным бэкендом секретом личности, а приложение лишь передаёт непрозрачный результат:
- Приложение спрашивает у вашего бэкенда, кто оно.
- Бэкенд, который уже аутентифицировал пользователя, выпускает короткоживущий JWT, подписанный секретом личности.
- Приложение передаёт эту строку в
identify. SDK её не разбирает.
Сервер проверяет утверждение строго, и любое отклонение отвергает его целиком:
{
"alg": "HS256",
"project_key": "sdk1_eu_…",
"aud": "mybot-customer-sdk",
"jti": "3f2504e0-4f89-41d3-9a0c-0305e82c3301",
"iat": 1730000000,
"exp": 1730000120,
"user_id": "acct_10293",
"properties": { "plan": "pro", "role": "admin" }
}
- Алгоритм строго
HS256, аудитория строгоmybot-customer-sdk, полейiss,subиnbfбыть не должно. jti: канонический UUIDv4,iatне в будущем, время жизниexp - iat: не более 300 секунд.user_id: ваш непрозрачный стабильный идентификатор (1-256 байт), а не сырой email или телефон, введённый в форму на устройстве.propertiesнеобязательны, не более 16 записей, только из закрытого словаряaccount_id,plan,role,localeсо строковыми значениями до 256 байт.
Повторный identify для того же пользователя идемпотентен, для другого: переносит установку к нему. Сырые контактные данные через этот API не проходят: тот же закрытый словарь действует и для маршрута профиля, и для свойств из очереди.
Выход из аккаунта поднимает эпоху личности
Если на одном телефоне по очереди входят разные люди, сообщения первого не должны отправиться от имени второго. Для этого установка хранит номер текущего входа, эпоху личности. Он начинается с 1 и увеличивается на единицу при выходе из аккаунта. Сервер проверяет его при каждом запросе и сразу отклоняет запросы прежней эпохи:
- операции прежней эпохи из очереди отбрасываются и больше никогда не будут приняты: клиент их удаляет, а сервер всё равно отверг бы пачку целиком;
- локальный счётчик последовательности начинается заново с 1;
- открытый realtime-сокет закрывается сразу, а тикет, выпущенный до выхода, погасить уже нельзя;
- незавершённые отправки со старой эпохой отменяются;
- пуш-токены, зарегистрированные в прежней эпохе, отзывает сам сервер в той же транзакции, где поднимается эпоха. Приложению не нужно помнить об этом при выходе;
- кэши, привязанные к прежнему человеку (назначения контента, бейдж непрочитанного, сохранённые поля профиля), очищаются.
Про realtime стоит сказать отдельно: рукопожатие веб-сокета не может нести заголовок эпохи, который несёт обычный запрос. SDK получает одноразовый тикет по HTTPS, а в момент погашения сервер заново читает эпоху установки из базы и сравнивает её с эпохой, зафиксированной при выпуске тикета. Выход, случившийся в промежутке, отменяет апгрейд, даже если сам тикет ещё не использован. Именно поэтому вышедший из аккаунта клиент не попадёт в чужой диалог.
Обновление токена не означает выход: эпоха и пользователь сохраняются. Перечисленные очистки и отмены при таком обновлении не выполняются.
Офлайн-очередь
Операции, записанные без сети, уходят упорядоченными пачками. Каждая пачка несёт клиентский идентификатор, эпоху и непрерывный диапазон номеров.
| Операция | Что делает |
|---|---|
track_event | записывает продуктовое событие (на практике имя должно подходить под ^[a-z][a-z0-9_.]{0,63}$: действует более строгая из двух проверок) |
set_properties | задаёт свойства профиля из закрытого словаря account_id, plan, role, locale |
register_push_token | сохраняет токен APNs или FCM в зашифрованном виде (sandbox или production) |
revoke_push_token | отзывает токен; отзыв неизвестного токена: молчаливая успешная операция, а не ошибка |
notification_opened | аналитика открытия уведомления, best effort |
in_app_impression, in_app_action | квитанции по одному назначению in-app контента |
typing | индикация набора текста в чате |
Правила на сервере:
- 1-100 операций в пачке, номера продолжаются ровно с того места, где закончилась последняя принятая пачка. Разрыв или наложение отвергают пачку целиком.
- Пачка с идентификатором, уже принятым для этой установки и эпохи, отвечает «дубликат» и ничего не выполняет заново, поэтому повтор после потерянного ответа безопасен.
- Неверная эпоха отвергает пачку целиком, а всё остальное сообщается по каждой операции кодом из закрытого списка: одно плохое свойство не отбрасывает пачку хороших событий.
Локальные границы одинаковы на всех трёх платформах, чтобы телефон, неделями пробывший офлайн, не рос бесконечно. Первыми вытесняются самые старые ожидающие операции:
- 2000 операций в очереди на установку;
- 2 МиБ сериализованного хранилища очереди;
- 7 дней возраста: независимо от двух предыдущих границ.
Операция, которая прямо сейчас отправляется, не вытесняется никогда. На каждое вытеснение срабатывает диагностический колбэк с локальным идентификатором и причиной (количество, объём или возраст): без содержимого операции. Неудачные отправки повторяются от базы в 30 секунд с удвоением до 240 секунд и полным разбросом; отказ авторизации не повторяется никогда, потому что это заслон, а не сбой.
Чат
Если функция связанной истории сайта и приложения доступна и включена, iOS и Android SDK могут читать страницы истории сайта с метаданными обычных вложений и скачивать файлы размером до 32 МиБ. Скачивание требует действующей авторизованной сессии; публичные ссылки на файлы не выдаются. Приватная пересылка (private forwarding) пока не поддерживается. Чтение истории выполняется постранично: подписка на общие обновления в реальном времени и автоматическая отметка прочтения этим способом не предоставляются.
При открытом разделе связанной истории виджет сайта периодически проверяет новые сообщения, а также изменения и удаления уже загруженных сообщений из приложения. Мобильное приложение может проверять обновления через явные вызовы SDK; фонового опроса SDK не запускает. Это периодическая проверка, а не полноценный общий realtime. Прочтения и уведомления каждого канала остаются отдельными.
Для начального снимка используйте linkedWebHistorySnapshot на iOS или getLinkedWebHistorySnapshot на Android. Храните mutationCursor отдельно от page.nextAfter. При необходимости вызовите linkedWebHistoryUpdates / getLinkedWebHistoryUpdates с обоими курсорами и не более чем 500 ID отображаемых сообщений. Если hasMutations истинно, перечитайте показанный диапазон с through, сохранив исходную границу страницы, и учтите удаления. Если в пустой начальной странице нет nextAfter, передайте в after значение nil/null или пустую строку: SDK начнёт проверку с 0. На старом сервере mutationCursor может отсутствовать; после выхода из аккаунта сбросьте курсоры.
Чтобы отметить просмотр в мобильном приложении, явно вызовите markLinkedWebHistorySeen(messageIds:) на iOS или markLinkedWebHistorySeen(messageIds) на Android. Передавайте до 500 ID только тех входящих сообщений от сотрудника (direction: "in"), которые действительно показаны посетителю. В открытом видимом разделе связанной истории виджет сайта отмечает видимые сообщения автоматически. Это может отменить ещё не отправленное резервное письмо о непрочитанном ответе, но не отзывает уже отправленное письмо и не синхронизирует счётчик непрочитанного SDK-чата.
Для отдельного счётчика сообщений связанной истории сайта без подтверждённой отметки просмотра приложение вызывает linkedWebUnreadCount() на iOS или getLinkedWebUnreadCount() на Android. Учитываются сообщения сотрудника, созданные после подтверждения связи и не отмеченные просмотренными. Отметка фактически показанных сообщений влияет на следующий результат. Прочтение в основном SDK-чате может не учитываться, поэтому это не точный счётчик непрочитанного. nil/null означает, что сервер не поддерживает счётчик, а не ноль. Этот счётчик отделён от основного непрочитанного SDK-чата, не обновляется автоматически в фоне и не связан с push; приложение само решает, когда его запрашивать.
Если связка сайта и SDK доступна и включена на сервере (WEB_SDK_LINK_ENABLED, по умолчанию выключен), возможен общий просмотр снимка двух историй. Обычный чат остаётся доступен, а для операторов диалоги остаются отдельными. Снимок возвращает сообщения от новых к старым, разбивается на страницы через непрозрачный nextCursor и содержит безопасные блоки и метаданные обычных вложений. Флаг unsupportedBlocks: true означает, что часть содержимого не показана; приватная пересылка не поддерживается. Вложения скачиваются с авторизацией через downloadMergedHistoryAttachment.
Для сохранения общего снимка используйте versionedMergedWebHistory на iOS или getVersionedMergedWebHistory на Android. Сравнивайте linkVersion всех страниц и явно проверяйте его через mergedHistoryLinkVersion / getMergedHistoryLinkVersion перед повторным показом сохранённой истории и после возвращения в приложение. Если версия изменилась или доступ проверить не удалось, очистите сохранённые страницы, курсоры и вложения; после выхода из аккаунта они тоже недействительны. Общий просмотр не предоставляет общего realtime, не отмечает сообщения просмотренными и не запускает фоновый опрос.
В открытом и видимом общем снимке виджет периодически проверяет изменения и предлагает обновить историю вручную. Это ориентировочный сигнал, а не гарантированная очередь событий или realtime; операторские диалоги остаются отдельными.
В мобильном приложении вызовите observableMergedWebHistory на iOS или getObservableMergedWebHistory на Android для первой страницы и сохраните её непрозрачный updatesBaseline. Если он отсутствует, сервер не поддерживает эту проверку. По необходимости вызовите mergedWebHistoryChanges / getMergedWebHistoryChanges с этим baseline и не более чем 500 ID отображаемых сообщений. hasNew сообщает о новых сообщениях, hasChanged – о правках или удалениях среди переданных ID; содержимое ответ не возвращает. Проверка ориентировочная и может пропустить изменения, сохранённые одновременно; значение false не гарантирует актуальность снимка. Когда нужны актуальные данные, обновляйте историю. Сравните linkVersion с версией снимка и при несовпадении или невозможности проверки очистите страницы, курсоры и вложения. После обновления получите первую страницу с новым baseline. SDK не запускает фоновый опрос.
Чат: это веб-канал бота, увиденный с телефона: те же сообщения, тот же инбокс оператора, те же триггеры автоматизации при отправке.
- История листается вперёд от курсора, до 50 сообщений на страницу. Поле
directionуказано относительно клиента:in: от оператора или бота. - Отправка принимает клиентский идентификатор сообщения и отвечает «поставлено в очередь». Это значит «принято к доставке», а не «доставлено»: реальное состояние придёт через realtime или при следующем чтении истории. Повтор с тем же идентификатором и тем же текстом ничего не делает, повтор с другим текстом: конфликт и признак ошибки в приложении.
- Вложения загружаются по одному файлу, до 10 МиБ, дедуплицируются по хешу содержимого внутри бота и возвращаются готовой ссылкой.
- Непрочитанное считается для каждой установки по её собственному курсору, отдельно от прочтений оператора, и курсор движется только вперёд.
- Realtime передаёт новые, изменённые и удалённые сообщения и набор текста. При подключении сервер отдаёт пропущенное за время офлайна (до 50 кадров), а затем стримит живые события; курсора переподключения со стороны клиента нет.
Если владелец бота не подключал веб-канал, все маршруты чата отвечают, что чат для этого бота недоступен. Показывайте это как выключенную функцию, а не как временную ошибку.
In-app контент
GET /sdk/v1/content возвращает уже назначенные элементы: тип, приоритет, задержку, правила по визитам и частоте, блоки и оформление. Пустой список: нормальный ответ.
Кому что показывать, решает таргетинг. Поп-ап, у которого в таргетинге по устройствам нет мобильных, в SDK не попадёт никогда; поп-ап вообще без таргетинга по устройствам считается «для всех устройств» и попадёт. Вариант назначается детерминированно для конкретного человека, поэтому анонимный пользователь видит один и тот же вариант, пока identify или выход из аккаунта не пересчитают распределение заново.
Квитанции бывают трёх видов: impression, action и conversion. Смахнутое пользователем сообщение получает клиентское конечное состояние без серверного события, как и закрытый поп-ап на сайте.
Мобильные пуш-токены
register_push_token сохраняет токен APNs или FCM для текущей установки и эпохи личности. Токен хранится зашифрованным; revoke_push_token отзывает его. Отзыв неизвестного токена считается успешным, чтобы по ответу нельзя было проверить, зарегистрирован ли чужой токен. Данные об установке участвуют в выгрузке и удалении данных пользователя, но сами токены в выгрузку не попадают.
Конфигурация SDK сообщает pushEnabled: true: платформа поддерживает доставку мобильных пушей. Для фактической отправки администратор развёртывания должен настроить FCM; при наличии настроек APNs платформа может отправлять на iOS напрямую. Уведомление из опубликованного документа типа Push можно отправить через канал mobile_push в рассылке или кампании. Операторские уведомления кабинета используют другую аудиторию и другое хранилище устройств.
При выходе пользователя сервер отзывает активные пуш-токены прежней эпохи личности. После нового входа зарегистрируйте токен заново для новой эпохи. Отправка будет доступна только для активной установки с действующим токеном.
Ошибки
Любая ошибка /sdk/v1: это JSON-конверт с одним полем, и SDK классифицирует её по HTTP-статусу:
| Статус | Что означает | Что делает SDK |
|---|---|---|
400 | неверный локальный ввод | не повторяет, показывает как ошибку клиента |
401 | заслон авторизации: устаревшая эпоха, отозванный токен, неизвестный проект, использованный тикет | не повторяет с тем же credential |
404 | неизвестное или чужое назначение контента | удаляет как навсегда недействительное |
409 | чат недоступен для бота либо конфликт идемпотентности | показывает, не повторяет |
413 | вложение больше 10 МиБ | показывает до любых повторов |
500, 503 | временная ошибка | повторяет с выдержкой для идемпотентных операций |
Приватность и диагностика
Ни один маршрут SDK не возвращает сырые контактные данные, а словарь свойств закрыт от начала до конца. Диагностика выключена по умолчанию; включённая, она несёт только код события из закрытого списка, метку времени и очищенные числовые метаданные: никогда не токен, утверждение о личности, пуш-токен, ссылку и не содержимое сообщений, свойств или контента. Установки SDK относятся к категории хранения sdk_diagnostics со сроком по умолчанию 180 дней и участвуют в объединении подписчиков, выгрузке и удалении данных.
Контракт
Протокол обмена SDK описан отдельно от REST API владельца. Персональный токен не подходит для /sdk/v1, а токен установки не подходит для /api. Описание маршрутов в формате OpenAPI доступно без авторизации:
GET https://ваше-развёртывание/sdk/openapi.yaml
Правила поведения клиентов описаны в customer-sdk/contract/behavior.md мобильного репозитория: переходы между состояниями, порядок операций, пределы очереди, задержки повторов и обработка ошибок. Рядом находятся автоматически полученное описание серверных структур, перечислений, ограничений и шаблонов, а также 75 эталонных тестовых примеров, фикстур.
Скрипт повторно получает описание из копии бэкенда и сообщает об изменениях, которых нет в контракте. Тесты iOS, Android и React Native используют одни и те же примеры, чтобы проверять одинаковое поведение.
API и MCP
Маршруты управления проектом доступны по личному токену: см. REST API и токены. Для чтения нужны скоуп customer_sdk:read и право customer_sdk.read на бота. Для изменения нужны customer_sdk:write и customer_sdk.write; включение проекта и ротация секрета также требуют integrations.secrets. В MCP есть два инструмента только на чтение: см. MCP.
Что дальше
- Виджет на сайте: тот же диалог на вашем сайте.
- Пуш в браузере: уведомления для посетителей сайта, у которых отправитель есть.
- Контент-студия: документы, которые показывает in-app контент.