Widget SDK

Översikt

När widget-skriptet laddas registrerar det en global på window.CompaninWidget. Det ger din sida ett litet, beroendefritt API för att öppna och stänga widgeten, skicka meddelanden, identifiera den aktuella användaren och prenumerera på livscykelhändelser — utan att koppla din kod till widgetens interna funktioner.

Skriptet laddas asynkront, så den globala visas ett ögonblick efter att din sida gör det. Skydda ditt första anrop (window.CompaninWidget?.open()), eller prenumerera på widget.ready-händelsen. När du bäddar in mer än en widget på en sida registreras varje instans också av sitt data-instance-id under window.CompaninWidgets — använd CompaninWidgets.get(‘id’) för att rikta in dig på en specifik; window.CompaninWidget pekar på den senast skapade instansen.

JavaScript API

Anropa dessa på window.CompaninWidget när widgeten har laddats. Metoder som inte har någon effekt innan iframe:en är redo misslyckas tyst och loggar till konsolen istället för att kasta ett fel, så ett felaktigt tidsinställt anrop bryter aldrig din sida.

• open() / close() / toggle() — Expandera, kollapsa eller vänd på chattpanelen.
• show() / hide() — Visa eller dölj hela widgetbehållaren, inklusive lanseraren.
• isOpen() / isVisible() / isReady() — Läs det aktuella panelen, containern och bootstrap-tillståndet.
• sendMessage(text) — Skicka ett meddelande som besökare och få ett svar.
• prefill(text) — Koppla en användaridentitet till sessionen — { userId, email, name, metadata, token }. Se nedan.
• identify(user) — Bifoga en användaridentitet till sessionen — { userId, email, name, metadata, token }. Se nedan.
• setContext(data) — Skjut sidnivåkontext; widgeten slår samman den i nästa begärans page_context.
• setTheme(theme) — Byt palett vid körning — 'ljus', 'mörk' eller 'system'. Överskrider instrumentbrädans tema och data-tema.
• trackConversion(goal, value, opts) — Registrera ett mål som nåtts efter en chatt, t.ex. trackConversion('checkout', 79.00, { currency: 'EUR' }).
• beforeSend(fn) / afterReceive(fn) — Inspektera, skriv om eller avbryt meddelanden på väg ut eller in. Återvänd null för att avbryta.
• on(event, handler) — Prenumerera på en livscykelhändelse; returnerar en avprenumerera-funktion. off(event, handler) fungerar också.
• update(config) — Tillämpa en delvis widgetkonfiguration utan att ladda om sidan.
• reset() — Rensa den aktuella konversationen och starta en ny session.
• enableDebug() / disableDebug() — Slå på eller av detaljerad konsol-loggning på en live-sida.
• grantConsent() / revokeConsent() — Berätta för widgeten om den får använda webblagring. Krävs för samtyckesbaserade distributioner.
• getVersion() / destroy() — Läs loader-versionen, eller riv ner widgeten och ta bort den från sidan.

<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>

Identifiera inloggade användare

Låt widgeten känna igen dina inloggade användare så att konversationer blir personliga och återställs över deras enheter. Din server signerar en kortlivad token som widgeten överlämnar till Companin; Companin verifierar den och kopplar sessionen till den användaren.

1. Hämta din signeringshemlighet från instrumentpanelen och kopiera den till din servers miljö. Exponera den aldrig i webbläsarkod.

2. Signera en token på din server — en kortlivad HS256 JWT som bär användarens id (sub), e-post och namn:

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. Ge tokenet till widgeten. På en server-renderad sida, lägg till det i script-taggen som data-user-token; i en en-sidig app, kalla på identify() efter att användaren loggar in:

<!-- 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>

Ett ogiltigt eller utgånget token ignoreras — widgeten förblir helt anonym, så det är säkert att alltid försöka identifiering.

• Signera tokenet på din server – skicka aldrig signing secret till webbläsaren.
• Håll tokenet kortlivat (några minuter); det behövs endast när widgeten laddas eller när du anropar identify().
• Det samma sub-värde över enheter är vad som återställer en användares konversation och personaliserar svar.
• Att rotera hemligheten i instrumentpanelen ogiltigförklarar tokens signerade med den gamla – uppdatera din server samtidigt.
• identify() accepterar också userId, email, name och metadata direkt när du bara vill märka konversationen och inte verifiera identitet.
• För dokumentationswidgeten, anropa window.CompaninDocsWidget.identify(...) istället för window.CompaninWidget.

Avlyssning av meddelanden

beforeSend(fn) kör din funktion på varje utgående besökarmeddelande innan det når API:et; afterReceive(fn) körs på varje agentens svar innan det renderas. Återvänd en modifierad sträng för att ändra den, eller återvänd null för att avbryta. Båda accepterar ett Promise, så du kan först anropa din egen tjänst, och flera interceptorer körs i registreringsordning.

// 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');});

Spåra konverteringar

Anropa trackConversion() när en besökare når ett mål så att instrumentpanelen kan attribuera det till den konversation som hjälpte. Skicka en målslug och, när det finns en, ett monetärt värde och valuta. Vanliga slugs är add_to_cart, checkout, signup, lead och booking, men vilken slug du än väljer accepteras. Skicka en dedupKey (eller en metadata.order_id) så att en omladdning inte kan dubbelräkna samma beställning.

// 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');

Livscykelhändelser

Prenumerera med CompaninWidget.on(name, handler), som returnerar en avprenumerera-funktion. Handlers får ett kuvert: { event, timestamp, data, context } — nyttolasten finns i kuvert.data. Senare prenumeranter får omedelbart det senaste kuvertet för det evenemanget, så du missar aldrig ett genom att ansluta efter inläsning.

• widget.ready — Iframe:en avslutade sin bootstrap-handshake och API:et är live.
• open / close — Chattpanelen har expanderats eller kollapsat. Alias: widget.opened, widget.closed.
• message — Besökaren skickade ett meddelande. Alias: message.sent.
• response — Agenten svarade. Alias: message.received.
• conversation.created / conversation.closed — En konversation har startat eller avslutats.
• user.updated — identify() anropades eller den verifierade användaridentiteten ändrades.
• file.uploaded — Besökaren bifogade en fil.
• conversion.tracked — trackConversion() registrerade ett mål.
• theme.change — Den aktiva ljus/mörk paletten har ändrats.
• authFailure — Autentisering med backend misslyckades. Alias: auth.failed.
• error — Widgeten rapporterade ett fel.

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();

DOM-händelser

Varje livscykelhändelse skickas också på fönstret som en CustomEvent med namnet companin-widget:<event> — till exempel companin-widget:response. Samma kuvert finns på event.detail. Använd dessa när den lyssnande koden inte kan hålla en referens till widgeten, såsom en analys-tag eller en tagg-hanterare-snutt.

// 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' });});