Документация Мобильный SDK SDK 0.1.0
SDK 0.1.0

Мобильный SDK

Как подключить чат поддержки Revback к мобильному приложению — Android и iOS. Нужны две вещи: наш SDK в приложении и, для уведомлений, Firebase-проект самого приложения.

Что делает SDK

Версия0.1.0
ПлатформыAndroid — Maven Central: revback-chat-ui (готовый экран) и revback-chat-core (ядро); iOS — Swift-пакет RevbackChat: продукты RevbackChatUI и RevbackChatCore
ТехнологияНативные библиотеки: Android — Jetpack Compose, iOS — SwiftUI; ничего дополнительно ставить не нужно
Адрес APIhttps://api.revback.ai
Что делаетГотовый экран чата в виде виджета вашего сайта, лента и отправка с вложениями, уведомления о новых сообщениях через Firebase, стабильный id пользователя чата

Готовый экран чата входит в SDK; кто рисует чат сам — подключает только ядро. Firebase SDK подключает само приложение: модуль Firebase за собой не тянет.

Шаг 1. Подключить SDK

Android — зависимость из Maven Central. iOS — пакет через Swift Package Manager.

Kotlin
// build.gradle.kts — репозиторий mavenCentral() в проекте уже есть
implementation("ai.revback:revback-chat-ui:0.1.0")     // готовый экран чата, ядро внутри

// только ядро — если экран чата рисуете сами
implementation("ai.revback:revback-chat-core:0.1.0")

Шаг 2. Инициализация с ключом

Один вызов при старте приложения — ключ канала лежит в конфиге SDK.

Kotlin
// Application.onCreate
RevbackChat.init(this, RevbackChatConfig(widgetKey = "ваш ключ"))

Где взять ключ: кабинет Revback → Каналы → «Чат в приложении» → поле «Ключ канала».

  • DEFAULT_API_BASE_URL — это https://api.revback.ai.
  • В Swift параметры конфига указываются все — значений по умолчанию у них нет.
  • Любой вызов до init / configure безопасен: no-op с логом.
  • setPushToken буферизует токен.
  • API ничего не бросает.

Шаг 3. Экран чата

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

Kotlin
// открыть готовый экран поверх приложения — по тапу на «Поддержка» или по уведомлению
RevbackChatUI.open(context)

// или встроить в свою навигацию (Compose)
RevbackChatScreen(onClose = { navController.popBackStack() })
  • Вызов до init / configure — лог и no-op; повторный present при показанном экране — тоже.
  • onClose = null — крестика в шапке нет: экран закрывает приложение.
  • Экран сам сообщает ядру, когда чат на экране: пока он открыт, уведомления о новых сообщениях не показываются.
  • Тема у экрана своя, светлая — как у виджета сайта; Material приложения не наследуется.
  • Android: Jetpack Compose без Material; просмотр вложений через собственный FileProvider — настройки не требует.
  • iOS: минимум iOS 15; libsqlite3 и NSPhotoLibraryUsageDescription добавлять не нужно — пакет линкует библиотеку сам, а выбор фото идёт через системный пикер без доступа к медиатеке.

Свой экран — на ядре: RevbackChat.conversation даёт open() / close(), ленту messages, send(), вложения через upload()send(), loadMore(), markRead(). На Android это потоки, на iOS данные приходят через RevbackChatDelegate.

Шаг 4. Уведомления

Токен уходит в Revback, входящие уведомления проходят через SDK: он сам отвечает, его это пуш или ваш.

Kotlin
// FirebaseMessagingService
override fun onNewToken(token: String) = RevbackChat.setPushToken(token)
override fun onMessageReceived(message: RemoteMessage) {
    when (RevbackChat.onMessageReceived(this, message.data)) {   // показ — внутри
        is PushAction.NotOurs -> handleOwnPush(message)            // пуши самого приложения
        else -> Unit
    }
}

// при старте (Google рекомендует getToken() на каждом старте)
FirebaseMessaging.getInstance().token.addOnSuccessListener { RevbackChat.setPushToken(it) }

