API JavaScript del widget

Per installare il widget senza scrivere codice parti da Installare il widget.

#Cosa resta stabile fra le versioni

Questi elementi non cambiano nome né significato fra una versione e l'altra:

• Il file chatbot.js, incluso come script classico, con id="supportfast-script" (o id="chatbot-script") e l'attributo data-chatbot-id.
• L'oggetto window.SupportFast, con init() e version.
• window.ChatbotConfig.lang e window.chatbotUserData.
• L'evento chatbot_open nel dataLayer.
• Il contenitore #chat-widget-container, a cui si applicano le variabili CSS.
• Le variabili CSS --sf-offset-bottom, --sf-offset-side e --sf-z-index.

Il resto, comprese le classi interne del widget, può cambiare: non usarlo nel codice del sito.

#Il tag

HTML · il tag del widget (codice agente d'esempio)Copia

<script defer id="supportfast-script" src="https://cdn.supportfast.ai/chatbot.js" data-chatbot-id="bot-a1b2c3d4e5"></script>

• Il tag deve restare uno script classico: non aggiungere type="module".
• Va incluso una volta per pagina. Una seconda inclusione non fa nulla.
• Il widget si monta quando il documento è pronto. Se il tag arriva dopo, per esempio da Google Tag Manager, si monta subito.

#L'oggetto window.SupportFast

Il widget crea window.SupportFast appena chatbot.js viene eseguito, prima che la chat sia pronta.

• Le chiamate fatte dopo l'esecuzione di chatbot.js, ma prima che la chat sia pronta, restano in coda e partono nell'ordine di arrivo.
• ready arriva quando l'agente è caricato e attivo; un gestore registrato dopo parte subito. Con l'agente non disponibile, non arriva.

HTML · un bottone del sito che apre la chatCopia

<button type="button" onclick="window.SupportFast && window.SupportFast.open()">Scrivici</button>

#Far aspettare il tuo codice

Prima che chatbot.js venga eseguito, window.SupportFast non esiste e non c'è una coda in cui lasciare le chiamate. Il tuo codice deve quindi aspettare l'oggetto.

• Con il tag in defer, come nel codice della console, basta l'evento DOMContentLoaded: arriva dopo l'esecuzione degli script defer.
• Con async, con Google Tag Manager o con un plugin che ritarda gli script, chatbot.js può arrivare dopo DOMContentLoaded. Usa la funzione qui sotto, che va bene in tutti i casi.

JavaScript · aspettare il widget, comunque sia caricatoCopia

function conSupportFast(azione) {
  var tentativi = 0;
  (function prova() {
    if (window.SupportFast && typeof window.SupportFast.on === "function") {
      azione(window.SupportFast);
    } else if (tentativi < 100) {
      tentativi += 1;
      setTimeout(prova, 100); // riprova ogni decimo di secondo, per 10 secondi
    }
  })();
}

conSupportFast(function (chat) {
  chat.on("ready", function () {
    // la chat è caricata e l'agente è attivo
  });
});

Se chatbot.js può arrivare più tardi, per esempio perché un plugin aspetta il primo movimento del visitatore, alza il numero di tentativi.

#Forzare la lingua: window.ChatbotConfig.lang

Di norma il widget sceglie la lingua dal browser del visitatore, fra quelle del workspace. Per forzarla, imposta window.ChatbotConfig prima del codice del widget.

HTML · chat sempre in ingleseCopia

<script>window.ChatbotConfig = { lang: "en" };</script>
<script defer id="supportfast-script" src="https://cdn.supportfast.ai/chatbot.js" data-chatbot-id="bot-a1b2c3d4e5"></script>

• Codici possibili, in minuscolo: it, en, de, fr, es, nl, pl, tr, pt, pt-br, sr. it-IT o IT non valgono.
• La lingua deve essere fra quelle del workspace. Altrimenti il widget la ignora e sceglie come al solito.
• La lingua si decide all'avvio: per cambiarla serve ricaricare la pagina.
• Vale solo per il widget installato con il codice nel sito, non per il link e l'iframe.

#I dati del cliente collegato: window.chatbotUserData

Con window.chatbotUserData passi al widget i dati di un cliente collegato al tuo sito. I campi sono firstName, lastName, fullName, company, email, phone e metadata, per le variabili del workspace. Limiti ed esempi sono in Passare i dati dell'utente.

#Eventi per Google Analytics e Tag Manager

A ogni apertura della chat il widget esegue window.dataLayer.push({ event: "chatbot_open" }). Se dataLayer non esiste, lo crea. L'evento non ha altri parametri.

Con Google Tag Manager crea un attivatore di tipo evento personalizzato, con nome evento chatbot_open. Collegalo a un tag evento di Google Analytics 4, per esempio con lo stesso nome. Pubblica il contenitore, apri la chat e cerca l'evento nel rapporto in tempo reale di Analytics.

Con gtag.js, senza Tag Manager, una voce nel dataLayer non diventa un evento di Analytics. Usa l'evento open del widget:

JavaScript · evento GA4 all'apertura della chatCopia

// conSupportFast è la funzione di «Far aspettare il tuo codice», qui sopra
conSupportFast(function (chat) {
  chat.on("open", function () {
    gtag("event", "chatbot_open");
  });
});

La chat dentro un iframe comunica con la pagina che la contiene attraverso messaggi postMessage, elencati in Passare i dati dell'utente.

#Spostare il bottone: le variabili CSS

Il contenitore del widget legge tre variabili CSS, che puoi impostare dal foglio di stile del sito:

CSS · bottone più in alto, per non coprire un banner dei cookieCopia

#chat-widget-container {
  --sf-offset-bottom: 100px; /* il bottone sale sopra il banner, alto circa 80 pixel */
  --sf-offset-side: 20px;
  --sf-z-index: 1000; /* più basso del predefinito: il banner, se ha un livello più alto, resta sopra la chat */
}

