Integrazione JavaScript avanzata

Questa pagina è rivolta a chi sviluppa l'integrazione del widget in un'applicazione web e ha bisogno di controllarlo programmaticamente: avviarlo, distruggerlo, iniettare dati del cliente, personalizzare l'aspetto a runtime o intercettarne gli eventi. Per la sola installazione dello script tag vedi Installare il widget sul sito.

Prerequisiti

• Il widget installato sul sito (vedi Installare il widget sul sito).
• Conoscenza di base di JavaScript lato client.
• Per le funzionalità indicate come disponibili solo nella variante nuova: widget configurato con il bundle askme.chat.widget.js (vedi Il widget di chat).

Dopo il caricamento, il widget espone l'oggetto globale window.askmeChatWidget, tramite il quale è possibile invocare tutte le API descritte in questa pagina.

Caricamento e ciclo di vita

Metodo	Effetto
load(callback, tokenOverride)	Avvia il caricamento del widget, con possibilità di specificare un token diverso da quello dello script tag
init()	Inizializza e rende visibile il componente di chat
start()	Avvia esplicitamente la sessione di chat
destroy()	Distrugge l'istanza corrente: chiude la connessione, cancella i cookie e le voci di localStorage della sessione, interrompe i timer attivi e rimuove il widget dal DOM
loadWithToken(newToken, callback)	Distrugge l'istanza corrente e la ricarica con un nuovo token, utile ad esempio dopo un login o un logout dell'utente che deve associarlo a un widget diverso
reload(callback)	Distrugge e ricarica il widget mantenendo il token corrente, riportandolo a uno stato pulito senza ricaricare l'intera pagina

document.addEventListener('askmeChatWidgetLoaded', function () {
  window.askmeChatWidget.init();
});

// Al login dell'utente, per associare il widget a un nuovo token
window.askmeChatWidget.loadWithToken('#NUOVO-TOKEN-...', function () {
  window.askmeChatWidget.addCustomerInfo('matricola', currentUser.id);
});

Eventi

Evento	Dove	Descrizione
askmeChatWidgetLoaded	document (entrambe le varianti)	Emesso al termine dell'inizializzazione del widget. Tutte le API vanno invocate solo dopo questo evento
askmechat:chatClosed	window, con bubbles: true (solo variante nuova)	Emesso alla chiusura della chat, con detail: { tenantId, roomId, timestamp }

document.addEventListener('askmeChatWidgetLoaded', function () {
  window.askmeChatWidget.addCustomerInfo('name', 'Mario Rossi');
});

window.addEventListener('askmechat:chatClosed', function (event) {
  console.log('Chat chiusa', event.detail.roomId);
});

Passare dati del cliente

addCustomerInfo(key, value) inietta variabili di sessione nel widget prima o durante la chat. Tre chiavi hanno un significato convenzionale lato backend; altre chiavi vengono comunque accettate e propagate:

Chiave	Descrizione
name	Nome dell'utente
matricola	Identificativo univoco dell'utente (può essere anche un indirizzo email)
email	Email dell'utente

Esempio tipico in un contesto con autenticazione SSO, dove i dati dell'utente già loggato vengono passati al widget al momento del caricamento:

document.addEventListener('askmeChatWidgetLoaded', function () {
  window.askmeChatWidget.addCustomerInfo('name', currentUser.fullName);
  window.askmeChatWidget.addCustomerInfo('matricola', currentUser.id);
  window.askmeChatWidget.addCustomerInfo('email', currentUser.email);
});

getCustomerInfo() restituisce i dati correntemente iniettati; resetChat() reinizializza il widget preservando name, matricola ed email (le altre chiavi vanno reimpostate manualmente dopo il reset).

Personalizzazione runtime con setUIParams

Le CSS custom property non sono modificabili a runtime

Il widget definisce internamente variabili CSS (--awc-*, solo variante nuova) per colori, spaziature e tipografia, ma sono risolte in fase di compilazione del bundle: impostarle a runtime da codice esterno non ha alcun effetto. La personalizzazione a runtime va effettuata esclusivamente tramite setUIParams(...) oppure tramite il CSS personalizzato configurato lato backend (vedi CSS personalizzato).

setUIParams(params) sovrascrive a runtime i parametri grafici altrimenti impostati nel passo Grafica del wizard (vedi Personalizzazione grafica):

