Android SDK

Requisiti#

• minSdk 24 (Android 7.0), compileSdk 35.
• Kotlin 2.x e Jetpack Compose (l’SDK include la UI Compose).
• Target JVM 17.

L’SDK porta con sé le proprie dipendenze transitive (Coroutines, kotlinx.serialization, OkHttp, Coil, Compose) e dichiara il permesso INTERNET nel proprio manifest — non c’è nulla da aggiungere a mano.

Installazione#

La libreria è pubblicata su Maven Central come ai.respondo:respondo-sdk. Assicurati che mavenCentral() sia tra i tuoi repository (lo è per impostazione predefinita in un nuovo progetto Android), poi aggiungi la dipendenza per coordinate.

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

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

Inizializzazione#

Chiama Respondo.init una volta, monta RespondoChatHost() una volta nel tuo albero Compose e apri la chat dal tuo pulsante.

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>",   // dalla dashboard
                channelId = "<channel-uuid>", // opzionale
                // baseUrl omesso -> https://api.respondo.ai
            ),
        )

        setContent {
            MaterialTheme {
                Box(modifier = Modifier.fillMaxSize()) {
                    Button(onClick = { Respondo.open() }) { Text("Support") }
                    RespondoChatHost() // l'SDK mostra il sheet quando lo stato della chat è OPEN
                }
            }
        }
    }
}

Tutte le chiamate passano dal singleton Respondo. Sono idempotenti, sicure da qualsiasi thread, e le chiamate fatte prima che init termini vengono accodate e riprodotte.

Identificare gli utenti#

Per impostazione predefinita ogni visitatore è anonimo. Al primo avvio l’SDK genera un visitor_id stabile e lo conserva nello storage locale, così un utente che torna ritrova la sua conversazione. Non c’è alcuna chiave API da incorporare — ogni conversazione è protetta da un token di sessione per conversazione che il backend emette e fa avanzare a ogni messaggio, così un visitatore anonimo non deve mai autenticarsi di nuovo.

Chiama identify non appena l’utente è autenticato. Questo collega la sua identità reale, così la sua cronologia lo segue tra dispositivi e reinstallazioni, e il suo nome ed email compaiono accanto alla conversazione nella tua inbox invece di un visitatore anonimo.

Lo userHash è una firma che il tuo backend calcola a partire dall’ identity_secret dell’agente — HMAC-SHA256(secret, userId) (o l’email quando non c’è userId), codificata in esadecimale minuscolo. Il secret dimostra che l’identità è autentica, quindi deve risiedere solo sul tuo backend e non va mai incluso nell’app. Consulta la pagina Verifica dell’identità per la formula completa e gli esempi lato server.

import ai.respondo.sdk.RespondoIdentity

// Lo userHash proviene dal tuo backend (HMAC-SHA256 sullo userId) —
// non calcolarlo mai nell'app.
Respondo.identify(
    RespondoIdentity(
        userId = session.userId,
        email = session.email,
        name = session.fullName,
        userHash = session.respondoUserHash,
    ),
)

// Al logout: rimuovi il token push, revoca la sessione, avvia un nuovo visitatore anonimo.
Respondo.clearPushToken()
Respondo.reset()

Se l’hash manca o è errato, non viene sollevata alcuna eccezione: il backend mantiene silenziosamente il visitatore anonimo, la chat continua a funzionare e si perde semplicemente il collegamento tra dispositivi finché non viene fornito un hash valido. La verifica viene eseguita solo quando l’agente ha un identity_secret impostato — lascialo vuoto durante lo sviluppo e userId / email vengono accettati così come sono.

Observable & callback#

Leggi lo stato in modo reattivo come StateFlow (ottimo per Compose) o in modo imperativo tramite RespondoListener (ottimo per un badge sull’icona dell’app).

// Reattivo: conteggio dei non letti come StateFlow.
val unread by Respondo.unreadCount.collectAsState()

// Imperativo: listener per badge e analytics.
Respondo.setListener(object : RespondoListener {
    override fun onUnreadChanged(count: Int) { updateAppIconBadge(count) }
    override fun onUrlRequested(url: String): Boolean = tryOpenInternally(url)
})

Tracciamento delle schermate#

Segnala la schermata corrente a ogni navigazione, così i teaser proattivi e il targeting a livello di pagina possono farvi riferimento. Passa null per cancellarla; a ogni cambio il teaser proattivo viene rivalutato per la nuova schermata.

Respondo.setCurrentScreen("pricing")

Prossimi passi#

Configura le Notifiche push per le risposte offline degli operatori e la Verifica dell’identità per gli utenti autenticati. L’intera superficie delle API, il wrapper Fragment per host XML e la risoluzione dei problemi sono trattati nella guida introduttiva dell’Android SDK; i sorgenti dell’SDK sono pubblici su GitHub.