Driv widgeten från din sida och håll varje konversation motståndskraftig — automatisk återanslutning, meddelandeförsök, offline-detektering, tidsgränser och vänlig felhantering.
När widget-skriptet laddas registrerar Companin en värdbro vid window.CompaninWidgetHost. Det ger din sida ett litet, beroendefritt API för att öppna och stänga widgeten, skicka meddelanden, läsa tillstånd och prenumerera på livscykelhändelser — utan att koppla din kod till widgetens interna funktioner.
Bron lägger också till ett pålitlighetslager ovanpå widgeten: meddelanden köas medan de är offline, försöks automatiskt när anslutningen återkommer, tidsgränsas om inget svar kommer och widgeten återansluter automatiskt efter tillfälliga fel. Varje tillståndsändring visas som en DOM-händelse så att du kan reagera i din egen UI.
Anropa dessa metoder på window.CompaninWidgetHost efter att widgeten har laddats. De är säkra no-ops när widgeten inte är redo än, så du behöver aldrig skydda varje anrop.
open() / close() / toggle() — Visa, dölja eller vända widgetpanelen.sendText(text) — Skicka ett vanligt textmeddelande som besökaren.sendPayload(payload) — Skicka ett strukturerat meddelande eller kommandobjekt.sendSafe(payload) — Skicka genom pålitlighetslagret — köas när offline och passerar genom eventuella avlyssnare.sendWithTimeout(payload, ms) — Skicka och avge en tidsgränshändelse om inget svar kommer inom ms (standard 10000).intercept(fn) — Registrera en funktion som kan skriva om eller avbryta utgående meddelanden; returnerar en avprenumerationsfunktion.getState() — Läs det aktuella värdtillståndet: öppet status, senaste skickade och mottagna meddelande, online-flagg och kommandohistorik.getIsOnline() — Om värden för närvarande anser att anslutningen är online.drainRetryQueue() — Manuellt tömma eventuella meddelanden som köats medan offline.cleanup() — Avprenumerera varje lyssnare — anropa innan du tar bort 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>Låt widgeten känna igen dina inloggade användare så att konversationerna 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. Få din signeringshemlighet. I instrumentpanelen, öppna Installera → Inloggade användare → Generera hemlighet, kopiera den sedan 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. Överför token till widgeten. På en server-renderad sida, lägg till den i skript-taggen som data-user-token; i en en-sides-app, anropa identify() efter att användaren loggar in:
<!-- 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ålig eller utgången token ignoreras — widgeten förblir helt enkelt anonym, så det är säkert att alltid försöka identifiera.
Använd sendSafe istället för sendText när leverans är viktigt. Värden övervakar webbläsarens online- och offline-händelser; medan offline, läggs meddelanden till en återförsökskö och en companin:widget:offline-händelse utlöses. Så snart anslutningen återkommer, töms kön automatiskt i ordning och companin:widget:online utlöses.
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.');});Kapsla in ett meddelande i sendWithTimeout för att skydda mot ett svar som aldrig kommer. Om inget svar mottas inom tidsgränsen (10 sekunder som standard), utlöses en companin:widget:timeout-händelse så att du kan visa en vänlig återförsöksuppmaning istället för att låta användaren vänta.
window.CompaninWidgetHost.sendWithTimeout('Are you there?', 8000);window.addEventListener('companin:widget:timeout', function () { showRetryPrompt('That took longer than expected. Try again?');});När widgeten rapporterar ett fel försöker värden återansluta upp till tre gånger med en ökande back-off (1,5 s, 3 s, sedan 4,5 s), och avger companin:widget:reconnecting vid varje försök. Ett framgångsrikt svar återställer räknaren; om alla försök misslyckas, utlöses companin:widget:reconnectFailed så att du kan falla tillbaka smidigt.
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.');});Registrera en avlyssnare med intercept(fn) för att inspektera, skriva om eller avbryta varje utgående meddelande. Returnera en modifierad payload för att ändra den, returnera false för att avbryta sändningen, eller returnera ingenting för att låta den gå igenom oförändrad. intercept returnerar en avprenumerationsfunktion.
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();Värden återutsänder varje widgetlivscykeländring som en DOM CustomEvent på fönstret, så att du kan reagera utan att hålla en referens till widgeten. Den relevanta datan finns på event.detail.
companin:widget:open / close — Widgetpanelen öppnades eller stängdes.companin:widget:message / response — Besökaren skickade ett meddelande, eller agenten svarade.companin:widget:authFailure — Autentisering med backend misslyckades.companin:widget:error — Widgeten rapporterade ett fel.companin:widget:offline / online — Webbläsaren förlorade eller återfick sin anslutning.companin:widget:queued / retryDrained — Ett meddelande köades medan offline, eller kön tömdes.companin:widget:reconnecting / reconnectFailed — Ett automatiskt återanslutningsförsök startade, eller alla försök uttömdes.companin:widget:timeout — Ett meddelande fick inget svar inom sin tidsgräns.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);});Decoupled kod kan styra widgeten genom att avge en companin:widget:command-händelse istället för att anropa API:et direkt. Skicka en sträng för att leverera ett meddelande, eller ett detaljobjekt som { action: 'open' } eller { text: 'Hej' }. Detta är praktiskt för analys-taggar, GTM eller andra skript som inte bör importera 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' }}));Ställ in window.__COMPANIN_WIDGET_WEBHOOK_URL till en insamlingsändpunkt och värden vidarebefordrar öppna, stänga, meddelande och svarshändelser till den som JSON via navigator.sendBeacon (faller tillbaka till en keepalive-fetch). Detta är ett lättviktigt, klientbaserat komplement till serverbaserade webhooks — användbart för förstapartanalys.
// Point the host at your collector before the widget loads.window.__COMPANIN_WIDGET_WEBHOOK_URL = 'https://example.com/collect/widget';