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

Справочник мобильных SDK

Все публичные классы, методы и свойства SDK Android (ru.shtab.helpdesk) и iOS (ShtabHelpdesk) версии 1.0.0-beta.2. Как встроить чат по шагам — в руководствах Android и iOS. Вкладка языка запоминается для всей страницы.

Весь API вызывается из главного потока: в Kotlin методы помечены @MainThread, в Swift HelpdeskSDK — @MainActor.

Инициализация​

SDK настраивается один раз при старте приложения: адрес установки (только origin, https) и ключ размещения приложения из Интеграции → Мобильные приложения. Обычный http:// принимается только в отладочной сборке приложения — для стенда.

СимволЧто делает
HelpdeskSdkТочка входа SDK — объект: настройка, вход пользователя, экран чата, push. Методы доступны из Java как статические.
HelpdeskSdk.configure(context, installationUrl, placementKey, options)Настраивает SDK: установка, ключ размещения и необязательные HelpdeskOptions. Неверный адрес, ключ, язык, версия приложения или пин — IllegalArgumentException.
HelpdeskSdk.isConfiguredtrue, если configure уже вызван. openChat, registerPushToken, handleNotification и logout до настройки бросают IllegalStateException.
HelpdeskSdk.VERSIONВерсия SDK (semver), например 1.0.0-beta.2.
HelpdeskSdk.BRIDGE_VERSIONВерсия моста между SDK и интерфейсом чата: установка, не поддерживающая её, получает вшитый интерфейс.
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        HelpdeskSdk.configure(
            this,
            installationUrl = "https://support.example.com",
            placementKey = "pk_…",
            options = HelpdeskOptions(appVersion = BuildConfig.VERSION_NAME),
        )
    }
}

Параметры​

Все параметры необязательны.

СимволЧто делает
HelpdeskOptionsПараметры configure; из Java — перегрузки конструктора.
HelpdeskOptions.localeru или en, пока окно размещения не назовёт свой язык; null — русский.
HelpdeskOptions.appVersionВерсия приложения для диагностики регистраций push, например 2.4.1.
HelpdeskOptions.certificatePinsПины ключей установки sha256/<base64>, их даёт администратор установки; пусто — без пиннинга. Что они покрывают — в руководстве.
HelpdeskOptions.loggerКуда идёт диагностика; null — Logcat, только предупреждения и ошибки.
HelpdeskLoggerПриёмник диагностики — функциональный интерфейс.
HelpdeskLogger.log(level, code)Получает уровень и код (ui.bundled.offline, token.timeout…) — никогда текст сообщений, токены или персональные данные.
LogLevelУровень диагностического кода.
LogLevel.DEBUGОтладочный код.
LogLevel.INFOСведения о работе, например ui.installation — открыт интерфейс установки.
LogLevel.WARNПредупреждение; по умолчанию попадает в Logcat.
LogLevel.ERRORОшибка; по умолчанию попадает в Logcat.
HelpdeskOptions(
    locale = "ru",
    appVersion = BuildConfig.VERSION_NAME,
    logger = HelpdeskLogger { level, code -> analytics.log("helpdesk", level.name, code) },
)

Вход пользователя​

Пользователь приложения входит в чат токеном чата (chat token): его подписывает бэкенд приложения для своего вошедшего пользователя — iss, aud = ключ размещения, sub, exp не дольше 10 минут, jti. SDK просит токен при каждом открытии чата и когда сессия чата закончилась, использует один раз и не хранит. Нет ответа за 15 секунд — чат открывается без входа. Поля токена — те же, что у виджета.

СимволЧто делает
HelpdeskSdk.setChatTokenProvider(provider)Откуда SDK берёт токен чата; null — нет вошедшего пользователя, доступны только гостевые размещения.
ChatTokenProviderПоставщик токена чата — функциональный интерфейс.
ChatTokenProvider.requestChatToken(callback)SDK просит свежий токен; ответить в callback один раз, из любого потока.
ChatTokenCallbackОтвет поставщика.
ChatTokenCallback.onChatToken(chatToken)Токен или null, если в приложении никто не вошёл: чат попросит войти в приложении снова.
HelpdeskSdk.logout()Пользователь вышел: экран чата закрывается, сессия завершается на сервере (он отключает push устройства), данные чата в WebView удаляются. Без сети сервер узнает об этом при следующем configure.
HelpdeskSdk.setChatTokenProvider { callback ->
    backend.issueSupportToken { token -> callback.onChatToken(token) }
}

