Widget SDK

Ikhtisar

Setelah skrip widget dimuat, ia mendaftarkan sebuah global di window.CompaninWidget. Ini memberikan halaman Anda API kecil yang bebas ketergantungan untuk membuka dan menutup widget, mengirim pesan, mengidentifikasi pengguna saat ini, dan berlangganan ke peristiwa siklus hidup — tanpa mengaitkan kode Anda dengan internal widget.

Skrip ini dimuat secara asinkron, jadi global muncul sesaat setelah halaman Anda. Lindungi panggilan pertama Anda (window.CompaninWidget?.open()), atau berlangganan ke acara widget.ready. Ketika Anda menyematkan lebih dari satu widget di halaman, setiap instance juga terdaftar dengan data-instance-id-nya di bawah window.CompaninWidgets — gunakan CompaninWidgets.get(‘id’) untuk menargetkan yang spesifik; window.CompaninWidget menunjuk ke instance yang baru saja dibuat.

JavaScript API

Panggil ini di window.CompaninWidget setelah widget dimuat. Metode yang tidak berpengaruh sebelum iframe siap akan gagal dengan tenang dan mencatat ke konsol daripada melempar, jadi panggilan yang tidak tepat waktu tidak pernah merusak halaman Anda.

• open() / close() / toggle() — Perluas, lipat, atau balik panel obrolan.
• show() / hide() — Tampilkan atau sembunyikan seluruh kontainer widget, termasuk peluncur.
• isOpen() / isVisible() / isReady() — Baca panel saat ini, kontainer, dan status bootstrap.
• sendMessage(text) — Kirim pesan sebagai pengunjung dan dapatkan balasan.
• prefill(text) — Teks ini adalah contoh untuk diterjemahkan ke dalam bahasa Indonesia. Pastikan untuk mempertahankan semua placeholder dan markup seperti yang ditentukan. Jika ada pertanyaan, silakan ajukan.
• identify(user) — Lampirkan identitas pengguna ke sesi — { userId, email, name, metadata, token }. Lihat di bawah.
• setContext(data) — Dorong konteks tingkat halaman; widget menggabungkannya ke dalam page_context permintaan berikutnya.
• setTheme(theme) — Ganti palet saat runtime — 'light', 'dark', atau 'system'. Mengganti tema dasbor dan data-theme.
• trackConversion(goal, value, opts) — Catat tujuan yang tercapai setelah obrolan, misalnya trackConversion('checkout', 79.00, { currency: 'EUR' }).
• beforeSend(fn) / afterReceive(fn) — Periksa, tulis ulang, atau batalkan pesan saat keluar atau masuk. Kembalikan null untuk membatalkan.
• on(event, handler) — Langganan ke acara siklus hidup; mengembalikan fungsi batal langganan. off(event, handler) juga berfungsi.
• update(config) — Terapkan konfigurasi widget sebagian secara langsung tanpa memuat ulang halaman.
• reset() — Bersihkan percakapan saat ini dan mulai sesi baru.
• enableDebug() / disableDebug() — Nyalakan atau matikan logging konsol yang verbose di halaman langsung.
• grantConsent() / revokeConsent() — Beri tahu widget apakah ia boleh menggunakan penyimpanan browser. Diperlukan untuk penyebaran yang memerlukan persetujuan.
• getVersion() / destroy() — Baca versi pemuat, atau bongkar widget dan hapus dari halaman.

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

Mengidentifikasi pengguna yang masuk

Biarkan widget mengenali pengguna yang telah masuk sehingga percakapan dipersonalisasi dan dipulihkan di seluruh perangkat mereka. Server Anda menandatangani token yang memiliki masa hidup pendek yang diserahkan widget kepada Companin; Companin memverifikasinya dan menghubungkan sesi tersebut ke pengguna itu.

1. Dapatkan rahasia penandatanganan Anda dari dasbor dan salin ke dalam lingkungan server Anda. Jangan pernah mengeksposnya dalam kode browser.

