Kavchat by maxsave
Menu delle guide

Android

La libreria Android di Kavchat aggiunge alla tua app il bot di assistenza basato su script, con componenti Jetpack Compose e un'Activity per le app sviluppate con Views. Le risposte sono prevedibili e continuano a funzionare anche senza connessione, usando l'ultima versione pubblicata. Richiede Android 6.0 (API 23) o successivo.

Ci sono due componenti: kavchat-engine, la versione Kotlin/JVM del motore di conversazione, senza dipendenze da Android o da librerie di terze parti, e kavchat, che include la comunicazione di rete (HttpURLConnection), la cache sul dispositivo (SharedPreferences), i componenti Compose KavchatChat e KavchatLauncher e KavchatActivity.

Installazione

Gradle (Kotlin DSL)
// settings.gradle.kts
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven("https://jitpack.io")
    }
}

// app/build.gradle.kts
dependencies {
    implementation("com.kavchat:kavchat-android:0.0.11")
}

La libreria è distribuita tramite JitPack: aggiungi il suo repository una sola volta, accanto a google() e mavenCentral(). L'SDK è open source, con licenza MIT: bitbucket.org/maxsave/kavchat-android.

La libreria dichiara già il permesso INTERNET e KavchatActivity nel proprio manifest. Non serve aggiungere nulla a mano.

Configurazione

Chiama configure una sola volta, in Application.onCreate:

Kotlin
class App : Application() {
    override fun onCreate() {
        super.onCreate()
        Kavchat.configure(this, publicKey = "pk_live_...")
        // Optional: Kavchat.configure(this, "pk_live_...", apiBase = "https://api.kavchat.com", locale = "he")
    }
}

Puoi includere la chiave pubblica nell'app. Non includere mai la chiave segreta (sk_live_...).

Compose

Un pulsante mobile nell'angolo scelto nella dashboard, che apre la chat a schermo intero:

Compose
KavchatOverlay(Modifier.fillMaxSize()) {
    AppContent()
}

Puoi anche posizionare il pulsante dove preferisci o integrare la chat in una tua schermata:

Compose
KavchatLauncher()                                    // com.kavchat.ui.KavchatLauncher
KavchatChat(Modifier.fillMaxSize())                  // full chat, no close button
KavchatChat(Modifier.fillMaxSize(), onClose = { navController.popBackStack() })

Apri e chiudi da codice la chat del pulsante mobile con Kavchat.controller.setPresented(true) e setPresented(false).

