Widget'i sayfanızdan yönetin: açın ve kapatın, mesaj gönderin, oturum açmış kullanıcıları tanıyın, dönüşümleri takip edin ve yaşam döngüsü olaylarına tepki verin.
Widget script yüklendikten sonra, window.CompaninWidget'ta bir global kaydeder. Bu, sayfanıza widget'ı açıp kapatmak, mesaj göndermek, mevcut kullanıcıyı tanımlamak 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.
Script asenkron olarak yüklenir, bu nedenle global, sayfanızdan bir an sonra görünür. İlk çağrınızı koruyun (window.CompaninWidget?.open()), veya widget.ready olayına abone olun. Bir sayfada birden fazla widget gömülü olduğunda, her bir örnek de window.CompaninWidgets altında kendi data-instance-id'si ile kaydedilir — belirli birini hedeflemek için CompaninWidgets.get(‘id’) kullanın; window.CompaninWidget en son oluşturulan örneğe işaret eder.
Widget yüklendikten sonra bunları window.CompaninWidget üzerinde çağırın. iframe hazır olmadan önce etkisi olmayan yöntemler sessizce başarısız olur ve konsola kaydeder, bu nedenle zamanlaması yanlış bir çağrı sayfanızı asla bozmaz.
open() / close() / toggle() — Sohbet panelini genişlet, daralt veya çevir.show() / hide() — Tüm widget konteynerini, başlatıcı dahil, göster veya gizle.isOpen() / isVisible() / isReady() — Mevcut paneli, konteyneri ve bootstrap durumunu okuyun.sendMessage(text) — Ziyaretçi olarak bir mesaj gönderin ve bir yanıt alın.prefill(text) — Metin çevrildi.identify(user) — Oturuma bir kullanıcı kimliği ekleyin — { userId, email, name, metadata, token }. Aşağıya bakın.setContext(data) — Sayfa düzeyindeki bağlamı it. Widget, bunu bir sonraki isteğin page_context'ine birleştirir.setTheme(theme) — Çalışma zamanında paleti değiştir — 'açık', 'koyu' veya 'sistem'. Gösterge panosunun temasını ve veri temasını geçersiz kılar.trackConversion(goal, value, opts) — Bir sohbet sonrası ulaşılmış bir hedef kaydedin, örneğin trackConversion('checkout', 79.00, { currency: 'EUR' }).beforeSend(fn) / afterReceive(fn) — Giden veya gelen mesajları inceleyin, yeniden yazın veya iptal edin. İptal etmek için null döndürün.on(event, handler) — Bir yaşam döngüsü olayına abone olun; bir abonelikten çıkma işlevi döner. off(event, handler) da çalışır.update(config) — Sayfayı yeniden yüklemeden kısmi bir widget yapılandırmasını canlı olarak uygula.reset() — Mevcut sohbeti temizleyin ve yeni bir oturum başlatın.enableDebug() / disableDebug() — Canlı bir sayfada ayrıntılı konsol günlüklemeyi açın veya kapatın.grantConsent() / revokeConsent() — Widget'e tarayıcı depolamasını kullanıp kullanamayacağını bildirin. Onay gerektiren dağıtımlar için gereklidir.getVersion() / destroy() — Yükleyici sürümünü okuyun veya widget'ı kaldırın ve sayfadan çıkarın.<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>Widget'iniz, oturum açmış kullanıcılarınızı tanıyarak sohbetlerin kişiselleştirilmesini ve cihazları arasında geri yüklenmesini sağlar. Sunucunuz, widget'ın Companin'e verdiği kısa ömürlü bir token imzalar; Companin bunu doğrular ve oturumu o kullanıcıya bağlar.
1. İmza sırrınızı kontrol panelinden alın ve sunucunuzun ortamına kopyalayın. Bunu asla tarayıcı kodunda açığa çıkarmayın.
2. Sunucunuzda bir token imzalayın — kullanıcının kimliğini (sub), e-posta adresini ve adını taşıyan kısa ömürlü 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'i widget'a verin. 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ısını yapın:
<!-- 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>Geçersiz veya süresi dolmuş bir jeton yok sayılır — widget basitçe anonim kalır, bu nedenle her zaman kimlik tespiti yapmayı denemek güvenlidir.
beforeSend(fn) her giden ziyaretçi mesajı API'ye ulaşmadan önce fonksiyonunuzu çalıştırır; afterReceive(fn) her ajan yanıtında render edilmeden önce çalışır. Değiştirmek için değiştirilmiş bir dize döndürün veya iptal etmek için null döndürün. Her ikisi de bir Promise kabul eder, böylece önce kendi servisinizi çağırabilirsiniz ve birden fazla interceptors kayıt sırasına göre çalışır.
// 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');});Ziyaretçi bir hedefe ulaştığında trackConversion() çağrısını yapın, böylece gösterge paneli bunu yardımcı olan konuşmaya atfedebilir. Bir hedef slug'ı ve, varsa, bir para değeri ve para birimi geçirin. Yaygın slug'lar add_to_cart, checkout, signup, lead ve booking'dir, ancak seçtiğiniz herhangi bir slug kabul edilir. Aynı siparişi iki kez saymamak için bir dedupKey (veya bir metadata.order_id) geçirin.
// 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');CompaninWidget.on(name, handler) ile abone olun, bu bir abonelikten çıkma fonksiyonu döner. İşleyiciler bir zarf alır: { event, timestamp, data, context } — yük, zarf.data üzerinde bulunur. Geç abone olanlar, o etkinlik için son zarfı hemen alır, böylece yüklemeden sonra bağlanarak hiçbiri kaçırılmaz.
widget.ready — Iframe, bootstrap el sıkışmasını tamamladı ve API canlı.open / close — Sohbet paneli genişletildi veya daraltıldı. Takma adlar: widget.opened, widget.closed.message — Ziyaretçi bir mesaj gönderdi. Takma ad: message.sent.response — Ajan cevap verdi. Takma ad: message.received.conversation.created / conversation.closed — Bir konuşma başladı veya sona erdi.user.updated — identify() çağrıldı veya doğrulanmış kullanıcı kimliği değişti.file.uploaded — Ziyaretçi bir dosya ekledi.conversion.tracked — trackConversion() bir hedef kaydetti.theme.change — Aktif ışık/karanlık paleti değişti.authFailure — Arka uç ile kimlik doğrulama başarısız oldu. Takma ad: auth.failed.error — Widget bir hata bildirdi.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();Her yaşam döngüsü olayı, window üzerinde companin-widget:<event> adında bir CustomEvent olarak da iletilir — örneğin companin-widget:response. Aynı zarf event.detail üzerindedir. Widget'a bir referans tutamayan dinleme kodları için, bir analiz etiketi veya bir etiket yöneticisi parçası gibi, bunları kullanın.
// 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' });});