SDK Android

Prérequis#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x et Jetpack Compose (le SDK fournit une UI Compose).
• Cible JVM 17.

Le SDK récupère ses propres dépendances transitives (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) et déclare la permission INTERNET dans son manifeste — rien à ajouter à la main.

Installation#

La bibliothèque est publiée sur Maven Central sous ai.respondo:respondo-sdk. Assurez-vous que mavenCentral() figure dans vos dépôts (c’est le cas par défaut dans un nouveau projet Android), puis ajoutez la dépendance par ses coordonnées.

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

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

Initialiser#

Appelez Respondo.init une fois, montez RespondoChatHost() une fois dans votre arbre Compose, et ouvrez le chat depuis votre propre bouton.

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>",   // depuis le tableau de bord
                channelId = "<channel-uuid>", // optionnel
                // baseUrl omis -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // le SDK affiche la feuille quand l'état du chat est OPEN
                }
            }
        }
    }
}

Tous les appels passent par le singleton Respondo. Ils sont idempotents, sûrs depuis n’importe quel thread, et les appels effectués avant la fin de l’initialisation sont mis en tampon et rejoués.

Identifier les utilisateurs#

Par défaut, chaque visiteur est anonyme. Au premier lancement, le SDK génère un visitor_id stable et le conserve dans le stockage local, si bien qu’un utilisateur de retour retrouve sa conversation. Aucune clé d’API à intégrer — chaque conversation est protégée par un jeton de session propre à la conversation, que le backend émet et fait glisser à chaque message, de sorte qu’un visiteur anonyme n’a jamais à se réauthentifier.

Appelez identify une fois votre utilisateur connecté. Cela rattache son identité réelle, de sorte que son historique le suit d’un appareil à l’autre et après réinstallation, et que son nom et son e-mail apparaissent à côté de la conversation dans votre boîte de réception au lieu d’un visiteur anonyme.

Le userHash est une signature que votre backend calcule à partir de l’ identity_secret de l’agent — HMAC-SHA256(secret, userId) (ou l’e-mail lorsqu’il n’y a pas de userId), encodée en hexadécimal minuscule. Le secret prouve que l’identité est authentique ; il doit donc résider uniquement sur votre backend et n’est jamais livré dans l’application. Consultez la page Vérification d’identité pour la formule complète et des exemples côté serveur.

import ai.respondo.sdk.RespondoIdentity

// Le userHash provient de votre backend (HMAC-SHA256 sur le userId) —
// ne le calculez jamais dans l'application.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
    ),
)

// À la déconnexion : supprimez le token push, révoquez la session, démarrez un nouveau visiteur anonyme.
Respondo.clearPushToken()
Respondo.reset()

Si le hash est manquant ou incorrect, rien n’est levé : le backend garde silencieusement le visiteur anonyme, le chat continue de fonctionner, et vous perdez simplement le lien inter-appareils jusqu’à ce qu’un hash valide soit fourni. La vérification ne s’exécute que lorsque l’agent a un identity_secret défini — laissez-le vide pendant le développement et userId / e-mail sont acceptés tels quels.

Observables et callbacks#

Lisez l’état de façon réactive via StateFlow (idéal pour Compose) ou de façon impérative via RespondoListener (idéal pour un badge sur l’icône de l’application).

// Réactif : le nombre de messages non lus sous forme de StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Impératif : listener pour les badges et l'analytique.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Suivi d’écran#

Signalez l’écran courant à chaque navigation pour que les accroches proactives et le ciblage par page puissent s’y référer. Passez null pour l’effacer ; à chaque changement, l’accroche proactive est réévaluée pour le nouvel écran.

Respondo.setCurrentScreen("pricing")

Étapes suivantes#

Configurez les Notifications push pour les réponses des agents hors ligne et la Vérification d’identité pour les utilisateurs connectés. La surface d’API complète, le wrapper Fragment pour les hôtes XML et le dépannage sont couverts dans le guide de démarrage du SDK Android ; les sources du SDK sont publiques sur GitHub.