Widget per il sito

Il widget è la chat che i visitatori vedono sul tuo sito. Carica il bot che hai pubblicato e gestisce l'intera conversazione nel browser. Nessun modello linguistico, nessuna richiesta a terze parti, circa 22KB dopo la compressione. La chat con un operatore viene caricata da un file separato, solo quando la attivi.

Installazione

Incolla questa riga prima di </body> in ogni pagina in cui deve comparire il bot. Nel pannello di controllo, alla pagina Installazione, la trovi già completa della tua chiave.

<script src="https://cdn.kavchat.com/v1/kavchat.js" data-key="pk_live_..." async></script>

Puoi inserire nella pagina la chiave pubblica (pk_live_...). Non inserire mai nella pagina la chiave segreta (sk_live_...).

Attributi

<script
  src="https://cdn.kavchat.com/v1/kavchat.js"
  data-key="pk_live_..."
  data-locale="he"
  data-user-token="<identity JWT>"
  data-user-name="Dana"
  data-open="false"
  async></script>

API JavaScript

Lo script installa window.Kavchat:

Kavchat.init({
  publicKey: 'pk_live_...',
  apiBase: 'https://api.kavchat.com', // optional
  locale: 'he',                       // optional
  userToken: '<identity JWT>',        // optional
  userName: 'Dana',                   // optional
  open: false,                        // optional
  onScreen(screen, targetId) {},      // optional: "screen" buttons in your scripts
  onEvent(event) {},                  // optional: ready, unavailable, open, close, effect, ticket
});
Kavchat.open();
Kavchat.close();
Kavchat.toggle();
Kavchat.setUser({ token: '<identity JWT>', name: 'Dana' }); // on login; setUser(null) on logout
Kavchat.offset({ bottom: 80 });       // lift the launcher, e.g. above a cookie banner; offset(null) resets
Kavchat.destroy();

init non serve se il tag dello script contiene data-key. Una nuova chiamata a init sostituisce il widget in esecuzione.

Chiamare l'API prima che lo script sia caricato

Il tag dello script è async, quindi il tuo codice potrebbe essere eseguito prima. Crea una coda e aggiungi le chiamate: il widget le eseguirà in ordine al caricamento. init viene sempre eseguito per primo e le sue impostazioni hanno la precedenza sugli attributi del tag.

<script>
  window.Kavchat = window.Kavchat || { q: [] };
  Kavchat.q.push(['init', { publicKey: 'pk_live_...', onScreen: function (s, id) { location.href = '/' + s + '/' + id; } }]);
  Kavchat.q.push(['setUser', { token: '<identity JWT>', name: 'Dana' }]);
</script>
<script src="https://cdn.kavchat.com/v1/kavchat.js" async></script>

Ogni elemento della coda è [methodName, ...args]. Anche dopo il caricamento dello script, Kavchat.q.push(...) continua a funzionare ed esegue subito la chiamata, quindi lo stesso codice funziona in entrambi i casi.

Spazio per il banner dei cookie

Se sul sito c’è un elemento fisso in fondo allo schermo, come un banner dei cookie, puoi spostare il pulsante, la finestra e le bolle al di sopra di questo elemento. Puoi farlo in due modi: con la variabile CSS --kavchat-bottom o con il comando Kavchat.offset, che accetta un numero in pixel o un valore di lunghezza come 5rem. Lo spostamento si aggiunge all’altezza impostata nel pannello di gestione. Quando il banner si chiude, rimuovi la variabile o chiama offset(null). Entrambi i metodi funzionano anche su siti con una CSP restrittiva. Sul telefono la finestra si apre a schermo intero e non si sposta.

/* while your cookie banner is shown */
body.cookie-banner-open { --kavchat-bottom: 80px; }

// works before or after the widget script loads
window.Kavchat = window.Kavchat || { q: [] };
Kavchat.q.push(['offset', { bottom: banner.offsetHeight + 12 }]);

// after the visitor makes a choice
Kavchat.q.push(['offset', null]);

Eventi

La funzione onEvent riceve uno dei seguenti eventi:

