Documentazione

Android SDK

Un client leggero in Kotlin e Jetpack Compose che apre la chat di assistenza Respondo come bottom sheet sopra la tua app.

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.

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

Inizializzazione

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

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>",   // dalla dashboard
                channelId = "<channel-uuid>", // Settings › Channels › Mobile SDK
                // 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.

Kotlin
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,
        signedUpAt = session.signedUpAt,
    ),
)

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

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

Lo stesso nome viene confrontato con le regole di schermata dei sondaggi pop-up: usa identificatori stabili come «Checkout» invece di titoli tradotti. Le regole sull’indirizzo della pagina valgono solo sui siti web.

Kotlin
Respondo.setCurrentScreen("pricing")

Aprire un sondaggio dal codice

Apre subito un sondaggio pop-up attivo, ovunque si trovi l’utente, ignorando Show on, le regole di schermata, il tempo sulla schermata, l’evento di attivazione e il pubblico. Copia l’id dall’editor del sondaggio (Additional ways to share). Un sondaggio a cui l’utente ha già risposto non viene mostrato di nuovo.

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

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.