Sayfanızdan widget'ı yönetin ve her konuşmayı dayanıklı tutun — otomatik yeniden bağlanma, mesaj yeniden denemesi, çevrimdışı tespit, zaman aşımı ve dostça hata yönetimi.
Widget script'i yüklendikten sonra, Companin, window.CompaninWidgetHost'ta bir ana köprü kaydeder. Bu, sayfanıza widget'ı açıp kapatmak, mesaj göndermek, durumu okumak ve yaşam döngüsü olaylarına abone olmak için küçük, bağımlılık içermeyen bir API sağlar — kodunuzu widget'ın iç yapısına bağlamadan.
Köprü, widget'ın üstünde bir güvenilirlik katmanı ekler: mesajlar çevrimdışı iken sıraya alınır, bağlantı geri döndüğünde otomatik olarak yeniden denemeler yapılır, yanıt gelmezse zaman aşımına uğrar ve widget geçici hatalardan sonra otomatik olarak yeniden bağlanır. Her durum değişikliği, kendi UI'nizde tepki verebilmeniz için bir DOM olayı olarak yüzeye çıkar.
Widget yüklendikten sonra window.CompaninWidgetHost üzerinde bu yöntemleri çağırın. Widget henüz hazır değilse, güvenli no-op'lardır, bu nedenle her çağrıyı korumanıza gerek yoktur.
open() / close() / toggle() — Widget panelini göster, gizle veya çevir.sendText(text) — Ziyaretçi olarak düz metin mesajı gönderin.sendPayload(payload) — Yapılandırılmış bir mesaj veya komut nesnesi gönderin.sendSafe(payload) — Güvenilirlik katmanından gönderin — çevrimdışı olduğunda sıraya alınır ve herhangi bir kesici üzerinden geçer.sendWithTimeout(payload, ms) — Yanıt gelmezse ms içinde (varsayılan 10000) zaman aşımı olayı gönderin ve yayılmasını sağlayın.intercept(fn) — Giden mesajları yeniden yazabilen veya iptal edebilen bir işlev kaydedin; bir abonelik iptal işlevi döndürür.getState() — Mevcut ana durumunu okuyun: açık durumu, en son gönderilen ve alınan mesaj, çevrimiçi bayrağı ve komut geçmişi.getIsOnline() — Ana, bağlantıyı şu anda çevrimiçi olarak kabul ediyor mu?drainRetryQueue() — Çevrimdışı iken sıraya alınan tüm mesajları manuel olarak boşaltın.cleanup() — Her dinleyiciyi iptal edin — widget'ı kaldırmadan önce çağırın.<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>Widget'ın giriş yapan kullanıcılarınızı tanımasına izin verin, böylece konuşmalar kişiselleştirilir ve cihazları arasında geri yüklenir. Sunucunuz, widget'ın Companin'e teslim ettiği kısa ömürlü bir token imzalar; Companin bunu doğrular ve oturumu o kullanıcıya bağlar.
1. İmzalama sırrınızı alın. Kontrol panelinde, Kurulum → Giriş yapan kullanıcılar → Sırayı oluştur'a gidin, ardından bunu sunucunuzun ortamına kopyalayın. Bunu tarayıcı kodunda asla açığa çıkarmayın.
2. Sunucunuzda bir token imzalayın — kullanıcının kimliğini (sub), e-posta ve adını taşıyan kısa ömürlü bir HS256 JWT:
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. Token'ı widget'a teslim edin. Sunucu tarafından oluşturulan bir sayfada, bunu script etiketine data-user-token olarak ekleyin; tek sayfa uygulamasında, kullanıcı giriş yaptıktan sonra identify() çağırın:
<!-- 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>Kötü veya süresi dolmuş bir token görmezden gelinir — widget basitçe anonim kalır, bu nedenle tanımlama girişiminde bulunmak her zaman güvenlidir.
Gönderim önemli olduğunda sendSafe yerine sendText kullanın. Ana, tarayıcının çevrimiçi ve çevrimdışı olaylarını izler; çevrimdışı iken, mesajlar yeniden deneme kuyruğuna eklenir ve companin:widget:offline olayı tetiklenir. Bağlantı geri döner dönmez, kuyruk otomatik olarak sırayla boşaltılır ve companin:widget:online olayı tetiklenir.
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.');});Yanıtın asla gelmemesi durumunda bir gönderimi korumak için sendWithTimeout içinde sarın. Zaman aşımında (varsayılan olarak 10 saniye) yanıt alınmazsa, companin:widget:timeout olayı tetiklenir, böylece kullanıcıyı bekletmek yerine dostça bir yeniden deneme istemi gösterebilirsiniz.
window.CompaninWidgetHost.sendWithTimeout('Are you there?', 8000);window.addEventListener('companin:widget:timeout', function () { showRetryPrompt('That took longer than expected. Try again?');});Widget bir hata bildirdiğinde, ana, artan bir bekleme süresi ile üç kez yeniden bağlanmaya çalışır (1.5s, 3s, ardından 4.5s), her denemede companin:widget:reconnecting olayı yayar. Başarılı bir yanıt, sayacı sıfırlar; tüm denemeler başarısız olursa, companin:widget:reconnectFailed olayı tetiklenir, böylece nazikçe geri dönebilirsiniz.
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.');});Her giden mesajı denetlemek, yeniden yazmak veya iptal etmek için intercept(fn) ile bir kesici kaydedin. Değiştirilmiş bir yük döndürmek, onu değiştirmek için, gönderimi iptal etmek için false döndürmek veya değişmeden geçmesine izin vermek için hiçbir şey döndürmek. Kesici, bir abonelik iptal işlevi döndürür.
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();Ana, her widget yaşam döngüsü değişikliğini window üzerinde bir DOM CustomEvent olarak yeniden yayar, böylece widget'a bir referans tutmadan tepki verebilirsiniz. İlgili veriler event.detail'de bulunur.
companin:widget:open / close — Widget paneli açıldı veya kapatıldı.companin:widget:message / response — Ziyaretçi bir mesaj gönderdi veya temsilci yanıt verdi.companin:widget:authFailure — Arka uç ile kimlik doğrulama başarısız oldu.companin:widget:error — Widget bir hata bildirdi.companin:widget:offline / online — Tarayıcı bağlantısını kaybetti veya geri kazandı.companin:widget:queued / retryDrained — Bir mesaj çevrimdışı iken sıraya alındı veya kuyruk boşaltıldı.companin:widget:reconnecting / reconnectFailed — Otomatik yeniden bağlanma girişimi başladı veya tüm girişimler tüketildi.companin:widget:timeout — Bir mesaj, zaman aşımı içinde yanıt almadı.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);});Bağlantısız kod, API'yi doğrudan çağırmak yerine bir companin:widget:command olayı göndererek widget'ı yönlendirebilir. Bir mesaj iletmek için bir dize gönderin veya { action: 'open' } veya { text: 'Hello' } gibi bir ayrıntı nesnesi gönderin. Bu, widget'ı içe aktarması gerekmeyen analiz etiketleri, GTM veya diğer betikler için kullanışlıdır.
// 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' }}));window.__COMPANIN_WIDGET_WEBHOOK_URL'yi bir toplayıcı uç noktasına ayarlayın ve ana, açık, kapalı, mesaj ve yanıt olaylarını JSON olarak navigator.sendBeacon aracılığıyla iletir (bir keepalive fetch ile geri döner). Bu, sunucu tarafı webhook'larına hafif, istemci tarafı bir tamamlayıcıdır — birinci taraf analizleri için kullanışlıdır.
// Point the host at your collector before the widget loads.window.__COMPANIN_WIDGET_WEBHOOK_URL = 'https://example.com/collect/widget';