// Activity.onCreate / onNewIntent — тап по уведомлению открывает чат
if (RevbackChat.conversationId(intent) != null) RevbackChatUI.open(this)
  • Разрешение POST_NOTIFICATIONS (Android 13+) объявляет и запрашивает приложение.
  • Канал уведомлений revback_support создаёт модуль.
  • Иконка: RevbackChatNotifications.smallIconOverride = R.drawable.ic_notification.
  • Строки: английские по умолчанию, русские в values-ru; другие языки — те же имена ресурсов в своём values-xx.

Строки пуша в главном бандле (iOS)

Четыре ключа в Localizable.strings приложения:

Localizable.strings iOS
"revback.push.visitor.new_message.title_brand" = "%@";
"revback.push.visitor.new_message.body_contentless" = "Новое сообщение от поддержки";
"revback.push.visitor.test.title" = "Тест уведомлений";
"revback.push.visitor.test.body" = "Пуши из чата поддержки доходят";

APNs резолвит loc-key по главному бандлу: отсутствующий ключ iOS показывает буквально.

Шаг 5. Ключ APNs для iPhone

В консоли Firebase обязателен APNs Auth Key (.p8): Project settings → Cloud Messaging. Без него FCM отвечает THIRD_PARTY_AUTH_ERROR, а проверка ключа в кабинете этого не видит.

К нам .p8 загружать не нужно.

Файл сервисного аккаунта Firebase (JSON) в кабинет загружает владелец канала — строка «Ключ Firebase» в настройках канала. Разработчику достаточно знать: без него пуши не уйдут.

Шаг 6. Проверка — тест уведомлений

У SDK есть RevbackChat.debugInfo — версия, ключ, visitorId, installId, последний токен, lastTokenSync. И RevbackChat.sendTestPush() — сквозной тест доставки на это устройство.

Кнопки теста в SDK нет: sendTestPush() вызывает само приложение — например, с отладочного экрана.

Kotlin
val result = RevbackChat.sendTestPush()   // suspend

Что должно получиться. PUT push-token при старте → push-test → уведомление на экране блокировки. Повтор в течение минуты → 429 и Retry-After: это норма, троттл.

Под капотом: POST /v1/widget/{key}/push-test, троттл 60 секунд.

Шаг 7. Исходы теста

Что вернул sendTestPush() и что с этим делать.

РезультатЧто случилосьЧто делать
Accepted 202, конверт ушёл в FCM смотреть шторку устройства
Rejectedreason = WidgetKeyMismatch ключ в конфиге SDK не совпадает с инстансом (и после пересборки сессии) проверить widgetKey
Rejectedreason = PushUnsupported тип канала без визиторских пушей канал в кабинете должен быть «Чат в приложении»
Rejectedreason = ChannelInactive канал на паузе или заморожен биллингом снять паузу в кабинете, SDK ни при чём
Rejectedreason = NoTokenRegistered для этой установки нет подписки дождаться lastTokenSync.registered == true
Rejectedreason = TokenGone FCM больше не знает токен перезапросить у Firebase, setPushToken
Rejectedreason = RejectedByFcm(code) SENDER_ID_MISMATCH — токен из другого Firebase-проекта; THIRD_PARTY_AUTH_ERROR — нет APNs-ключа сверить google-services.json / GoogleService-Info.plist, залить .p8
Rejectedreason = Unknown(detail) новый код бэка, SDK его ещё не знает показать detail как есть
TooManyRequests(retryAfterSeconds) 429, троттл подождать
PushUnavailable(detail) 503: push unavailable: no_credentials (JSON не загружен) или push unavailable: push_disabled чинится в кабинете
Failed(message) нет сессии/сети, 404 (канал удалён), 502 (Google недоступен — повторить) по тексту

Дополнительно

Android Auto Backupid визитёра лежит в shared_prefs/revback_chat_visitor.xml — включите его в свои backup-rules, иначе переустановка = новый визитёр и потерянная переписка.
RevbackChat.conversation.open() / close()чат на экране / закрыт — нужно только своему экрану, готовый делает это сам.
RevbackChat.setTokenSyncListener { result -> … }диагностика регистрации токена.
data.vendor == "revback", data.surface == "visitor"различитель пушей.