Android SDK

Anforderungen#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x und Jetpack Compose (das SDK liefert Compose-UI mit).
• JVM-Target 17.

Das SDK zieht seine eigenen transitiven Abhängigkeiten (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) und deklariert die Berechtigung INTERNET in seinem Manifest — nichts von Hand hinzuzufügen.

Installation#

Die Bibliothek wird auf Maven Central als ai.respondo:respondo-sdk veröffentlicht. Stellen Sie sicher, dass mavenCentral() in Ihren Repositories steht (in einem neuen Android-Projekt ist es das standardmäßig), und fügen Sie dann die Abhängigkeit über ihre Koordinate hinzu.

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

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

Initialisieren#

Rufen Sie Respondo.init einmal auf, hängen Sie RespondoChatHost() einmal in Ihren Compose-Baum ein und öffnen Sie den Chat über Ihren eigenen Button.

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>",   // aus dem Dashboard
                channelId = "<channel-uuid>", // optional
                // baseUrl weggelassen -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // SDK zeigt das Sheet, wenn der Chat-Status OPEN ist
                }
            }
        }
    }
}

Alle Aufrufe laufen über das Singleton Respondo. Sie sind idempotent, aus jedem Thread sicher, und Aufrufe, die vor Abschluss der Init erfolgen, werden gepuffert und erneut abgespielt.

Nutzer identifizieren#

Standardmäßig ist jeder Besucher anonym. Beim ersten Start generiert das SDK eine stabile visitor_id und bewahrt sie im lokalen Speicher auf, sodass ein wiederkehrender Nutzer seine Konversation erneut findet. Es gibt keinen API-Schlüssel einzubetten — jede Konversation ist durch ein Session-Token pro Konversation geschützt, das das Backend prägt und bei jeder Nachricht weiterschiebt, sodass sich ein anonymer Besucher nie erneut authentifizieren muss.

Rufen Sie identify auf, sobald Ihr Nutzer angemeldet ist. Dies hängt seine reale Identität an, sodass sein Verlauf ihm geräte- und neuinstallationsübergreifend folgt und sein Name und seine E-Mail neben der Konversation in Ihrem Posteingang erscheinen statt eines anonymen Besuchers.

Der userHash ist eine Signatur, die Ihr Backend aus dem identity_secret des Agenten berechnet — HMAC-SHA256(secret, userId) (oder die E-Mail, wenn es keine userId gibt), kodiert als Hex in Kleinbuchstaben. Das Secret beweist, dass die Identität echt ist, daher muss es ausschließlich auf Ihrem Backend liegen und wird niemals in der App ausgeliefert. Auf der Seite Identitätsverifizierung finden Sie die vollständige Formel und serverseitige Beispiele.

import ai.respondo.sdk.RespondoIdentity

// Der userHash kommt von Ihrem Backend (HMAC-SHA256 über die userId) —
// berechnen Sie ihn niemals in der App.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
    ),
)

// Beim Logout: Push-Token verwerfen, Session widerrufen, neuen anonymen Besucher starten.
Respondo.clearPushToken()
Respondo.reset()

Wenn der Hash fehlt oder falsch ist, wird nichts geworfen: Das Backend hält den Besucher stillschweigend anonym, der Chat funktioniert weiter, und Sie verlieren lediglich die geräteübergreifende Verknüpfung, bis ein gültiger Hash geliefert wird. Die Verifizierung läuft nur, wenn für den Agenten ein identity_secret gesetzt ist — lassen Sie es während der Entwicklung leer, und userId / E-Mail werden unverändert akzeptiert.

Observables & Callbacks#

Lesen Sie den Zustand reaktiv als StateFlow (ideal für Compose) oder imperativ über RespondoListener (ideal für ein App-Icon-Badge).

// Reaktiv: Anzahl ungelesener Nachrichten als StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Imperativ: Listener für Badges und Analytics.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Bildschirm-Tracking#

Melden Sie den aktuellen Bildschirm bei jeder Navigation, damit proaktive Teaser und Targeting auf Seitenebene dagegen abgleichen können. Übergeben Sie null, um ihn zu löschen; bei jeder Änderung wird der proaktive Teaser für den neuen Bildschirm neu ausgewertet.

Respondo.setCurrentScreen("pricing")

Nächste Schritte#

Richten Sie Push-Benachrichtigungen für Offline-Antworten von Mitarbeitern und die Identitätsverifizierung für angemeldete Nutzer ein. Die vollständige API-Oberfläche, der Fragment-Wrapper für XML-Hosts und die Fehlerbehebung werden im Einstiegsleitfaden des Android SDK behandelt; die SDK-Quellen sind öffentlich auf GitHub.