SDK & Pålitelighet

Oversikt

Når widget-skriptet lastes, registrerer Companin en vertbro på vinduet.CompaninWidgetHost. Den gir siden din et lite, avhengighetsfritt API for å åpne og lukke widgeten, sende meldinger, lese tilstand, og abonnere på livssyklus-hendelser — uten å knytte koden din til widgetens indre.

Broen legger også til et pålitelighetslag på toppen av widgeten: meldinger settes i kø mens de er offline, prøves automatisk når forbindelsen gjenopprettes, tidsavbrytes hvis ingen svar kommer, og widgeten gjenoppretter seg automatisk etter midlertidige feil. Hver tilstandsendring vises som en DOM-hendelse slik at du kan reagere i din egen UI.

Vert API

Kall disse metodene på vinduet.CompaninWidgetHost etter at widgeten har lastet. De er trygge no-ops når widgeten ikke er klar ennå, så du trenger aldri å beskytte hvert kall.

• open() / close() / toggle() — Vis, skjul eller snu widgetpanelet.
• sendText(text) — Send en ren tekstmelding som besøkende.
• sendPayload(payload) — Send en strukturert melding eller kommandoobjekt.
• sendSafe(payload) — Send gjennom pålitelighetslaget — satt i kø når offline og sendt gjennom eventuelle interseptorer.
• sendWithTimeout(payload, ms) — Send og utløse en tidsavbruddshendelse hvis ingen svar kommer innen ms (standard 10000).
• intercept(fn) — Registrer en funksjon som kan omskrive eller kansellere utgående meldinger; returnerer en avmeldingsfunksjon.
• getState() — Les den nåværende vertens tilstand: åpen status, sist sendte og mottatte melding, online-flagg og kommandohistorikk.
• getIsOnline() — Om verten for øyeblikket anser forbindelsen som online.
• drainRetryQueue() — Manuelt tøm eventuelle meldinger som er satt i kø mens de er offline.
• cleanup() — Avmeld alle lyttere — kall før du fjerner widgeten.

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

Identifisere påloggede brukere

La widgeten gjenkjenne dine påloggede brukere slik at samtaler blir personlige og gjenopprettet på tvers av enhetene deres. Serveren din signerer en kortvarig token som widgeten gir til Companin; Companin verifiserer det og knytter sesjonen til den brukeren.

1. Få din signeringshemmelighet. I dashbordet, åpne Installer → Påloggede brukere → Generer hemmelighet, og kopier den inn i serverens miljø. Eksponer den aldri i nettleserkode.

2. Signer en 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 token til widgeten. På en server-rendered side, legg den til skript-taggen som data-user-token; i en enkelt-side-app, kall identify() etter at brukeren logger inn:

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

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

• Signer token på serveren din — aldri send signeringshemmeligheten til nettleseren.
• Hold token kortvarig (noen minutter); den 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 svarene.
• Rotering av hemmeligheten i dashbordet ugyldiggjør tokens signert med den gamle — oppdater serveren din samtidig.
• For dokumentasjonswidgeten, kall vinduet.CompaninDocsWidget.identify(...) i stedet for vinduet.CompaninWidget.

Pålitelig meldingshåndtering & offline-detektering

Bruk sendSafe i stedet for sendText når levering betyr noe. Vert overvåker nettleserens online- og offline-hendelser; mens offline, legges meldinger til en prøvekø og en companin:widget:offline-hendelse utløses. Så snart forbindelsen gjenopprettes, tømmes køen automatisk i rekkefølge og companin:widget:online-hendelsen utløses.

• Meldinger blir aldri stille droppet — de venter i køen til forbindelsen er tilbake.
• Køen tømmes automatisk; kall drainRetryQueue() for å tømme den manuelt.
• Lytt etter companin:widget:queued og companin:widget:retryDrained for å reflektere status i din UI.

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

Tidsavbruddsbehandling

Pakk en send i sendWithTimeout for å beskytte mot et svar som aldri kommer. Hvis ingen svar mottas innen tidsavbruddet (10 sekunder som standard), utløses en companin:widget:timeout-hendelse slik at du kan vise en vennlig prøv igjen-prompt i stedet for å la brukeren vente.

window.CompaninWidgetHost.sendWithTimeout('Are you there?', 8000);window.addEventListener('companin:widget:timeout', function () {  showRetryPrompt('That took longer than expected. Try again?');});

Automatisk gjenoppretting

Når widgeten rapporterer en feil, prøver verten å gjenopprette seg opptil tre ganger med en økende tilbakeholdelse (1,5s, 3s, deretter 4,5s), og sender companin:widget:reconnecting ved hvert forsøk. Et vellykket svar tilbakestiller telleren; hvis alle forsøk mislykkes, utløses companin:widget:reconnectFailed slik at du kan falle tilbake på en elegant måte.

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

Meldingsintersepting

Registrer en interseptor med intercept(fn) for å inspisere, omskrive, eller kansellere hver utgående melding. Returner en modifisert nyttelast for å endre den, returner false for å kansellere sendingen, eller returner ingenting for å la den gå uendret. intercept returnerer en avmeldingsfunksjon.

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

Livssyklus-hendelser

Verten gjenutløser hver widget livssyklusendring som en DOM CustomEvent på vinduet, slik at du kan reagere uten å holde en referanse til widgeten. De relevante dataene er på event.detail.

• companin:widget:open / close — Widgetpanelet ble åpnet eller lukket.
• companin:widget:message / response — Besøkende sendte en melding, eller agenten svarte.
• companin:widget:authFailure — Autentisering med backend mislyktes.
• companin:widget:error — Widgeten rapporterte en feil.
• companin:widget:offline / online — Nettleseren mistet eller gjenopprettet forbindelsen.
• companin:widget:queued / retryDrained — En melding ble satt i kø mens den var offline, eller køen ble tømt.
• companin:widget:reconnecting / reconnectFailed — Et automatisk gjenopprettingsforsøk startet, eller alle forsøk ble uttømt.
• companin:widget:timeout — En melding mottok ikke svar innen sitt tidsavbrudd.

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

Kommando-bro

Dekoblet kode kan drive widgeten ved å sende en companin:widget:command-hendelse i stedet for å kalle API-en direkte. Send en streng for å levere en melding, eller et detaljobjekt som { action: 'open' } eller { text: 'Hello' }. Dette er nyttig for analyse-tags, GTM, eller andre skript som ikke bør importere widgeten.

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

Webhook videresending

Sett vinduet.__COMPANIN_WIDGET_WEBHOOK_URL til en samler-endepunkt, og verten videresender åpne, lukke, melding og svarhendelser til det som JSON via navigator.sendBeacon (som faller tilbake til en keepalive fetch). Dette er et lettvekts, klientside-komplement til server-side webhooks — nyttig for førstepartsanalyse.

// Point the host at your collector before the widget loads.window.__COMPANIN_WIDGET_WEBHOOK_URL = 'https://example.com/collect/widget';