Parametro	Descrizione
header_bg_color, header_text_color	Colori dell'intestazione
button_bg_color, button_text_color*	Colori del pulsante flottante
bg_color, bg_text_color	Colore di sfondo e testo generale
baloon_received_bg_color, baloon_received_text_color	Colori dei messaggi ricevuti
baloon_sent_bg_color, baloon_sent_text_color	Colori dei messaggi inviati
button_size	Dimensione in pixel del pulsante flottante
position_top, position_bottom, position_left, position_right	Margini di posizionamento del pulsante
font_family	Famiglia di carattere
border_color, text_primary_color, text_secondary_color, smallchat_icon_color*	Solo variante nuova

* Parametri disponibili solo nella variante grafica nuova.

window.askmeChatWidget.setUIParams({
  header_bg_color: '#202020',
  header_text_color: '#FFFFFF',
  button_bg_color: '#FFBB00',
  button_text_color: '#202020',
});

overrideConfigurations({ texts, settings, ui }) permette di sovrascrivere in blocco testi, opzioni di comportamento e parametri grafici in un'unica chiamata; setConnectionParams(params) sovrascrive singoli parametri di connessione/comportamento equivalenti a quelli del passo Configurazioni.

Controllo apertura/chiusura e messaggi

Metodo	Effetto
openCloseChat()	Apre o chiude il pannello di chat in base allo stato corrente
openCloseSettings()	Apre o chiude il menu impostazioni del widget
sendMessage(text)	Invia un messaggio come se fosse digitato dal visitatore
sendAttachment(file)	Invia un allegato
resetChat()	Reinizializza il widget preservando i dati cliente (vedi sopra)
closeChat() / leaveChat()	Chiude la conversazione corrente
setPosition(top, bottom, left, right)	Riposiziona il pulsante flottante a runtime, con la stessa semantica dei margini del passo Grafica
isChatOpened(), isVisible(), isHeaderCollapsed()	Verificano lo stato corrente del widget
checkWidgetVisibility()	Rivaluta le regole di pagine incluse/escluse per l'URL corrente

window.askmeChatWidget.openCloseChat();
window.askmeChatWidget.setPosition(null, 20, null, 20); // in basso a destra, 20px

note

I metodi setPositionTop, setPositionBottom, setPositionLeft e setPositionRight esistono nel codice ma presentano un difetto noto nel passaggio dei parametri: non vanno utilizzati. Per il posizionamento programmatico usare esclusivamente setPosition(top, bottom, left, right).

Altre funzioni disponibili includono il controllo del canale vocale (startInputVoice/stopInputVoice, convertSpeechToText, convertTextToSpeech, playVoice, subordinate all'integrazione Google Cloud del tenant) e delle campagne proattive (startCampaigns, startCampaign, isCompletedCampaign).

Compatibilità dei bundle

Il widget è distribuito in due varianti (vedi Il widget di chat): l'oggetto window.askmeChatWidget e le API di base sono identiche in entrambe, ma alcune funzionalità sono disponibili solo nella variante nuova.

Funzionalità	Classica (askmechat.widget.js)	Nuova (askme.chat.widget.js)
API di ciclo di vita, eventi, dati cliente, setUIParams di base	Sì	Sì
Evento askmechat:chatClosed	No	Sì
Parametri grafici border_color, text_primary_color, text_secondary_color, smallchat_icon_color	No	Sì
Editing dei messaggi inviati (canEditMessage, startEditMessage, submitEditMessage, ecc.)	No	Sì
Gestione avanzata dell'input (focusMessageInput, showInputValidationError/hideInputValidationError, showInactivityPrompt)	No	Sì
Lingua interfaccia spagnolo	No	Sì (oltre a italiano/inglese)

Problemi comuni

Problema	Causa	Soluzione
Un metodo dell'API risulta undefined	Il metodo è disponibile solo nella variante nuova, oppure è stato invocato prima dell'evento askmeChatWidgetLoaded	Verificare la variante grafica del widget e agganciare la chiamata all'evento di caricamento
Le variabili CSS impostate da codice non hanno effetto	Le CSS custom property --awc-* sono risolte a compile-time	Usare setUIParams(...) oppure il CSS personalizzato lato backend
Il riposizionamento del pulsante produce risultati inattesi	Uso dei metodi setPositionTop/Bottom/Left/Right, non affidabili	Usare setPosition(top, bottom, left, right)
addCustomerInfo non sembra avere effetto	Il metodo è stato invocato prima che il widget fosse pronto	Invocarlo sempre all'interno del listener dell'evento askmeChatWidgetLoaded

Pagine correlate

• Installare il widget sul sito
• Personalizzazione grafica
• CSS personalizzato
• Il widget di chat
• API di Askme Chat