Android SDK

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.

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

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

Inicjalizacja#

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

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>", // opcjonalnie
                // 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.

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,
    ),
)

// 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).

// 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.

Respondo.setCurrentScreen("pricing")

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.