2. Tandatangani token di server Anda — HS256 JWT yang memiliki masa hidup pendek yang membawa id pengguna (sub), email, dan nama:

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. Serahkan token ke widget. Di halaman yang dirender di server, tambahkan ke tag skrip sebagai data-user-token; dalam aplikasi satu halaman, panggil identify() setelah pengguna masuk:

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

Token yang buruk atau kedaluwarsa diabaikan — widget tetap anonim, jadi aman untuk selalu mencoba identifikasi.

• Tandatangani token di server Anda — jangan pernah mengirimkan rahasia penandatanganan ke browser.
• Jaga agar token memiliki masa hidup pendek (beberapa menit); token hanya diperlukan saat widget dimuat atau saat Anda memanggil identify().
• Nilai sub yang sama di berbagai perangkat adalah yang mengembalikan percakapan pengguna dan mempersonalisasi balasan.
• Memutar rahasia di dasbor membatalkan token yang ditandatangani dengan yang lama — perbarui server Anda pada saat yang sama.
• identify() juga menerima userId, email, nama, dan metadata secara langsung ketika Anda hanya ingin memberi label pada percakapan dan tidak memverifikasi identitas.
• Untuk widget dokumentasi, panggil window.CompaninDocsWidget.identify(...) alih-alih window.CompaninWidget.

Menyadap pesan

beforeSend(fn) menjalankan fungsi Anda pada setiap pesan pengunjung yang keluar sebelum mencapai API; afterReceive(fn) berjalan pada setiap balasan agen sebelum dirender. Kembalikan string yang dimodifikasi untuk mengubahnya, atau kembalikan null untuk membatalkan. Keduanya menerima Promise, jadi Anda dapat memanggil layanan Anda sendiri terlebih dahulu, dan beberapa interceptor berjalan dalam urutan pendaftaran.

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

Melacak konversi

Panggil trackConversion() ketika pengunjung mencapai tujuan sehingga dasbor dapat mengaitkannya dengan percakapan yang membantu. Lewati slug tujuan dan, ketika ada, nilai moneter dan mata uang. Slug umum adalah add_to_cart, checkout, signup, lead, dan booking, tetapi slug apa pun yang Anda pilih diterima. Lewati dedupKey (atau metadata.order_id) sehingga pemuatan ulang tidak dapat menghitung dua kali pesanan yang sama.

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

Peristiwa siklus hidup

Langganan dengan CompaninWidget.on(name, handler), yang mengembalikan fungsi batal langganan. Penangan menerima sebuah amplop: { event, timestamp, data, context } — muatan ada di envelope.data. Pelanggan yang terlambat segera menerima amplop terakhir untuk acara itu, jadi Anda tidak akan pernah melewatkannya dengan melampirkan setelah pemuatan.

• widget.ready — Iframe telah menyelesaikan jabat tangan bootstrap dan API sudah aktif.
• open / close — Panel obrolan telah diperluas atau diperkecil. Alias: widget.opened, widget.closed.
• message — Pengunjung mengirim pesan. Alias: message.sent.
• response — Agen membalas. Alias: message.received.
• conversation.created / conversation.closed — Sebuah percakapan dimulai atau diakhiri.
• user.updated — identify() dipanggil atau identitas pengguna yang terverifikasi berubah.
• file.uploaded — Pengunjung melampirkan sebuah file.
• conversion.tracked — trackConversion() mencatat sebuah tujuan.
• theme.change — Palet cahaya/gelap aktif telah berubah.
• authFailure — Autentikasi dengan backend gagal. Alias: auth.failed.
• error — Widget melaporkan kesalahan.

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

Acara DOM

Setiap peristiwa siklus hidup juga dikirimkan di jendela sebagai CustomEvent bernama companin-widget:<event> — misalnya companin-widget:response. Amplop yang sama ada di event.detail. Gunakan ini ketika kode pendengar tidak dapat menyimpan referensi ke widget, seperti tag analitik atau cuplikan tag-manager.

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