Steuern Sie das Widget von Ihrer Seite und halten Sie jedes Gespräch widerstandsfähig – automatische Wiederverbindung, Nachrichtenwiederholung, Offline-Erkennung, Zeitüberschreitungen und freundliche Fehlerbehandlung.
Sobald das Widget-Skript geladen ist, registriert Companin eine Hostbrücke unter window.CompaninWidgetHost. Es gibt Ihrer Seite eine kleine, abhängigkeitfreie API, um das Widget zu öffnen und zu schließen, Nachrichten zu senden, den Status zu lesen und sich für Lebenszyklusereignisse anzumelden – ohne Ihren Code an die Interna des Widgets zu koppeln.
Die Brücke fügt auch eine Zuverlässigkeitsschicht über dem Widget hinzu: Nachrichten werden während des Offline-Seins in eine Warteschlange gestellt, automatisch wiederholt, wenn die Verbindung zurückkehrt, zeitlich begrenzt, wenn keine Antwort eintrifft, und das Widget verbindet sich nach vorübergehenden Fehlern automatisch wieder. Jede Statusänderung wird als DOM-Ereignis angezeigt, sodass Sie in Ihrer eigenen Benutzeroberfläche reagieren können.
Rufen Sie diese Methoden auf window.CompaninWidgetHost auf, nachdem das Widget geladen wurde. Sie sind sichere No-ops, wenn das Widget noch nicht bereit ist, sodass Sie jeden Aufruf nie schützen müssen.
open() / close() / toggle() — Zeigen Sie das Widget-Panel an, verstecken oder drehen Sie es um.sendText(text) — Senden Sie eine einfache Textnachricht als Besucher.sendPayload(payload) — Senden Sie eine strukturierte Nachricht oder ein Befehlsobjekt.sendSafe(payload) — Senden Sie über die Zuverlässigkeitsschicht – in der Warteschlange, wenn offline, und durch alle Interzeptoren weitergeleitet.sendWithTimeout(payload, ms) — Senden Sie und geben Sie ein Zeitüberschreitungsereignis aus, wenn innerhalb von ms (Standard 10000) keine Antwort eintrifft.intercept(fn) — Registrieren Sie eine Funktion, die ausgehende Nachrichten umschreiben oder abbrechen kann; gibt eine Abmeldefunktion zurück.getState() — Lesen Sie den aktuellen Hoststatus: Öffnungsstatus, zuletzt gesendete und empfangene Nachricht, Online-Flag und Befehlsverlauf.getIsOnline() — Ob der Host die Verbindung derzeit als online betrachtet.drainRetryQueue() — Manuelles Leeren aller Nachrichten, die während des Offline-Seins in der Warteschlange standen.cleanup() — Abmelden aller Zuhörer – rufen Sie dies auf, bevor Sie das Widget entfernen.<script> window.addEventListener('load', function () { var host = window.CompaninWidgetHost; if (!host) return; host.open(); host.sendText('Hi! I have a question about pricing.'); console.log(host.getState()); });</script>Lassen Sie das Widget Ihre angemeldeten Benutzer erkennen, damit Gespräche personalisiert und über ihre Geräte hinweg wiederhergestellt werden. Ihr Server signiert ein kurzlebiges Token, das das Widget an Companin übergibt; Companin überprüft es und verknüpft die Sitzung mit diesem Benutzer.
1. Holen Sie sich Ihr Signaturgeheimnis. Öffnen Sie im Dashboard Installieren → Angemeldete Benutzer → Geheimnis generieren, und kopieren Sie es dann in die Umgebung Ihres Servers. Geben Sie es niemals im Browsercode preis.
2. Signieren Sie ein Token auf Ihrem Server – ein kurzlebiges HS256 JWT, das die Benutzer-ID (sub), E-Mail und Namen trägt:
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. Geben Sie das Token an das Widget weiter. Fügen Sie es auf einer servergerenderten Seite dem Skript-Tag als data-user-token hinzu; in einer Single-Page-App rufen Sie identify() auf, nachdem sich der Benutzer angemeldet hat:
<!-- Option A: server-rendered page — put the signed token on the script tag --><script src="https://YOUR_WIDGET_HOST/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>Ein schlechtes oder abgelaufenes Token wird ignoriert – das Widget bleibt einfach anonym, sodass es sicher ist, immer eine Identifizierung zu versuchen.
Verwenden Sie sendSafe anstelle von sendText, wenn die Lieferung wichtig ist. Der Host überwacht die Online- und Offline-Ereignisse des Browsers; während offline werden Nachrichten in eine Wiederholungswarteschlange hinzugefügt und ein companin:widget:offline-Ereignis wird ausgelöst. Sobald die Verbindung zurückkehrt, wird die Warteschlange automatisch in der Reihenfolge entleert und companin:widget:online wird ausgelöst.
window.CompaninWidgetHost.sendSafe('Track my order #1234');window.addEventListener('companin:widget:offline', function () { showBanner('You are offline — your message will send automatically.');});window.addEventListener('companin:widget:online', function () { showBanner('Back online.');});window.addEventListener('companin:widget:retryDrained', function (e) { showBanner(e.detail.count + ' queued message(s) sent.');});Wickeln Sie ein Senden in sendWithTimeout ein, um gegen eine Antwort zu schützen, die niemals eintrifft. Wenn innerhalb der Zeitüberschreitung (standardmäßig 10 Sekunden) keine Antwort empfangen wird, wird ein companin:widget:timeout-Ereignis ausgelöst, sodass Sie eine freundliche Wiederholungsaufforderung anzeigen können, anstatt den Benutzer warten zu lassen.
window.CompaninWidgetHost.sendWithTimeout('Are you there?', 8000);window.addEventListener('companin:widget:timeout', function () { showRetryPrompt('That took longer than expected. Try again?');});Wenn das Widget einen Fehler meldet, versucht der Host bis zu dreimal, sich mit einer zunehmenden Verzögerung (1,5 s, 3 s, dann 4,5 s) wieder zu verbinden und gibt bei jedem Versuch companin:widget:reconnecting aus. Eine erfolgreiche Antwort setzt den Zähler zurück; wenn alle Versuche fehlschlagen, wird companin:widget:reconnectFailed ausgelöst, sodass Sie elegant zurückfallen können.
window.addEventListener('companin:widget:reconnecting', function (e) { console.log('Reconnecting — attempt', e.detail.attempt, 'in', e.detail.delay, 'ms');});window.addEventListener('companin:widget:reconnectFailed', function () { showBanner('We could not reconnect. Please refresh the page.');});Registrieren Sie einen Interzeptor mit intercept(fn), um jede ausgehende Nachricht zu inspizieren, umzuschreiben oder abzubrechen. Geben Sie eine modifizierte Nutzlast zurück, um sie zu ändern, geben Sie false zurück, um das Senden abzubrechen, oder geben Sie nichts zurück, um sie unverändert durchzulassen. intercept gibt eine Abmeldefunktion zurück.
const stop = window.CompaninWidgetHost.intercept(function (payload) { if (typeof payload === 'string') { if (!payload.trim()) return false; // cancel the send return payload.replace(/[\w.+-]+@[\w-]+\.[\w.-]+/g, '[email]'); } return payload;});// Later, to remove the interceptor:stop();Der Host gibt jede Änderung des Widget-Lebenszyklus als DOM-CustomEvent auf dem Fenster erneut aus, sodass Sie reagieren können, ohne eine Referenz auf das Widget zu halten. Die relevanten Daten befinden sich in event.detail.
companin:widget:open / close — Das Widget-Panel wurde geöffnet oder geschlossen.companin:widget:message / response — Der Besucher hat eine Nachricht gesendet oder der Agent hat geantwortet.companin:widget:authFailure — Die Authentifizierung mit dem Backend ist fehlgeschlagen.companin:widget:error — Das Widget hat einen Fehler gemeldet.companin:widget:offline / online — Der Browser hat seine Verbindung verloren oder wiederhergestellt.companin:widget:queued / retryDrained — Eine Nachricht wurde während des Offline-Seins in die Warteschlange gestellt oder die Warteschlange wurde geleert.companin:widget:reconnecting / reconnectFailed — Ein automatischer Wiederverbindungsversuch wurde gestartet oder alle Versuche wurden erschöpft.companin:widget:timeout — Eine Nachricht hat innerhalb ihrer Zeitüberschreitung keine Antwort erhalten.window.addEventListener('companin:widget:message', function (e) { console.log('Visitor sent:', e.detail.message);});window.addEventListener('companin:widget:response', function (e) { console.log('Agent replied:', e.detail.response);});window.addEventListener('companin:widget:authFailure', function (e) { console.warn('Widget auth failed:', e.detail.error);});Entkoppelte Codes können das Widget steuern, indem sie ein companin:widget:command-Ereignis auslösen, anstatt die API direkt aufzurufen. Senden Sie einen String, um eine Nachricht zu übermitteln, oder ein Detailobjekt wie { action: 'open' } oder { text: 'Hallo' }. Dies ist praktisch für Analytik-Tags, GTM oder andere Skripte, die das Widget nicht importieren sollten.
// Open the widget from anywhere — no widget reference needed.window.dispatchEvent(new CustomEvent('companin:widget:command', { detail: { action: 'open' }}));// Or send a message.window.dispatchEvent(new CustomEvent('companin:widget:command', { detail: { text: 'I need help with billing' }}));Setzen Sie window.__COMPANIN_WIDGET_WEBHOOK_URL auf einen Sammelendpunkt, und der Host leitet Öffnungs-, Schließ-, Nachrichten- und Antwortereignisse als JSON über navigator.sendBeacon weiter (fällt auf einen Keepalive-Fetch zurück). Dies ist eine leichte, clientseitige Ergänzung zu serverseitigen Webhooks – nützlich für First-Party-Analytik.
// Point the host at your collector before the widget loads.window.__COMPANIN_WIDGET_WEBHOOK_URL = 'https://example.com/collect/widget';