iOS

Il pacchetto Swift di Kavchat aggiunge alla tua app iOS il bot di assistenza basato su script, con componenti SwiftUI e UIKit. Le risposte sono prevedibili e continuano a funzionare anche offline, usando l'ultima versione pubblicata. Richiede iOS 15 o successivo.

Il pacchetto include due prodotti: KavchatEngine, la versione Swift del motore di conversazione, senza UIKit, e Kavchat, con la gestione delle comunicazioni, la cache sul dispositivo e l'interfaccia: KavchatChatView (SwiftUI), KavchatLauncher e KavchatViewController (UIKit).

Installazione

Con Swift Package Manager in Xcode: scegli File > Aggiungi dipendenze dei pacchetti e inserisci l'indirizzo del repository:

https://bitbucket.org/maxsave/kavchat-ios.git

Oppure nel file Package.swift:

.package(url: "https://bitbucket.org/maxsave/kavchat-ios.git", from: "0.0.11"),
// ...
.product(name: "Kavchat", package: "kavchat-ios"),

L'SDK è open source, con licenza MIT: bitbucket.org/maxsave/kavchat-ios.

Configurazione

Chiama configure una sola volta, il prima possibile, ad esempio nell'init di App o in application(_:didFinishLaunchingWithOptions:):

import Kavchat

Kavchat.configure(publicKey: "pk_live_...")            // the public key from the dashboard
// Optional:
// Kavchat.configure(publicKey: "pk_live_...", apiBase: "https://api.kavchat.com", locale: "he")

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

SwiftUI

Un pulsante flottante nell'angolo scelto nel pannello di controllo apre la chat in una finestra modale (sheet):

ContentView()
    .kavchatLauncher()

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

KavchatLauncher()
KavchatChatView()                                      // full chat, no close button
KavchatChatView(onClose: { showChat = false })         // with a close button

Apri e chiudi da codice la finestra del pulsante flottante con Kavchat.open() e Kavchat.close().

UIKit

Kavchat.present(from: self)                            // modal, with a close button
// or
let chat = KavchatViewController(showsCloseButton: false)
navigationController?.pushViewController(chat, animated: true)

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.

Kavchat.setUser(token: identityToken, name: "Dana")    // after login
Kavchat.setUser(token: nil)                            // 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. La finestra della chat si chiude prima, per rendere visibile la schermata:

Kavchat.onScreen = { screen, targetId in
    router.open(screen, id: targetId)                  // e.g. "orders", "42"
}

Senza un handler, questi pulsanti non fanno nulla. I pulsanti link aprono solo link https e tel. Per l'analisi dei dati, Kavchat.onEvent segnala gli eventi 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:). 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 richiede anche l'identificativo di un elemento quando la schermata ne ha bisogno e segnala i pulsanti che rimandano a schermate non dichiarate. Non serve inserire manualmente l'elenco delle schermate nel pannello di controllo.

Kavchat.configure(publicKey: "pk_live_...", screens: [
    KavchatScreen(id: "orders", label: "My orders"),
    KavchatScreen(id: "product", label: "Product page", needsTarget: true),  // needs a targetId
])
// or later: Kavchat.registerScreens([...])

• 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 identificativi duplicati vengono scartati.
• needsTarget: il pulsante contiene anche l'identificativo di un elemento (ad esempio 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 segnalato e l'invio viene ritentato all'avvio successivo. L'utente non vede nulla.
• Le schermate registrate compaiono nel pannello di controllo 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 dal pannello di controllo (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 colore quasi nero. Anche il nome del bot, il sottotitolo, l'immagine e il lato del pulsante flottante (start o end) provengono dal pannello di controllo e possono quindi cambiare senza aggiornare l'app.

Il badge "Powered by Kavchat by maxsave" è visibile 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 viene passato, si usa la lingua del dispositivo, se disponibile una traduzione (he, en, ar, ru, es, fr, de, pt, it, tr), poi la lingua dello script e infine l'inglese.
• La ricerca delle corrispondenze usa sempre la lingua dello script (parole comuni da ignorare e prefissi in ebraico e arabo).
• In ebraico e arabo, layoutDirection imposta l'intera chat da destra a sinistra. Nulla viene invertito manualmente: se racchiudi i componenti in altri contenitori, usa leading e trailing.

Risposte AI (Premium)

Non c'è nulla da configurare nell'app. Quando attivi le risposte AI nel pannello di gestione (con una tua chiave di un provider AI), le domande a cui nessuno script risponde vengono inviate 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, seguita da un pulsante per un argomento correlato, se presente, e da un pulsante "Contatta il team".

Se non c'è una risposta, oppure la richiesta non riesce, 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 serve 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. Il risultato viene conservato per 30 secondi. Se un operatore è disponibile, prima di quel pulsante compare "Parla con un operatore". Altrimenti viene mostrato solo il modulo di contatto. Sopra il modulo, una breve riga spiega il motivo: fuori dall'orario di servizio (con l'orario di riapertura) oppure tutti gli operatori occupati.
• Prima della chat si compila un breve modulo: nome, email o telefono, reparto (solo se ce n'è più di uno aperto) e un primo messaggio facoltativo. Un ospite deve lasciare un'email o un numero di telefono. Un utente identificato tramite token di identità non deve lasciare 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 rimanente 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 è di 2 minuti. Si può scrivere anche durante l'attesa: 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 messaggio quando un operatore si unisce (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 in corso...". 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 (ad esempio dietro un proxy aziendale), l'SDK passa temporaneamente a controlli periodici 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 include 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 solo in memoria e nel Keychain del dispositivo. Non vengono salvate in UserDefaults, in un 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.shared.livePage per indicare all'operatore da quale schermata è arrivato l'utente.

Domande, condizioni e lead

Non serve configurare nulla nell'app. Uno script può chiedere dati (nome, telefono, email, un 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. Per le domande facoltative compare 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, impostato nel pannello di gestione.
• Lead: un passaggio lead mostra il testo del 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 o il server non è disponibile, l'invio viene ritentato, anche all'avvio successivo e dopo reload(). Il server ignora i duplicati.
• Precompilazione: il modulo di contatto e quello per richiedere un operatore vengono compilati con il nome, l'email e il 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 del collegamento.
• Token di identità: quando usi setUser, i campi name, email e phone del token compilano le risposte alle domande corrispondenti, che il bot salta.
• Schermata corrente: le condizioni possono verificare la schermata corrente. Imposta Kavchat.shared.livePage (ad esempio "checkout").

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

Funzionamento offline e cache

L'ultima versione viene salvata in UserDefaults con il suo ETag e ricontrollata con If-None-Match (304) a ogni avvio. Senza rete viene usata la copia salvata e viene mostrato un avviso. 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 comunicato due secondi dopo l'ultima azione e subito quando l'app passa in background.