Steuere das Widget von deiner Seite: öffne und schließe es, sende Nachrichten, identifiziere angemeldete Benutzer, verfolge Konversionen und reagiere auf Lebenszyklusereignisse.
Sobald das Widget-Skript geladen ist, registriert es ein globales Objekt unter window.CompaninWidget. Es bietet Ihrer Seite eine kleine, abhängigkeitfreie API, um das Widget zu öffnen und zu schließen, Nachrichten zu senden, den aktuellen Benutzer zu identifizieren und sich für Lebenszyklusereignisse anzumelden — ohne Ihren Code an die internen Abläufe des Widgets zu koppeln.
Das Skript wird asynchron geladen, sodass das globale Objekt einen Moment nach Ihrer Seite erscheint. Schützen Sie Ihren ersten Aufruf (window.CompaninWidget?.open()), oder abonnieren Sie das widget.ready-Ereignis. Wenn Sie mehr als ein Widget auf einer Seite einbetten, wird jede Instanz auch unter window.CompaninWidgets mit ihrer data-instance-id registriert — verwenden Sie CompaninWidgets.get(‘id’), um ein bestimmtes anzusprechen; window.CompaninWidget verweist auf die zuletzt erstellte Instanz.
Rufen Sie diese auf window.CompaninWidget auf, sobald das Widget geladen ist. Methoden, die keine Wirkung haben, bevor das iframe bereit ist, schlagen stillschweigend fehl und protokollieren in der Konsole, anstatt eine Ausnahme auszulösen, sodass ein falsch getimter Aufruf Ihre Seite niemals beschädigt.
open() / close() / toggle() — Erweitern, reduzieren oder umdrehen Sie das Chat-Panel.show() / hide() — Zeige oder verstecke den gesamten Widget-Container, einschließlich des Launchers.isOpen() / isVisible() / isReady() — Lese den aktuellen Panel-, Container- und Bootstrap-Zustand.sendMessage(text) — Senden Sie eine Nachricht als Besucher und erhalten Sie eine Antwort.prefill(text) — Bitte geben Sie den Text ein, den Sie übersetzen möchten.identify(user) — Fügen Sie eine Benutzeridentität zur Sitzung hinzu — { userId, email, name, metadata, token }. Siehe unten.setContext(data) — Drücken Sie den seitenbezogenen Kontext; das Widget fügt ihn in den page_context der nächsten Anfrage ein.setTheme(theme) — Wechseln Sie die Palette zur Laufzeit — 'hell', 'dunkel' oder 'System'. Überschreibt das Dashboard-Thema und data-theme.trackConversion(goal, value, opts) — Aufzeichnen eines erreichten Ziels nach einem Chat, z.B. trackConversion('checkout', 79.00, { currency: 'EUR' }).beforeSend(fn) / afterReceive(fn) — Überprüfen, umschreiben oder stornieren Sie Nachrichten auf ihrem Weg nach draußen oder hinein. Geben Sie null zurück, um zu stornieren.on(event, handler) — Abonnieren Sie ein Lebenszyklusereignis; gibt eine Abmeldefunktion zurück. off(event, handler) funktioniert ebenfalls.update(config) — Wenden Sie eine teilweise Widget-Konfiguration an, ohne die Seite neu zu laden.reset() — Löschen Sie das aktuelle Gespräch und starten Sie eine neue Sitzung.enableDebug() / disableDebug() — Aktivieren oder deaktivieren Sie ausführliches Konsolenprotokolling auf einer Live-Seite.grantConsent() / revokeConsent() — Teilen Sie dem Widget mit, ob es den Browser-Speicher verwenden darf. Erforderlich für zustimmungspflichtige Bereitstellungen.getVersion() / destroy() — Lese die Loader-Version oder reiß das Widget ab und entferne es von der Seite.<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>Lassen Sie das Widget Ihre angemeldeten Benutzer erkennen, damit Gespräche personalisiert und auf ihren Geräten 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.
Holen Sie sich Ihr Signaturgeheimnis vom Dashboard und kopieren Sie es in die Umgebung Ihres Servers. Stellen Sie es niemals im Browser-Code zur Verfügung.
2. Signieren Sie ein Token auf Ihrem Server — ein kurzlebiges HS256 JWT, das die Benutzer-ID (sub), die E-Mail und den 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. Übergeben Sie das Token an das Widget. Auf einer serverseitig gerenderten Seite fügen Sie es dem Skript-Tag als data-user-token hinzu; in einer Single-Page-App rufen Sie identify() auf, nachdem der Benutzer sich angemeldet hat:
<!-- 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>Ein ungültiges oder abgelaufenes Token wird ignoriert — das Widget bleibt einfach anonym, sodass es sicher ist, immer eine Identifizierung zu versuchen.
beforeSend(fn) führt Ihre Funktion bei jeder ausgehenden Besucher-Nachricht aus, bevor sie die API erreicht; afterReceive(fn) wird bei jeder Agentenantwort ausgeführt, bevor sie gerendert wird. Geben Sie einen modifizierten String zurück, um ihn zu ändern, oder geben Sie null zurück, um abzubrechen. Beide akzeptieren ein Promise, sodass Sie zuerst Ihren eigenen Dienst aufrufen können, und mehrere Interceptoren werden in der Registrierungsreihenfolge ausgeführt.
// 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');});Rufen Sie trackConversion() auf, wenn ein Besucher ein Ziel erreicht, damit das Dashboard es dem Gespräch zuordnen kann, das geholfen hat. Übergeben Sie einen Ziel-Slug und, wenn vorhanden, einen Geldwert und eine Währung. Häufige Slugs sind add_to_cart, checkout, signup, lead und booking, aber jeder Slug, den Sie wählen, wird akzeptiert. Übergeben Sie einen dedupKey (oder eine metadata.order_id), damit ein Neuladen die gleiche Bestellung nicht doppelt zählt.
// 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');Abonnieren Sie mit CompaninWidget.on(name, handler), das eine Abmeldefunktion zurückgibt. Handler erhalten einen Umschlag: { event, timestamp, data, context } — die Nutzlast befindet sich in envelope.data. Späte Abonnenten erhalten sofort den letzten Umschlag für dieses Ereignis, sodass Sie niemals einen verpassen, indem Sie sich nach dem Laden anhängen.
widget.ready — Das iframe hat seinen Bootstrap-Handschlag abgeschlossen und die API ist live.open / close — Das Chat-Panel wurde erweitert oder minimiert. Aliase: widget.opened, widget.closed.message — Der Besucher hat eine Nachricht gesendet. Alias: message.sent.response — Der Agent hat geantwortet. Alias: message.received.conversation.created / conversation.closed — Ein Gespräch wurde gestartet oder beendet.user.updated — identify() wurde aufgerufen oder die verifizierte Benutzeridentität hat sich geändert.file.uploaded — Der Besucher hat eine Datei angehängt.conversion.tracked — trackConversion() hat ein Ziel aufgezeichnet.theme.change — Die aktive Licht-/Dunkelpalette hat sich geändert.authFailure — Die Authentifizierung mit dem Backend ist fehlgeschlagen. Alias: auth.failed.error — Das Widget hat einen Fehler gemeldet.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();Jedes Lifecycle-Ereignis wird auch auf dem Fenster als ein CustomEvent mit dem Namen companin-widget:<event> gesendet — zum Beispiel companin-widget:response. Dasselbe Envelope befindet sich in event.detail. Verwenden Sie diese, wenn der hörende Code keinen Verweis auf das Widget halten kann, wie zum Beispiel ein Analytics-Tag oder ein Tag-Manager-Snippet.
// 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' });});