Android SDK

Вимоги#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x і Jetpack Compose (SDK постачає UI на Compose).
• Ціль JVM 17.

SDK підтягує власні транзитивні залежності (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) і оголошує дозвіл INTERNET у своєму маніфесті — вручну додавати нічого не треба.

Встановлення#

Бібліотека опублікована в Maven Central як ai.respondo:respondo-sdk. Переконайтеся, що mavenCentral() є у ваших репозиторіях (у новому Android-проєкті він там за замовчуванням), потім додайте залежність за координатою.

dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}

dependencies {
    implementation("ai.respondo:respondo-sdk:0.1.0")
}

Ініціалізація#

Викличте Respondo.init один раз, змонтуйте RespondoChatHost() один раз у своєму дереві Compose й відкривайте чат зі своєї власної кнопки.

import ai.respondo.sdk.Respondo
import ai.respondo.sdk.RespondoConfig
import ai.respondo.sdk.ui.RespondoChatHost

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        Respondo.init(
            context = this,
            config = RespondoConfig(
                agentId = "<agent-uuid>",   // з дашборда
                channelId = "<channel-uuid>", // необов’язково
                // baseUrl пропущено -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // SDK показує панель, коли стан чату OPEN
                }
            }
        }
    }
}

Усі виклики йдуть через синглтон Respondo. Вони ідемпотентні, безпечні з будь-якого потоку, а виклики, зроблені до завершення init, буферизуються й відтворюються.

Ідентифікація користувачів#

За замовчуванням кожен відвідувач анонімний. Під час першого запуску SDK генерує стабільний visitor_id і тримає його в локальному сховищі, тож користувач, який повернувся, знову знаходить свою розмову. Ключа API вбудовувати не потрібно — кожна розмова захищена посесійним токеном на розмову, який бекенд карбує й зсуває вперед на кожному повідомленні, тож анонімному відвідувачеві ніколи не доводиться повторно автентифікуватися.

Викличте identify, щойно ваш користувач залогінився. Це прив’язує його реальну особу, тож його історія супроводжує його на різних пристроях і при перевстановленнях, а його ім’я та email з’являються поруч із розмовою у вашій спільній скриньці замість анонімного відвідувача.

userHash — це підпис, який ваш бекенд обчислює з identity_secret агента — HMAC-SHA256(secret, userId) (або email, коли userId немає), закодований як hex у нижньому регістрі. Секрет доводить, що особа справжня, тож він має жити лише на вашому бекенді й ніколи не постачається в застосунку. Повну формулу й приклади на боці сервера дивіться на сторінці Верифікація особи.

import ai.respondo.sdk.RespondoIdentity

// userHash приходить з вашого бекенду (HMAC-SHA256 над userId) —
// ніколи не обчислюйте його в застосунку.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
    ),
)

// При виході: скиньте push-токен, відкличте сесію, почніть нового анонімного відвідувача.
Respondo.clearPushToken()
Respondo.reset()

Якщо хеш відсутній або хибний, нічого не падає з винятком: бекенд мовчки залишає відвідувача анонімним, чат далі працює, і ви просто втрачаєте зв’язок між пристроями, доки не буде надано валідний хеш. Верифікація виконується лише тоді, коли в агента заданий identity_secret — залиште його порожнім під час розробки, і userId / email приймаються як є.

Обсервабли й колбеки#

Читайте стан реактивно як StateFlow (чудово для Compose) або імперативно через RespondoListener (чудово для бейджа на іконці застосунку).

// Реактивно: кількість непрочитаних як StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Імперативно: слухач для бейджів і аналітики.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Відстеження екранів#

Повідомляйте поточний екран під час кожної навігації, щоб проактивні тизери й таргетинг рівня сторінки могли з ним зіставлятися. Передайте null, щоб очистити його; після кожної зміни проактивний тизер переоцінюється для нового екрана.

Respondo.setCurrentScreen("pricing")

Наступні кроки#

Налаштуйте Push-сповіщення для офлайн-відповідей операторів і Верифікацію особи для залогінених користувачів. Повна поверхня API, обгортка Fragment для XML-хостів і розв’язання проблем описані в посібнику з початку роботи з Android SDK; вихідні коди SDK відкриті на GitHub.