Kavchat.init({
  publicKey: 'pk_live_...',
  onEvent(event) {
    if (event.type === 'ready') console.log('Bot version', event.version, event.offline ? '(offline copy)' : '');
    if (event.type === 'ticket') console.log('Request opened', event.number);
  },
});

Azioni nello script

• Ticket: apre il modulo di contatto nella chat. La trascrizione della conversazione viene allegata al ticket.
• Link: apre i link https: e tel: in una nuova scheda (rel="noopener noreferrer"). Gli altri tipi di link non vengono aperti.
• Schermata: chiama la tua funzione onScreen(screen, targetId). Senza questa funzione, il pulsante non fa nulla sul sito.

Elenco delle schermate nell'editor

Dichiara una sola volta le schermate che l'app può aprire, nell'opzione screens di Kavchat.init. L'SDK invia automaticamente l'elenco a Kavchat e l'editor degli script propone queste schermate in un menu a discesa con i rispettivi 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 occorre inserire manualmente l'elenco delle schermate nel pannello di controllo.

Kavchat.init({
  publicKey: 'pk_live_...',
  screens: [
    { id: 'orders', label: 'My orders' },
    { id: 'product', label: 'Product page', needsTarget: true }, // the button also carries a product id
  ],
  onScreen(screen, targetId) {
    location.href = targetId ? `/${screen}/${targetId}` : `/${screen}`;
  },
});

• id è il valore ricevuto da onScreen: lettere latine, cifre, _, . e -, fino a 40 caratteri. label è il nome che vede l'amministratore, fino a 60 caratteri. Fino a 100 schermate. Le voci non valide e gli identificativi duplicati vengono scartati.
• needsTarget: il pulsante include anche l'identificativo di un elemento (ad esempio un prodotto), che viene passato a onScreen come targetId.
• L'elenco viene inviato in background dopo il caricamento della versione, solo se è cambiato o una volta alla settimana. Se l'invio fallisce, non viene mostrato alcun errore e viene fatto un nuovo tentativo all'avvio successivo. L'utente non vede nulla.
• Le schermate registrate compaiono nel pannello di controllo sotto Bot, Impostazioni, "Schermate dell'app", insieme alle piattaforme che hanno segnalato ciascuna schermata. Da lì puoi eliminare una schermata rimossa dall'app.

Identificare i tuoi utenti

Per associare alle conversazioni e ai ticket il tuo identificativo utente, o per mostrare il bot solo agli utenti di test, firma un JWT sul server e passalo tramite data-user-token o userToken. Quando l'utente effettua l'accesso o esce, chiama Kavchat.setUser(...). Il widget invia il token nell'header Authorization: Bearer <token> a ogni chiamata. Un utente che ha effettuato l'accesso può aprire un ticket senza lasciare email o numero di telefono. Per creare il token, vedi Identificazione degli utenti.

Content Security Policy (CSP)

Il widget funziona su siti con una CSP restrittiva, senza 'unsafe-inline' né 'unsafe-eval'. Basta autorizzare le nostre due origini:

script-src https://cdn.kavchat.com;
connect-src https://api.kavchat.com;

Gli stili vengono caricati come constructable stylesheets all'interno dello Shadow DOM, quindi non è necessario modificare style-src. Se il bot ha una propria immagine o se gli script contengono immagini, aggiungi a img-src il server da cui vengono caricate. Il widget non carica nulla da altre origini e non apre iframe.

Chat con un operatore

Non devi configurare nulla sul sito. Quando attivi la chat con gli operatori nel pannello di gestione, il widget carica un file aggiuntivo, kavchat-live.js, dalla stessa cartella e nella stessa versione di kavchat.js. I siti senza chat con operatori non scaricano questo file.