• Puoi scriverle su #chat-widget-container o su un elemento che lo contiene, come :root.
• La finestra aperta e la nuvola si spostano con il bottone. Sotto i 600 pixel di larghezza la finestra aperta occupa comunque tutto lo schermo.
• Abbassa --sf-z-index se un elemento del sito, come un menu o il banner dei cookie, deve stare sopra la chat: passa sopra ogni elemento con un livello più alto del valore che scegli.
• Per nascondere il widget in una pagina, applica solo lì la regola #chat-widget-container { display: none; }. Serve, per esempio, nella pagina in cui hai messo la chat con l'iframe.

#Isolamento dal CSS del sito

La chat è isolata dal resto della pagina: il CSS del sito non entra nella chat e quello della chat non esce. Dal sito si governano solo il contenitore e le tre variabili CSS.

#Content Security Policy

Se il sito manda una Content Security Policy (CSP), la policy deve permettere gli indirizzi da cui il widget carica le sue parti e con cui comunica. Altrimenti il bottone non compare, o la chat si apre ma non risponde. Aggiungi queste origini alle direttive che il sito usa già:

HTTP · esempio di intestazione con le sole direttive del widgetCopia

Content-Security-Policy:
  script-src 'self' https://cdn.supportfast.ai;
  font-src 'self' https://cdn.supportfast.ai;
  connect-src 'self' https://server.supportfast.ai wss://server.supportfast.ai;
  img-src 'self' https: blob:;
  media-src 'self' https:;
  frame-src 'self' https://app.supportfast.ai

• Il widget non ha bisogno di 'unsafe-inline' né di 'unsafe-eval'. Gli script che scrivi tu nella pagina, come window.chatbotUserData o window.ChatbotConfig, sono invece script in linea: con una policy senza 'unsafe-inline' dagli un nonce o spostali in un file.
• Per i messaggi vocali il browser deve concedere il microfono alla pagina. Se il sito manda l'intestazione Permissions-Policy, deve contenere microphone=(self). Nell'iframe il codice della console ha già allow="microphone".
• Sul portale di un rivenditore gli indirizzi possono essere diversi: per script-src, font-src e frame-src usa i domini che trovi nel codice copiato dalla console.

Come verificare. Apri il sito, poi la console del browser (F12), e apri la chat. Se la policy blocca qualcosa, la console mostra un errore che nomina la direttiva e l'indirizzo bloccato: aggiungilo e riprova.

#Cosa salva nel browser

Il widget usa solo il localStorage: nessun cookie, niente sessionStorage né IndexedDB. Con il bottone i dati stanno sul dominio del tuo sito; con il link e l'iframe sul dominio della chat.

• Il consenso alla privacy dato dal visitatore vale fino allo stesso giorno del mese dopo. Una conversazione ferma da più di 31 giorni non si riapre da sola.
• Le chiavi del widget cominciano con sf:. Se un gestore dei cookie svuota il localStorage, escludile: altrimenti la chat riparte da zero a ogni visita.
• Se il browser nega il localStorage, il widget funziona senza memoria.

#Messaggi nella console del browser

Durante il funzionamento normale il widget non scrive nella console. Quando qualcosa non va, scrive un messaggio in inglese che comincia con [SupportFast]:

Alcuni casi non producono messaggi: agente in pausa, codice inesistente, dominio non autorizzato, browser troppo vecchio. Le cause e i rimedi sono in Problemi con il widget sul sito.

#Browser supportati

Il widget funziona su Chrome ed Edge dalla versione 85, su Firefox dalla 101 e su Safari dalla 16.4. Su iPhone e iPad serve iOS o iPadOS 16.4 o successivo. Sui browser più vecchi il bottone non compare, senza conseguenze per il resto della pagina.

I messaggi vocali richiedono anche un browser che sappia registrare l'audio e l'accesso al microfono. Dove mancano, il microfono non compare.

#Versioni e aggiornamenti

Il tag punta sempre allo stesso chatbot.js: le versioni nuove arrivano da sole, senza toccare il sito. Per sapere quale versione gira, scrivi window.SupportFast.version nella console del browser.

#Leggi anche