Views (senza Compose nell'app)

Kotlin
Kavchat.open(context)                                // starts KavchatActivity

Da Java: Kavchat.open(context);. L'Activity usa Compose al suo interno, ma la tua app non deve necessariamente usarlo.

Token di identità

Identifica l'utente che ha effettuato l'accesso con un JWT firmato dal tuo server con la chiave segreta (vedi Identificazione degli utenti). Il token viene inviato nell'header Authorization: Bearer <token>. Un utente identificato può vedere le versioni riservate agli utenti di test e inviare il modulo di contatto senza email o telefono.

Kotlin
Kavchat.setUser(token = identityToken, name = "Dana")   // after login
Kavchat.setUser(token = null)                           // after logout

Il cambio di utente ricarica la versione e avvia una nuova conversazione, così la chat di un utente non viene mostrata a un altro.

Schermate dell'app: onScreen

Un pulsante di tipo screen nello script chiede all'app di aprire una delle sue schermate. Prima viene chiusa la chat (la finestra di dialogo di KavchatLauncher o KavchatActivity), in modo che la schermata sia visibile:

Kotlin
Kavchat.onScreen = { screen, targetId ->
    navController.navigate("$screen/${targetId.orEmpty()}")   // e.g. "orders", "42"
}

Senza un handler, questi pulsanti non fanno nulla. I pulsanti link aprono solo link https (nel browser) e tel (nel tastierino telefonico). Per l'analisi dei dati, Kavchat.onEvent segnala Ready, Unavailable, Open, Close, Effect e Ticket.

Elenco delle schermate nell'editor

Dichiara una sola volta le schermate che l'app può aprire in Kavchat.configure(..., screens = ...) (tipo KavchatAppScreen). L'SDK invia automaticamente l'elenco a Kavchat e l'editor degli script propone queste schermate in un menu a tendina con i loro nomi, al posto di un campo di testo libero. L'editor chiede anche un ID elemento quando la schermata lo richiede e segnala i pulsanti che portano a schermate non dichiarate. Nessuno deve inserire a mano l'elenco delle schermate nella dashboard.

Kotlin
Kavchat.configure(
    this, publicKey = "pk_live_...",
    screens = listOf(
        KavchatAppScreen("orders", "My orders"),
        KavchatAppScreen("product", "Product page", needsTarget = true),   // needs a targetId
    ),
)
// or later: Kavchat.registerScreens(listOf(...))
  • id è il valore ricevuto da onScreen: lettere latine, cifre, _, . e -, fino a 40 caratteri. label è il nome visibile all'amministratore, fino a 60 caratteri. Massimo 100 schermate. Le voci non valide e gli ID duplicati vengono scartati.
  • needsTarget: il pulsante contiene anche un ID elemento (per esempio l'ID di un prodotto), che arriva a onScreen come targetId.
  • L'elenco viene inviato in background dopo il caricamento della versione, solo quando cambia o una volta alla settimana. Un eventuale errore non viene mostrato e l'invio viene ritentato al successivo avvio. L'utente non vede nulla.
  • Le schermate registrate compaiono nella dashboard sotto Bot, Impostazioni, "Schermate dell'app", con le piattaforme che hanno segnalato ciascuna schermata. Da lì puoi eliminare una schermata rimossa dall'app.

Colori

I colori provengono dalla dashboard (primaryColor). Il testo sul colore del brand è bianco o quasi nero in base al contrasto WCAG. Nei link e nei pulsanti, un colore troppo chiaro per il testo su sfondo bianco viene sostituito con un quasi nero. Anche il nome del bot, il sottotitolo, l'immagine e il lato del pulsante mobile (start o end) provengono dalla dashboard, quindi possono cambiare senza aggiornare l'app. Superfici e tipografia seguono il tuo MaterialTheme.

Il badge "Powered by Kavchat by maxsave" viene mostrato in tutti i piani, con un link a kavchat.com. Con Premium puoi nasconderlo nelle impostazioni del bot.

Lingue e RTL

  • La lingua dell'interfaccia è il locale passato a configure. Se non è specificato, viene usata la lingua del dispositivo, se tradotta (he, en, ar, ru, es, fr, de, pt, it, tr), poi la lingua dello script e infine l'inglese.
  • La ricerca delle corrispondenze nello script usa sempre la lingua dello script (parole comuni da ignorare e prefissi in ebraico e arabo).
  • In ebraico e arabo, il LocalLayoutDirection dell'intera chat è RTL. Nulla viene invertito manualmente: se racchiudi i componenti in altri elementi, usa start e end. Mantieni android:supportsRtl="true" nel manifest dell'app.

Risposte AI (Premium)

Non devi configurare nulla nell'app. Quando attivi le risposte AI nel pannello di gestione (con la tua chiave di un fornitore AI), una domanda a cui nessuno script risponde viene inviata a Kavchat. Durante l'attesa, fino a 20 secondi, la chat mostra che il bot sta scrivendo. La risposta appare come testo semplice con una piccola etichetta "Risposta AI" nella lingua dell'interfaccia. Sotto compaiono un pulsante per un argomento correlato, se disponibile, e il pulsante "Contatta il team".

Se non c'è una risposta, oppure la richiesta non va a buon fine, impiega troppo tempo o supera il limite (10 risposte per conversazione ogni 15 minuti), la chat mostra il consueto messaggio "Non ho trovato una risposta". La domanda compare comunque nel report delle domande senza risposta e le risposte AI vengono conservate nella conversazione salvata come qualsiasi altro messaggio.

Chat con un operatore

Non devi configurare nulla nell'app. Quando attivi la chat con gli operatori nel pannello di gestione, la chat nell'app funziona esattamente come il widget sul sito.

  • L'opzione compare solo se la chat con gli operatori è attiva nella versione pubblicata. Quando il bot mostra "Contatta il team", l'SDK verifica se c'è un operatore disponibile. La risposta viene conservata per 30 secondi. Se c'è un operatore disponibile, prima di quel pulsante compare "Parla con un operatore". Altrimenti viene mostrato solo il modulo di contatto, preceduto da una breve spiegazione: fuori orario di servizio (con l'orario di riapertura) oppure tutti gli operatori sono occupati.
  • Prima della chat si compila un breve modulo: nome, email o telefono, reparto (solo quando c'è più di un reparto aperto) e primo messaggio (facoltativo). Un ospite deve lasciare un'email o un numero di telefono. Un utente identificato tramite token di identità non deve fornire nessuno dei due. Se al momento dell'invio non ci sono più operatori disponibili, si apre il modulo di contatto con i dati già inseriti.
  • Durante l'attesa vengono mostrati il tempo rimasto prima che la chat diventi un ticket e il pulsante "Lascia invece un messaggio". Il tempo di attesa si imposta nel pannello di gestione e il valore predefinito è 2 minuti. Si può scrivere anche durante l'attesa e l'operatore vedrà i messaggi. Se nessun operatore si libera in tempo, la chat viene salvata come un normale ticket e ne viene mostrato il numero.
  • Durante la chat vengono mostrati il nome dell'operatore, un avviso quando un operatore si unisce alla conversazione (anche dopo un trasferimento a un altro operatore), un indicatore quando sta scrivendo e un pulsante per terminare la chat. I messaggi contengono solo testo semplice, fino a 2.000 caratteri, senza link. Un messaggio non ancora arrivato al server è contrassegnato con "Invio...". Se l'invio fallisce più volte, si può toccare il messaggio per riprovare. Un nuovo tentativo non crea duplicati.
  • Dopo ogni disconnessione, l'SDK attende un po', recupera ciò che è stato perso e si riconnette. Il tempo di attesa aumenta gradualmente. I messaggi vengono sempre mostrati in ordine e senza duplicati. Se la connessione continua non funziona (per esempio dietro un proxy aziendale), l'SDK passa temporaneamente a controlli ripetuti sul server.
  • Quando l'app passa in background, la connessione si chiude. Al ritorno nell'app, l'SDK recupera ciò che è stato perso e si riconnette. Una chat aperta continua anche dopo la chiusura e il riavvio dell'app, purché non siano trascorse 12 ore.
  • Questa versione non prevede notifiche push. I messaggi arrivano solo quando l'app è aperta. Una risposta inviata mentre l'app è in background compare appena si torna nell'app.
  • Le credenziali di accesso alla chat vengono conservate in memoria. Sul dispositivo vengono salvate solo se crittografate con una chiave di Android Keystore. Non vengono scritte nell'URL o nei log. Vengono eliminate quando la chat termina, diventa un ticket o scade, e anche quando si cambia utente con setUser.

Puoi usare Kavchat.controller.livePage per indicare all'operatore da quale schermata arriva l'utente.

Domande, condizioni e lead

Non servono impostazioni nell'app. Uno script può chiedere dati (nome, telefono, email, numero o testo libero), scegliere come proseguire in base alle informazioni note e inviare un lead.

  • Tastiera adatta: quando il bot attende una risposta, il campo di testo mostra una tastiera per telefono, email o numeri. Per le domande sul nome, la tastiera imposta la maiuscola all'inizio di ogni parola. Se la risposta non è valida, il bot risponde con un breve messaggio nella lingua della chat e il campo viene evidenziato. Le domande che si possono saltare mostrano il pulsante "Salta". Scrivere "Annulla", in qualsiasi lingua supportata, permette di uscire dalla domanda.
  • Telefono: ai numeri senza + viene associato il paese predefinito dell'area di lavoro, definito nelle impostazioni del pannello di gestione.
  • Lead: un passaggio di tipo lead mostra il testo di consenso con i pulsanti "Invia" e "No, grazie", seguito dal messaggio di conferma. Il lead viene messo in coda sul dispositivo e inviato al server. Se manca la connessione di rete o il server non è disponibile, l'invio viene ritentato, anche al successivo avvio e dopo reload(). Il server ignora i duplicati.
  • Precompilazione: il modulo di contatto e quello per richiedere un operatore vengono compilati con nome, email e telefono raccolti. Tutti i valori raccolti vengono allegati al ticket o alla richiesta di un operatore. Le domande prima della chat con un operatore (Premium) vengono poste prima della connessione.
  • Token di identità: quando usi setUser, i campi name, email e phone del token compilano le risposte alle domande corrispondenti e il bot le salta.
  • Schermata attuale: le condizioni possono verificare la schermata attuale. Imposta Kavchat.controller.livePage (per esempio "checkout").

I valori raccolti sono dati personali. Restano nella conversazione salvata sul dispositivo e vengono inviati solo per lead, ticket e chat con gli operatori, mai per i report.

Funzionamento offline e cache

L'ultima versione viene salvata in SharedPreferences con il suo ETag e verificata di nuovo con If-None-Match (304) a ogni avvio. Senza rete viene usata la copia salvata e un avviso lo segnala. Quando il bot è disattivato, è riservato agli utenti di test o ha esaurito la quota, non viene mostrato nulla. Una conversazione aperta viene conservata fino a 30 minuti di inattività, così uscire dalla chat o dall'app non la fa ricominciare. Il percorso della conversazione viene inviato due secondi dopo l'ultima azione e subito quando l'app passa in background.