Dokumentacja

Android SDK

Cienki klient Kotlin i Jetpack Compose, który otwiera czat wsparcia Respondo jako dolny arkusz (bottom sheet) nad Twoją aplikacją.

Wymagania

  • minSdk 24 (Android 7.0), compileSdk 35.
  • Kotlin 2.x i Jetpack Compose (SDK dostarcza UI oparte na Compose).
  • Cel JVM 17.

SDK pobiera własne zależności przechodnie (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) i deklaruje uprawnienie INTERNET w swoim manifeście — nie trzeba niczego dodawać ręcznie.

Instalacja

Biblioteka jest opublikowana w Maven Central jako ai.respondo:respondo-sdk. Upewnij się, że mavenCentral() jest w Twoich repozytoriach (domyślnie tak jest w nowym projekcie Androida), a następnie dodaj zależność według współrzędnych.

settings.gradle.ktskotlin
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
    }
}
app/build.gradle.ktskotlin
dependencies {
    implementation("ai.respondo:respondo-sdk:0.3.0")
}

Inicjalizacja

Wywołaj Respondo.init raz, zamontuj RespondoChatHost() raz w swoim drzewie Compose i otwieraj czat z własnego przycisku.

MainActivity.ktkotlin
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>",   // z panelu
                channelId = "<channel-uuid>", // Settings › Channels › Mobile SDK
                // baseUrl pominięty -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // SDK pokazuje arkusz, gdy stan czatu to OPEN
                }
            }
        }
    }
}

Wszystkie wywołania przechodzą przez singleton Respondo. Są idempotentne, bezpieczne z dowolnego wątku, a wywołania wykonane przed zakończeniem inicjalizacji są buforowane i odtwarzane.

Identyfikacja użytkowników

Domyślnie każdy odwiedzający jest anonimowy. Przy pierwszym uruchomieniu SDK generuje stabilny visitor_id i przechowuje go w pamięci lokalnej, dzięki czemu powracający użytkownik odnajduje swoją rozmowę. Nie ma klucza API do osadzenia — każda rozmowa jest chroniona tokenem sesji przypisanym do rozmowy, który backend generuje i przesuwa do przodu przy każdej wiadomości, więc anonimowy odwiedzający nigdy nie musi się ponownie uwierzytelniać.

Wywołaj identify, gdy użytkownik się zaloguje. Powiązuje to jego prawdziwą tożsamość, dzięki czemu historia podąża za nim między urządzeniami i po ponownej instalacji, a jego imię i e-mail pojawiają się obok rozmowy w Twojej skrzynce zamiast anonimowego odwiedzającego.

userHash to podpis, który Twój backend oblicza z identity_secret agenta — HMAC-SHA256(secret, userId) (lub e-mail, gdy nie ma userId), zakodowany jako małe litery hex. Sekret dowodzi autentyczności tożsamości, więc musi żyć wyłącznie na Twoim backendzie i nigdy nie jest dostarczany w aplikacji. Pełny wzór i przykłady po stronie serwera znajdziesz na stronie Weryfikacja tożsamości.

Kotlin
import ai.respondo.sdk.RespondoIdentity

// userHash pochodzi z Twojego backendu (HMAC-SHA256 z userId) —
// nigdy nie obliczaj go w aplikacji.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
        signedUpAt = session.signedUpAt,
    ),
)

// Przy wylogowaniu: usuń token push, unieważnij sesję, rozpocznij świeżego anonimowego odwiedzającego.
Respondo.clearPushToken()
Respondo.reset()

Jeśli hash jest brakujący lub błędny, nic nie zgłasza wyjątku: backend po cichu utrzymuje odwiedzającego jako anonimowego, czat nadal działa, a Ty po prostu tracisz powiązanie między urządzeniami do momentu dostarczenia poprawnego hasha. Weryfikacja działa tylko, gdy agent ma ustawiony identity_secret — pozostaw go pustym podczas developmentu, a userId / e-mail są akceptowane bez zmian.

Obserwowalne i callbacki

Odczytuj stan reaktywnie jako StateFlow (świetne dla Compose) lub imperatywnie przez RespondoListener (świetne dla plakietki na ikonie aplikacji).

Kotlin
// Reaktywnie: liczba nieprzeczytanych jako StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Imperatywnie: listener dla plakietek i analityki.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Śledzenie ekranu

Zgłaszaj bieżący ekran przy każdej nawigacji, aby proaktywne zajawki i targetowanie na poziomie strony mogły się do niego dopasować. Przekaż null, aby go wyczyścić; przy każdej zmianie proaktywna zajawka jest ponownie oceniana dla nowego ekranu.

Ta sama nazwa jest porównywana z regułami ekranów ankiet pop-up, więc używaj stałych identyfikatorów, takich jak «Checkout», a nie przetłumaczonych tytułów. Reguły adresów stron działają tylko na stronach internetowych.

Kotlin
Respondo.setCurrentScreen("pricing")

Otwieranie ankiety z kodu

Otwiera od razu aktywną ankietę pop-up, niezależnie od ekranu, na którym jest użytkownik, pomijając Show on, reguły ekranów, czas na ekranie, zdarzenie wyzwalające i grupę odbiorców. Identyfikator skopiuj z edytora ankiety (Additional ways to share). Ankieta, na którą użytkownik już odpowiedział, nie pojawi się ponownie.

Kotlin
Respondo.startSurvey("<survey-id>")

Następne kroki

Skonfiguruj powiadomienia push dla odpowiedzi operatorów w trybie offline oraz weryfikację tożsamości dla zalogowanych użytkowników. Pełna powierzchnia API, wrapper Fragment dla hostów XML oraz rozwiązywanie problemów są opisane w przewodniku wprowadzającym Android SDK; źródła SDK są publicznie dostępne na GitHub.