Integrazione Widget

Il widget Askme Chat è uno snippet JavaScript che puoi includere in qualsiasi pagina web per abilitare la chat in tempo reale. Non richiede framework specifici: funziona su qualsiasi sito HTML, WordPress, SPA o applicazione web.

Prerequisito

Prima di integrare il widget devi aver creato almeno una configurazione widget dal pannello di amministrazione in Impostazioni → Widget → Nuovo Widget. Al termine troverai il token univoco da usare nell'embed.

Script tag base

Il modo più semplice per integrare il widget è inserire questo tag <script> prima della chiusura di </body>:

<script
  async
  data-token="IL_TUO_TOKEN"
  src="https://chat.askme.it/widget/askme.chat.widget.js">
</script>

Il widget si inizializza automaticamente al caricamento della pagina. Non è necessario nessun altro codice.

Varianti del bundle

A partire dalla versione 1.67.36 il widget è distribuito in due varianti, allineate alla stessa numerazione di versione e alle stesse API:

Variante	Bundle	Quando viene usata
Standard	`askme.chat.widget.js`	Default per tutti i widget creati dopo l'introduzione delle due varianti
Classica (legacy)	`askmechat.widget.js`	Mantiene la grafica precedente; i widget creati prima della 1.67.36 la usano implicitamente

La scelta avviene dal backoffice Askme Chat in fase di creazione o modifica del widget tramite l'opzione "Usa la grafica classica del widget": quando attiva il codice di integrazione generato fa riferimento al bundle askmechat.widget.js, altrimenti a askme.chat.widget.js. Indipendentemente dalla variante, l'oggetto globale esposto in pagina rimane window.askmeChatWidget e tutte le API descritte sotto sono utilizzabili allo stesso modo.

Attributi `data-*`

Attributo	Obbligatorio	Descrizione
`data-token`	Sì	Token univoco della configurazione widget. Lo trovi nel pannello admin sotto Widget → Dettaglio → Token.
`data-endpoint`	No	URL completo dell'API pubblica (es. `https://chat.askme.it/public/api`). Necessario solo se il file JS è servito da un dominio diverso da quello dell'istanza.
`data-language`	No	Forza la lingua dell'interfaccia: `it`, `en`, `es`. Se assente, viene letto l'attributo `lang` del tag `<html>`, poi il default configurato lato server.

WordPress

È disponibile un plugin dedicato scaricabile dal pannello admin sotto Integrazioni → WordPress. Il plugin inserisce automaticamente lo script tag in tutte le pagine del sito. In alternativa puoi incollare lo script tag nel tema tramite functions.php:

function askme_chat_widget() {
    echo '<script async data-token="IL_TUO_TOKEN" src="https://chat.askme.it/widget/askme.chat.widget.js"></script>';
}
add_action('wp_footer', 'askme_chat_widget');

API JavaScript

Dopo il caricamento, il widget espone l'oggetto globale window.askmeChatWidget. Tramite questo oggetto è possibile controllare il widget programmaticamente: avviarlo manualmente, aprirlo o chiuderlo, iniettare informazioni utente, distruggerlo, ricaricarlo con un altro token o resettarlo.

Evento di caricamento

Tutte le API devono essere invocate dopo che il widget è stato caricato in pagina. Il widget emette l'evento askmeChatWidgetLoaded al termine dell'inizializzazione: aggancia un listener prima di chiamare qualsiasi metodo.

document.addEventListener('askmeChatWidgetLoaded', function () {
  // il widget è pronto
  // window.askmeChatWidget.init();
});

In alternativa, con jQuery:

$(document).on('askmeChatWidgetLoaded', function () {
  // il widget è pronto
});

Compatibilità versioni

Le API destroy(), loadWithToken() e reload() sono disponibili a partire dalla versione 1.68.14. Su versioni precedenti queste funzioni non sono presenti e la loro invocazione genera un errore JavaScript. Tutte le altre API sono disponibili da sempre.

