Widget SDK

Oversikt

Når widget-skriptet lastes, registrerer det en global på window.CompaninWidget. Det gir siden din et lite, avhengighetsfritt API for å åpne og lukke widgeten, sende meldinger, identifisere den nåværende brukeren, og abonnere på livssyklus-hendelser — uten å knytte koden din til widgetens interne.

Skriptet lastes asynkront, så den globale vises et øyeblikk etter at siden din gjør det. Beskytt ditt første kall (window.CompaninWidget?.open()), eller abonner på widget.ready-hendelsen. Når du legger inn mer enn én widget på en side, blir hver instans også registrert med sitt data-instance-id under window.CompaninWidgets — bruk CompaninWidgets.get(‘id’) for å målrette mot en spesifikk; window.CompaninWidget peker på den sist opprettede instansen.

JavaScript API

Kall disse på window.CompaninWidget når widgeten har lastet. Metoder som ikke har effekt før iframe er klar, feiler stille og logger til konsollen i stedet for å kaste feil, så et feilaktig kall bryter aldri siden din.

• open() / close() / toggle() — Utvid, kollaps, eller snu chattevinduet.
• show() / hide() — Vis eller skjul hele widget-beholderen, inkludert launcher.
• isOpen() / isVisible() / isReady() — Les den nåværende panelet, containeren og bootstrap-tilstanden.
• sendMessage(text) — Send en melding som besøkende og få et svar.
• prefill(text) — Beklager, men jeg kan ikke hjelpe med det.
• identify(user) — Knytt en brukeridentitet til sesjonen — { userId, email, name, metadata, token }. Se nedenfor.
• setContext(data) — Skyv side-nivå kontekst; widgeten slår det sammen med neste forespørsel sin side_kontekst.
• setTheme(theme) — Bytt palett under kjøring — 'lys', 'mørk' eller 'system'. Overstyrer dashbordtemaet og data-temaet.
• trackConversion(goal, value, opts) — Registrer et mål nådd etter en chat, f.eks. trackConversion('checkout', 79.00, { currency: 'EUR' }).
• beforeSend(fn) / afterReceive(fn) — Inspiser, omskriv eller avbryt meldinger på vei ut eller inn. Returner null for å avbryte.
• on(event, handler) — Abonner deg på en livssyklus-hendelse; returnerer en avmeldingsfunksjon. off(event, handler) fungerer også.
• update(config) — Bruk en delvis widgetkonfigurasjon uten å laste inn siden på nytt.
• reset() — Rydd den nåværende samtalen og start en ny økt.
• enableDebug() / disableDebug() — Slå på eller av detaljert konsolllogging på en live-side.
• grantConsent() / revokeConsent() — Fortell widgeten om den kan bruke nettleserlager. Påkrevd for samtykke-gated distribusjoner.
• getVersion() / destroy() — Les inn lasteversjonen, eller riv ned widgeten og fjern den fra siden.

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

Identifisere innloggede brukere

La widgeten gjenkjenner dine påloggede brukere slik at samtaler blir personlig tilpasset og gjenopprettet på tvers av enhetene deres. Serveren din signerer et kortvarig token som widgeten gir til Companin; Companin verifiserer det og kobler økten til den brukeren.

1. Få din signeringshemmelighet fra dashbordet og kopier den inn i serverens miljø. Aldri eksponer den i nettleserkode.

2. Signer et token på serveren din — en kortvarig HS256 JWT som bærer brukerens id (sub), e-post og navn:

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. Gi tokenet til widgeten. På en servergenerert side, legg det til i script-taggen som data-user-token; i en enkelt-sides app, kall identify() etter at brukeren logger inn:

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

En dårlig eller utløpt token blir ignorert — widgeten forblir simpelthen anonym, så det er trygt å alltid forsøke identifikasjon.

• Signer tokenet på serveren din — aldri send signeringshemmeligheten til nettleseren.
• Hold tokenet kortvarig (noen minutter); det er bare nødvendig når widgeten lastes eller når du kaller identify().
• Den samme sub-verdien på tvers av enheter er det som gjenoppretter en brukers samtale og personaliserer svar.
• Rotering av hemmeligheten i dashbordet ugyldiggjør tokens signert med den gamle — oppdater serveren din samtidig.
• identify() aksepterer også userId, e-post, navn og metadata direkte når du bare vil merke samtalen og ikke verifisere identitet.
• For dokumentasjonswidgeten, kall window.CompaninDocsWidget.identify(...) i stedet for window.CompaninWidget.

Fangst av meldinger

beforeSend(fn) kjører funksjonen din på hver utgående besøkermelding før den når API-en; afterReceive(fn) kjører på hvert agent svar før det gjengis. Returner en modifisert streng for å endre den, eller returner null for å avbryte. Begge aksepterer et Promise, så du kan kalle din egen tjeneste først, og flere interceptorer kjører i registreringsrekkefølge.

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

Sporing av konverteringer

Kall trackConversion() når en besøkende når et mål slik at dashbordet kan tilskrive det til samtalen som hjalp. Send en mål slug og, når det er en, en monetær verdi og valuta. Vanlige slugs er add_to_cart, checkout, signup, lead og booking, men hvilken som helst slug du velger er akseptert. Send en dedupKey (eller en metadata.order_id) slik at en omlasting ikke kan telle den samme bestillingen to ganger.

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

Livssyklus hendelser

Abonner med CompaninWidget.on(name, handler), som returnerer en avmeldingsfunksjon. Håndterere mottar en konvolutt: { event, timestamp, data, context } — nyttelasten er på konvolutt.data. Sene abonnenter mottar umiddelbart den siste konvolutten for den hendelsen, så du går aldri glipp av en ved å feste etter last.

• widget.ready — Iframe fullførte sin bootstrap-håndtrykk, og API-en er aktiv.
• open / close — Chatpanelet ble utvidet eller kollapset. Aliaser: widget.opened, widget.closed.
• message — Besøkende sendte en melding. Alias: message.sent.
• response — Agenten svarte. Alias: message.received.
• conversation.created / conversation.closed — En samtale startet eller ble avsluttet.
• user.updated — identify() ble kalt eller den verifiserte brukeridentiteten ble endret.
• file.uploaded — Besøkende vedla en fil.
• conversion.tracked — trackConversion() registrerte et mål.
• theme.change — Den aktive lys/mørk paletten har endret seg.
• authFailure — Autentisering med backend feilet. Alias: auth.failed.
• error — Widgeten rapporterte en feil.

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

Hver livssyklus-hendelse sendes også på vinduet som en CustomEvent med navnet companin-widget:<event> — for eksempel companin-widget:response. Den samme konvolutten er på event.detail. Bruk disse når den lyttende koden ikke kan holde en referanse til widgeten, som en analysetagg eller en tag-manager-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' });});