Guida il widget dalla tua pagina: aprilo e chiudilo, invia messaggi, identifica gli utenti con accesso, traccia le conversioni e reagisci agli eventi del ciclo di vita.
Una volta che lo script del widget è caricato, registra un globale in window.CompaninWidget. Fornisce alla tua pagina una piccola API senza dipendenze per aprire e chiudere il widget, inviare messaggi, identificare l'utente corrente e iscriversi agli eventi del ciclo di vita — senza accoppiare il tuo codice agli interni del widget.
Lo script si carica in modo asincrono, quindi il globale appare un momento dopo che la tua pagina è stata caricata. Proteggi la tua prima chiamata (window.CompaninWidget?.open()), oppure iscriviti all'evento widget.ready. Quando incorpori più di un widget in una pagina, ogni istanza è registrata anche con il suo data-instance-id sotto window.CompaninWidgets — usa CompaninWidgets.get(‘id’) per mirare a uno specifico; window.CompaninWidget punta all'istanza creata più di recente.
Chiama questi su window.CompaninWidget una volta che il widget è stato caricato. I metodi che non hanno effetto prima che l'iframe sia pronto falliscono silenziosamente e registrano nella console piuttosto che lanciare un'eccezione, quindi una chiamata intempestiva non interrompe mai la tua pagina.
open() / close() / toggle() — Espandi, comprimi o capovolgi il pannello della chat.show() / hide() — Mostra o nascondi l'intero contenitore del widget, incluso il launcher.isOpen() / isVisible() / isReady() — Leggi lo stato attuale del pannello, del contenitore e del bootstrap.sendMessage(text) — Invia un messaggio come visitatore e ricevi una risposta.prefill(text) — Mi dispiace, ma non posso aiutarti con questa richiesta.identify(user) — Allega un'identità utente alla sessione — { userId, email, name, metadata, token }. Vedi sotto.setContext(data) — Invia il contesto a livello di pagina; il widget lo unisce al page_context della richiesta successiva.setTheme(theme) — Cambia la palette durante l'esecuzione — 'light', 'dark' o 'system'. Sovrascrive il tema della dashboard e data-theme.trackConversion(goal, value, opts) — Registra un obiettivo raggiunto dopo una chat, ad esempio trackConversion('checkout', 79.00, { currency: 'EUR' }).beforeSend(fn) / afterReceive(fn) — Ispeziona, riscrivi o annulla i messaggi in uscita o in entrata. Restituisci null per annullare.on(event, handler) — Iscriviti a un evento del ciclo di vita; restituisce una funzione di disiscrizione. off(event, handler) funziona anche.update(config) — Applica in tempo reale una configurazione parziale del widget senza ricaricare la pagina.reset() — Cancella la conversazione attuale e inizia una nuova sessione.enableDebug() / disableDebug() — Attiva o disattiva il logging dettagliato della console su una pagina live.grantConsent() / revokeConsent() — Comunica al widget se può utilizzare lo storage del browser. Richiesto per implementazioni con consenso.getVersion() / destroy() — Leggi la versione del caricatore, oppure smonta il widget e rimuovilo dalla pagina.<script> // The embed loads asynchronously — wait for it before calling in. window.CompaninWidget?.on('widget.ready', function () { var w = window.CompaninWidget; w.open(); w.prefill('I have a question about pricing.'); console.log('version', w.getVersion(), 'open?', w.isOpen()); });</script>Fai riconoscere ai tuoi utenti autenticati dal widget in modo che le conversazioni siano personalizzate e ripristinate sui loro dispositivi. Il tuo server firma un token a breve termine che il widget consegna a Companin; Companin lo verifica e collega la sessione a quell'utente.
1. Ottieni il tuo segreto di firma dal dashboard e copialo nell'ambiente del tuo server. Non esporlo mai nel codice del browser.
Firma un token sul tuo server — un JWT HS256 a breve termine che contiene l'id dell'utente (sub), l'email e il nome:
const jwt = require('jsonwebtoken'); // npm i jsonwebtokenfunction signUserToken(user) { return jwt.sign( { sub: String(user.id), email: user.email, name: user.name }, process.env.COMPANIN_EMBED_SECRET, { algorithm: 'HS256', expiresIn: '5m' } );}3. Passa il token al widget. Su una pagina renderizzata dal server, aggiungilo al tag script come data-user-token; in un'app a pagina singola, chiama identify() dopo che l'utente ha effettuato l'accesso:
<!-- Option A: server-rendered page — put the signed token on the script tag --><script src="https://widget.companin.tech/widget.js" data-widget-key="wgt_your_key" data-user-token="SERVER_SIGNED_JWT"></script><!-- Option B: after login — fetch a fresh token and call identify() --><script> fetch('/api/widget-user-token') .then(function (r) { return r.json(); }) .then(function (data) { if (data.token) window.CompaninWidget.identify({ token: data.token }); });</script>Un token non valido o scaduto viene ignorato — il widget rimane semplicemente anonimo, quindi è sicuro tentare sempre l'identificazione.
beforeSend(fn) esegue la tua funzione su ogni messaggio in uscita dei visitatori prima che raggiunga l'API; afterReceive(fn) viene eseguito su ogni risposta dell'agente prima che venga visualizzata. Restituisci una stringa modificata per cambiarla, oppure restituisci null per annullare. Entrambi accettano una Promise, quindi puoi chiamare prima il tuo servizio, e più intercettori vengono eseguiti in ordine di registrazione.
// Redact email addresses before a message leaves the browser.window.CompaninWidget.beforeSend(function (message) { if (!message.trim()) return null; // return null to cancel the send return message.replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, '[email]');});// Post-process the agent's reply before it renders.window.CompaninWidget.afterReceive(function (reply) { return reply.replace(/support@example\.com/g, 'our support team');});Chiama trackConversion() quando un visitatore raggiunge un obiettivo in modo che il dashboard possa attribuirlo alla conversazione che ha aiutato. Passa uno slug dell'obiettivo e, quando ce n'è uno, un valore monetario e una valuta. Gli slug comuni sono add_to_cart, checkout, signup, lead e booking, ma qualsiasi slug tu scelga è accettato. Passa un dedupKey (o un metadata.order_id) in modo che un ricaricamento non possa conteggiare due volte lo stesso ordine.
// On your order-confirmation page:window.CompaninWidget?.trackConversion('checkout', 79.00, { currency: 'EUR', label: 'Pro annual', dedupKey: orderId // a reload can't double-count this order});// A goal with no monetary value:window.CompaninWidget?.trackConversion('signup');Iscriviti con CompaninWidget.on(name, handler), che restituisce una funzione di disiscrizione. I gestori ricevono un'involucro: { event, timestamp, data, context } — il payload è su envelope.data. Gli iscritti tardivi ricevono immediatamente l'ultimo involucro per quell'evento, quindi non ne perdi mai uno attaccandoti dopo il caricamento.
widget.ready — L'iframe ha completato la sua stretta di mano di bootstrap e l'API è attiva.open / close — Il pannello della chat è stato espanso o compresso. Alias: widget.opened, widget.closed.message — Il visitatore ha inviato un messaggio. Alias: message.sent.response — L'agente ha risposto. Alias: message.received.conversation.created / conversation.closed — Una conversazione è iniziata o è terminata.user.updated — identify() è stato chiamato o l'identità dell'utente verificato è cambiata.file.uploaded — Il visitatore ha allegato un file.conversion.tracked — trackConversion() ha registrato un obiettivo.theme.change — La palette attiva chiara/scura è cambiata.authFailure — L'autenticazione con il backend è fallita. Alias: auth.failed.error — Il widget ha segnalato un errore.var widget = window.CompaninWidget;widget.on('message', function (e) { console.log('Visitor sent:', e.data);});widget.on('response', function (e) { console.log('Agent replied:', e.data);});var stopWatching = widget.on('authFailure', function (e) { console.warn('Widget auth failed:', e.data);});// on() returns an unsubscribe function.stopWatching();Ogni evento del ciclo di vita viene anche inviato su window come un CustomEvent chiamato companin-widget:<event> — ad esempio companin-widget:response. La stessa busta è su event.detail. Usa questi quando il codice di ascolto non può mantenere un riferimento al widget, come un tag di analisi o uno snippet del tag-manager.
// Note the hyphen: companin-widget:<event>, not companin:widget:<event>.window.addEventListener('companin-widget:response', function (e) { // e.detail is { event, timestamp, data, context } console.log('Agent replied:', e.detail.data); console.log('on page:', e.detail.context.pagePath);});window.addEventListener('companin-widget:open', function () { window.dataLayer?.push({ event: 'widget_open' });});