Avvio del widget — `init()`

Avvia il componente di chat e lo rende visibile nella pagina. Da usare quando la configurazione del widget non lo rende visibile automaticamente allo startup (ad esempio se vuoi mostrarlo solo a utenti autenticati o in base ad altre condizioni applicative).

window.askmeChatWidget.init();

Apertura/chiusura — `openCloseChat()`

Apre o chiude il pannello di chat in base allo stato corrente. Utile per agganciare un pulsante "Apri chat" personalizzato sulla pagina.

window.askmeChatWidget.openCloseChat();

Iniezione informazioni utente — `addAdditionalInfo()`

Allo startup, prima dell'inizio della chat, è possibile iniettare nel componente alcune variabili per inizializzare una sessione personalizzata. Per identificare l'utente sono previste tre chiavi convenzionali; chiavi diverse vengono comunque accettate e propagate al backend.

window.askmeChatWidget.addAdditionalInfo(key, value);

Chiave	Descrizione
`name`	Nome dell'utente autenticato
`matricola`	Identificativo univoco dell'utente. Può essere anche l'indirizzo email
`email`	Email dell'utente

Esempio:

document.addEventListener('askmeChatWidgetLoaded', function () {
  window.askmeChatWidget.addAdditionalInfo('name', 'Mario Rossi');
  window.askmeChatWidget.addAdditionalInfo('matricola', 'EMP-1234');
  window.askmeChatWidget.addAdditionalInfo('email', '[email protected]');
});

Reset — `resetChat()`

Inizializza nuovamente il componente di chat preservando l'identità dell'utente. Vengono salvati i valori di matricola, name ed email; il widget viene ricostruito da zero (rimozione del DOM e nuova init()) e i tre valori sono ripristinati nella nuova istanza. Al termine il pannello di chat viene automaticamente riaperto, indipendentemente dallo stato precedente.

window.askmeChatWidget.resetChat();

Note operative:

Va invocata solo dopo che il widget è caricato in pagina (evento askmeChatWidgetLoaded); altrimenti l'API non è disponibile e l'invocazione genera un errore.
Vengono preservate solo matricola, name ed email. Eventuali altre informazioni precedentemente impostate via addAdditionalInfo() vanno reimpostate manualmente dopo il reset.
I cookie e le voci di localStorage della sessione non vengono cancellati: la sessione lato backend è mantenuta. Per una pulizia completa usa reload() (vedi sotto).

Distruzione — `destroy()`

Distrugge completamente l'istanza corrente del widget. L'operazione esegue, in ordine:

Chiusura della stanza chat e disconnessione del client
Cancellazione di tutti i cookie utilizzati dal widget e dal core (campagne, sessione, identificativo univoco anonimo)
Pulizia delle voci di localStorage relative alla sessione
Interruzione di tutti i timer attivi
Reset dello stato interno
Rimozione del DOM del widget dalla pagina

window.askmeChatWidget.destroy();

Dopo l'invocazione il bottone di chat non è più presente in pagina e l'istanza non è più operativa. Per riutilizzarla occorre richiamare init(), loadWithToken() o reload().

Ricaricamento con un nuovo token — `loadWithToken()`

Distrugge l'istanza corrente del widget (con la stessa logica di destroy()) e la ricarica utilizzando un nuovo token. Pensata per scenari in cui l'utente effettua login o logout e l'applicazione deve associarlo a un widget diverso senza ricaricare l'intera pagina.

Il nuovo token deve essere nel formato canonico #XXXX-... (come quello fornito tramite data-token).

window.askmeChatWidget.loadWithToken(newToken, callback);

Parametro	Descrizione
`newToken`	Nuovo token da utilizzare per il caricamento del widget
`callback`	(Opzionale) funzione invocata al termine del ricaricamento

Esempio in seguito al login dell'utente:

window.askmeChatWidget.loadWithToken(
  '#NEWTOKEN-1234-5678-9abc-def012345678',
  function () {
    window.askmeChatWidget.addAdditionalInfo('userId', currentUser.id);
  }
);