• L'opzione: accanto a "Contatta il team" compare "Chat con un operatore", solo dopo che il server ha confermato la disponibilità di un operatore. Fuori dall'orario di servizio, o quando tutti gli operatori sono occupati, viene mostrato solo il modulo di contatto. Accanto compare una breve spiegazione e, se noto, l'orario in cui il team tornerà disponibile. Quando la quota mensile è esaurita, il modulo viene mostrato senza spiegazione.
• La richiesta: i visitatori non autenticati lasciano un'email o un numero di telefono, nel caso in cui nessun operatore si liberi in tempo. Possono aggiungere anche il nome e un primo messaggio. Se è aperto più di un reparto, ne scelgono uno. Gli utenti identificati (userToken) non devono inserire i recapiti. Se nessun operatore può accettare la chat, si apre il modulo di contatto con i dati già inseriti.
• L'attesa: compare "In attesa di un operatore" con un conto alla rovescia fino al termine del tempo di attesa che hai impostato, insieme ai pulsanti "Lascia un messaggio" e "Termina chat". È possibile scrivere già durante l'attesa. Allo scadere del tempo, la chat si trasforma automaticamente in un ticket. Al visitatore vengono mostrati il numero del ticket e una spiegazione che indica che nessun operatore si è liberato in tempo.
• La conversazione: nome dell'operatore, messaggi, indicatore di digitazione, trasferimento a un altro operatore e chiusura della chat. Tutto ciò che arriva dal server viene mostrato come testo semplice, senza HTML né link. I lettori di schermo leggono i nuovi messaggi e, quando la finestra è chiusa, compare un puntino sul pulsante flottante.
• Tempo reale: la connessione usa Server-Sent Events. Se si interrompe, il widget prova a riconnettersi a intervalli sempre più lunghi e recupera tutto ciò che ha perso. In questo modo nessun messaggio va perso o compare due volte. Sulle reti che bloccano questa connessione, il widget passa a richieste ripetute (long-poll). Ogni messaggio ha un identificativo, quindi un nuovo tentativo non crea duplicati. I messaggi non inviati vengono segnalati e puoi toccarli per inviarli di nuovo.
• Ricaricamento: la credenziale di accesso alla chat viene salvata in localStorage per chiave pubblica e conversazione, mai nell'URL. È valida fino a 12 ore o fino al termine della chat. Così, dopo un ricaricamento o il passaggio a un'altra pagina, viene ripristinata l'intera conversazione: prima la parte con il bot, poi quella con l'operatore.
• Senza preflight: le chiamate vengono inviate senza header personalizzati e il corpo della richiesta è JSON inviato come text/plain.

Risposte AI (Premium)

Non devi configurare nulla sul sito. Quando attivi le risposte AI nel pannello di gestione (con una tua chiave del fornitore AI), le domande a cui nessuno script sa rispondere vengono inviate a Kavchat. Durante l'attesa, fino a 20 secondi, la chat mostra che il bot sta scrivendo. La risposta compare 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 fallisce, 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.

Come si comporta il widget

• Isolamento: tutto viene visualizzato all'interno di uno Shadow DOM. Il tuo CSS non influisce sul widget e il CSS del widget non influisce sulla pagina.
• Cache: il bot pubblicato viene salvato in localStorage per chiave pubblica, insieme al suo ETag. A ogni caricamento viene inviato l'header If-None-Match e, se non è cambiato nulla, il server risponde con 304. In assenza di connessione, il widget usa la copia salvata e mostra un avviso.
• Conversazioni: un identificativo casuale della conversazione viene salvato in sessionStorage, così il passaggio da una pagina all'altra mantiene la stessa conversazione.
• Chat con un operatore: una chat aperta viene salvata in localStorage e ripristinata nella pagina successiva.
• Dati: il percorso della conversazione viene inviato circa 2 secondi dopo ogni azione e anche quando la pagina viene nascosta.
• Badge Kavchat: compare in tutti i piani. Con Premium puoi nasconderlo nelle impostazioni del bot.
• Accessibilità: la finestra è una finestra di dialogo con etichetta, il focus passa al suo interno e poi torna all'elemento precedente, Esc la chiude, i pulsanti sono veri pulsanti, i nuovi messaggi del bot vengono letti ad alta voce e le animazioni vengono ridotte se il visitatore lo ha richiesto.

Installazione da npm

In un'app a pagina singola puoi includere il widget nel bundle del tuo codice invece di caricare il tag dello script:

yarn add @kavchat/widget
# or: npm install @kavchat/widget

import { createWidget } from '@kavchat/widget';

const widget = createWidget({ publicKey: 'pk_live_...' });
await widget.ready;
widget.open();