// Пользователь вышел из приложения
HelpdeskSdk.logout()

Экран чата​

СимволЧто делает
HelpdeskSdk.openChat(activity)Открывает экран чата поверх activity. Обращение из нажатого push открывается в нём после входа пользователя.
HelpdeskChatActivityЭкран чата: WebView с интерфейсом установки или вшитым. Объявлен в манифесте SDK; открывается только через openChat.
supportButton.setOnClickListener { HelpdeskSdk.openChat(this) }

Push​

Сервер шлёт push без текста сообщения: заголовок «Новый ответ» на языке размещения и данные conversation_id и kind (new_reply, у проверки из консоли — test). Обращение из push открывается только после входа пользователя в чат.

СимволЧто делает
HelpdeskSdk.registerPushToken(token)FCM registration token устройства (onNewToken и при старте): SDK хранит его под защитой Keystore и регистрирует при каждом входе в чат.
HelpdeskSdk.handleNotification(intent, activity)Нажатие на уведомление принесло intent: true, если это push установки. С activity чат открывается сразу, без неё — при следующем openChat.
HelpdeskNotificationsПомощники для push установки.
HelpdeskNotifications.KEY_CONVERSATION_IDКлюч conversation_id в data push.
HelpdeskNotifications.KEY_KINDКлюч kind в data push.
HelpdeskNotifications.DEFAULT_CHANNEL_IDКанал уведомлений SDK — shtab_helpdesk; свой канал называют в настройках FCM в консоли.
HelpdeskNotifications.isHelpdeskPush(data)Это data FCM — push установки?
HelpdeskNotifications.createChannel(context, name, channelId)Создаёт канал уведомлений; name пользователь видит в настройках приложения.
HelpdeskNotifications.show(context, data, smallIcon, title, text, channelId)Показывает push, пришедший, пока приложение на экране: нажатие откроет launch activity с ключами push. false — push не наш или уведомления выключены.
class Messaging : FirebaseMessagingService() {
    override fun onNewToken(token: String) {
        Handler(Looper.getMainLooper()).post { HelpdeskSdk.registerPushToken(token) }
    }

    override fun onMessageReceived(message: RemoteMessage) {
        if (HelpdeskNotifications.isHelpdeskPush(message.data)) {
            HelpdeskNotifications.show(this, message.data, R.drawable.ic_notification)
        }
    }
}

// Launcher activity: нажатие на уведомление приносит ключи push в intent
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    HelpdeskSdk.handleNotification(intent, this)
}

События​

Непрочитанные ответы в открытом чате и отклонённый токен чата приходят в главном потоке.

СимволЧто делает
HelpdeskSdk.setEventListener(listener)Подписывает приложение на события чата; null — отписаться.
HelpdeskEventListenerСлушатель событий; у методов есть пустые реализации по умолчанию.
HelpdeskEventListener.onUnreadChanged(count)Изменилось число непрочитанных ответов в открытом чате; 0 — прочитаны.
HelpdeskEventListener.onSessionExpired()Токен чата отклонён: пользователь не войдёт в чат, пока поставщик не выдаст новый.
HelpdeskSdk.setEventListener(object : HelpdeskEventListener {
    override fun onUnreadChanged(count: Int) {
        badge.text = count.toString()
    }
})

Отладка​

Помощники проверяют обработку push и переход к обращению до того, как придут настоящие push. Работают только в отладочной сборке приложения.

СимволЧто делает
HelpdeskDebugОтладочные помощники; в релизной сборке методы бросают IllegalStateException.
HelpdeskDebug.testPushData(context, conversationId)data, который шлёт сервер: с обращением — new_reply, без него — test.
HelpdeskDebug.testNotificationIntent(context, conversationId)Launch intent, который приносит приложению нажатие на такой push: его передают в handleNotification.
HelpdeskSdk.handleNotification(HelpdeskDebug.testNotificationIntent(context, conversationId), activity)

Ошибки​

SDK Android сообщает о неверном вызове стандартными исключениями: IllegalArgumentException — неверный адрес, ключ, параметр или push-токен, IllegalStateException — вызов до configure или отладочный помощник в релизной сборке. В iOS ошибки — HelpdeskError.

Своих типов ошибок в SDK Android нет.