Reload — `reload()`

Distrugge e ricarica il widget mantenendo il token corrente. Equivalente a loadWithToken() con il token già attivo: si usa per riportare il widget a uno stato pulito (sessione, cookie e DOM ricreati da zero) senza ricaricare l'intera pagina.

window.askmeChatWidget.reload(callback);

Parametro	Descrizione
`callback`	(Opzionale) funzione invocata al termine del ricaricamento

Riepilogo metodi

Metodo	Disponibile da	Effetto
`init()`	sempre	Avvia il widget e lo rende visibile
`openCloseChat()`	sempre	Apre o chiude il pannello in base allo stato
`addAdditionalInfo(key, value)`	sempre	Inietta variabili di sessione (incluso `name`/`matricola`/`email`)
`resetChat()`	sempre	Re-init preservando `matricola`/`name`/`email`; sessione backend mantenuta
`destroy()`	1.68.14+	Distrugge l'istanza, pulisce cookie/storage, rimuove il DOM
`loadWithToken(token, cb?)`	1.68.14+	Distrugge e ricarica con un nuovo token
`reload(cb?)`	1.68.14+	Distrugge e ricarica con il token corrente

Visibilità per pagina

Puoi limitare le pagine in cui il widget è visibile direttamente dalla configurazione lato server (Widget → Impostazioni → Pagine), usando espressioni regolari:

Campo	Comportamento
Pagine incluse	Il widget compare solo sugli URL che corrispondono
Pagine escluse	Il widget è nascosto sugli URL che corrispondono

Esempio: mostrare il widget solo nella sezione supporto ed escludere l'area admin:

Pagine incluse:  ^https://esempio\.it/supporto
Pagine escluse:  ^https://esempio\.it/admin

Personalizzazione CSS

Le opzioni grafiche principali (colori, dimensioni, posizione) sono configurabili dal pannello admin senza toccare il codice. Per personalizzazioni avanzate puoi inserire CSS personalizzato nel campo Widget → CSS Personalizzato.

I selettori principali:

Selettore	Elemento
`.askme-chat-widget`	Contenitore radice
`.askme-chat-widget .chat-header`	Barra dell'intestazione
`.askme-chat-widget .smallchat`	Pulsante flottante
`.askme-chat-widget .chatbox`	Finestra chat
`.askme-chat-widget .message-received`	Messaggio ricevuto
`.askme-chat-widget .message-sent`	Messaggio inviato
`.askme-chat-widget .msg-box`	Area di input

Risoluzione problemi

Il widget non appare

Verifica che il data-token sia corretto e che il widget sia attivo nel pannello admin.
Controlla la console del browser per errori di rete (CORS, 404 sul file JS).
Accertati che l'URL corrente non sia escluso dalle regole di visibilità per pagina.

Il widget mostra la lingua sbagliata

Verifica l'attributo lang del tag <html> della tua pagina oppure usa data-language per forzarlo.

Devo mostrare il widget solo dopo il consenso cookie

Carica lo script dinamicamente dopo che l'utente ha accettato, tramite JavaScript:

function loadAskmeWidget() {
  const s = document.createElement('script');
  s.async = true;
  s.dataset.token = 'IL_TUO_TOKEN';
  s.src = 'https://chat.askme.it/widget/askme.chat.widget.js';
  document.body.appendChild(s);
}

Script tag base​

Varianti del bundle​

Attributi data-*​

WordPress​

API JavaScript​

Evento di caricamento​

Avvio del widget — init()​

Apertura/chiusura — openCloseChat()​

Iniezione informazioni utente — addAdditionalInfo()​

Reset — resetChat()​

Distruzione — destroy()​

Ricaricamento con un nuovo token — loadWithToken()​

Reload — reload()​

Riepilogo metodi​

Visibilità per pagina​

Personalizzazione CSS​

Risoluzione problemi​