Stuur de widget vanaf je pagina: open en sluit deze, stuur berichten, identificeer ingelogde gebruikers, volg conversies en reageer op levenscyclusgebeurtenissen.
Zodra het widget-script is geladen, registreert het een globale variabele op window.CompaninWidget. Het biedt je pagina een kleine, afhankelijkheidsvrije API om de widget te openen en te sluiten, berichten te verzenden, de huidige gebruiker te identificeren en je in te schrijven voor levenscyclusgebeurtenissen — zonder je code te koppelen aan de interne werking van de widget.
Het script laadt asynchroon, dus de globale verschijnt een moment nadat je pagina dat doet. Bescherm je eerste aanroep (window.CompaninWidget?.open()), of abonneer je op de widget.ready gebeurtenis. Wanneer je meer dan één widget op een pagina insluit, wordt elke instantie ook geregistreerd onder zijn data-instance-id onder window.CompaninWidgets — gebruik CompaninWidgets.get(‘id’) om een specifieke te targeten; window.CompaninWidget wijst naar de meest recent gemaakte instantie.
Roep deze aan op window.CompaninWidget zodra de widget is geladen. Methoden die geen effect hebben voordat de iframe klaar is, falen stilletjes en loggen naar de console in plaats van een fout te genereren, zodat een verkeerd getimede aanroep je pagina nooit breekt.
open() / close() / toggle() — Vouw het chatpaneel uit, in of om.show() / hide() — Toon of verberg de hele widgetcontainer, inclusief de launcher.isOpen() / isVisible() / isReady() — Lees de huidige paneel-, container- en bootstrapstatus.sendMessage(text) — Stuur een bericht als de bezoeker en ontvang een antwoord.prefill(text) — Koppel een gebruikersidentiteit aan de sessie — { userId, email, name, metadata, token }. Zie hieronder.identify(user) — Koppel een gebruikersidentiteit aan de sessie — { userId, email, name, metadata, token }. Zie hieronder.setContext(data) — Duw de paginagrootte context; de widget voegt het samen in de page_context van het volgende verzoek.setTheme(theme) — Schakel palet tijdens runtime — 'licht', 'donker' of 'systeem'. Overschrijft het dashboardthema en data-theme.trackConversion(goal, value, opts) — Registreer een doel dat is bereikt na een chat, bijv. trackConversion('checkout', 79.00, { currency: 'EUR' }).beforeSend(fn) / afterReceive(fn) — Inspecteer, herschrijf of annuleer berichten op hun weg naar buiten of naar binnen. Geef null terug om te annuleren.on(event, handler) — Abonneer je op een lifecycle-evenement; retourneert een unsubscribe-functie. off(event, handler) werkt ook.update(config) — Pas een gedeeltelijke widgetconfiguratie live toe zonder de pagina opnieuw te laden.reset() — Wis het huidige gesprek en begin een nieuwe sessie.enableDebug() / disableDebug() — Zet uitgebreide console logging aan of uit op een live pagina.grantConsent() / revokeConsent() — Vertel de widget of het browseropslag mag gebruiken. Vereist voor toestemming-gebaseerde implementaties.getVersion() / destroy() — Lees de loaderversie, of haal de widget naar beneden en verwijder deze van de 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>Laat de widget uw ingelogde gebruikers herkennen, zodat gesprekken gepersonaliseerd zijn en op hun apparaten worden hersteld. Uw server ondertekent een kortlevende token die de widget aan Companin overhandigt; Companin verifieert deze en koppelt de sessie aan die gebruiker.
1. Haal je handtekening geheim op uit het dashboard en kopieer het naar de omgeving van je server. Stel het nooit bloot in browsercode.
2. Onderteken een token op je server — een kortlevende HS256 JWT met de gebruikers-id (sub), e-mailadres en naam:
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. Geef het token aan de widget. Op een server-gerenderde pagina, voeg het toe aan de script-tag als data-user-token; in een single-page app, roep identify() aan nadat de gebruiker is ingelogd:
<!-- 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>Een slechte of verlopen token wordt genegeerd — de widget blijft gewoon anoniem, dus het is veilig om altijd identificatie te proberen.
beforeSend(fn) voert je functie uit op elk uitgaand bezoekersbericht voordat het de API bereikt; afterReceive(fn) wordt uitgevoerd op elke agentantwoord voordat het wordt weergegeven. Geef een gewijzigde string terug om het te veranderen, of geef null terug om te annuleren. Beide accepteren een Promise, zodat je eerst je eigen service kunt aanroepen, en meerdere interceptors worden uitgevoerd in registratVolgorde.
// 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');});Roep trackConversion() aan wanneer een bezoeker een doel bereikt, zodat het dashboard het kan toeschrijven aan het gesprek dat heeft geholpen. Geef een doel slug door en, wanneer er een is, een monetair bedrag en valuta. Veelvoorkomende slugs zijn add_to_cart, checkout, signup, lead en booking, maar elke slug die je kiest is geaccepteerd. Geef een dedupKey (of een metadata.order_id) door zodat een herlaadbeurt dezelfde bestelling niet dubbel kan tellen.
// 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');Abonneer je met CompaninWidget.on(name, handler), wat een afmeldfunctie retourneert. Handlers ontvangen een envelop: { event, timestamp, data, context } — de payload bevindt zich in envelope.data. Late abonnees ontvangen onmiddellijk de laatste envelop voor dat evenement, zodat je er nooit een mist door je aan te sluiten na het laden.
widget.ready — De iframe heeft zijn bootstrap-handshake voltooid en de API is live.open / close — Het chatpaneel was uitgebreid of ingeklapt. Aliassen: widget.opened, widget.closed.message — De bezoeker heeft een bericht verzonden. Alias: message.sent.response — De agent heeft geantwoord. Alias: message.received.conversation.created / conversation.closed — Een gesprek is begonnen of beëindigd.user.updated — identify() werd aangeroepen of de geverifieerde gebruikersidentiteit is veranderd.file.uploaded — De bezoeker heeft een bestand bijgevoegd.conversion.tracked — trackConversion() heeft een doel geregistreerd.theme.change — Het actieve licht/donker palet is veranderd.authFailure — Authenticatie met de backend is mislukt. Alias: auth.failed.error — De widget heeft een fout gerapporteerd.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();Elke levenscyclusgebeurtenis wordt ook verzonden op window als een CustomEvent genaamd companin-widget:<event> — bijvoorbeeld companin-widget:response. Dezelfde envelop is op event.detail. Gebruik deze wanneer de luistercode geen referentie naar de widget kan vasthouden, zoals een analytics-tag of een 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' });});