Управляйте виджетом со своей страницы: открывайте и закрывайте его, отправляйте сообщения, идентифицируйте вошедших пользователей, отслеживайте конверсии и реагируйте на события жизненного цикла.
Как только скрипт виджета загружается, он регистрирует глобальную переменную в window.CompaninWidget. Это предоставляет вашей странице небольшой, независимый от зависимостей API для открытия и закрытия виджета, отправки сообщений, идентификации текущего пользователя и подписки на события жизненного цикла — без связывания вашего кода с внутренностями виджета.
Скрипт загружается асинхронно, поэтому глобальный объект появляется через мгновение после загрузки вашей страницы. Защитите свой первый вызов (window.CompaninWidget?.open()), или подпишитесь на событие widget.ready. Когда вы встраиваете более одного виджета на страницу, каждый экземпляр также регистрируется по своему data-instance-id в window.CompaninWidgets — используйте CompaninWidgets.get(‘id’), чтобы нацелиться на конкретный; window.CompaninWidget указывает на последний созданный экземпляр.
Вызовите их на window.CompaninWidget, как только виджет загрузится. Методы, которые не имеют эффекта до готовности iframe, тихо завершаются и записываются в консоль, а не выбрасывают ошибку, так что неправильно выполненный вызов никогда не сломает вашу страницу.
open() / close() / toggle() — Развернуть, свернуть или перевернуть панель чата.show() / hide() — Показать или скрыть весь контейнер виджета, включая запускатель.isOpen() / isVisible() / isReady() — Прочитайте текущее состояние панели, контейнера и загрузки.sendMessage(text) — Отправьте сообщение как посетитель и получите ответ.prefill(text) — Пожалуйста, предоставьте текст для перевода.identify(user) — Прикрепите идентификатор пользователя к сессии — { userId, email, name, metadata, token }. См. ниже.setContext(data) — Отправьте контекст на уровне страницы; виджет объединяет его с контекстом страницы следующего запроса.setTheme(theme) — Переключите палитру во время выполнения — 'светлая', 'темная' или 'системная'. Переопределяет тему панели управления и data-theme.trackConversion(goal, value, opts) — Запишите достигнутую цель после чата, например, trackConversion('checkout', 79.00, { currency: 'EUR' }).beforeSend(fn) / afterReceive(fn) — Проверяйте, переписывайте или отменяйте сообщения на их пути наружу или внутрь. Верните null, чтобы отменить.on(event, handler) — Подпишитесь на событие жизненного цикла; возвращает функцию отписки. off(event, handler) также работает.update(config) — Примените частичную конфигурацию виджета без перезагрузки страницы.reset() — Очистите текущий разговор и начните новую сессию.enableDebug() / disableDebug() — Включите или отключите подробное логирование консоли на живой странице.grantConsent() / revokeConsent() — Сообщите виджету, может ли он использовать хранилище браузера. Обязательно для развертываний с ограничением согласия.getVersion() / destroy() — Прочитайте версию загрузчика или удалите виджет и уберите его со страницы.<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>Позвольте виджету распознавать ваших вошедших пользователей, чтобы разговоры были персонализированы и восстанавливались на их устройствах. Ваш сервер подписывает токен с коротким сроком действия, который виджет передает Companin; Companin проверяет его и связывает сессию с этим пользователем.
1. Получите свой секретный ключ для подписи с панели управления и скопируйте его в окружение вашего сервера. Никогда не раскрывайте его в коде браузера.
Подпишите токен на вашем сервере — краткоживущий HS256 JWT, содержащий идентификатор пользователя (sub), электронную почту и имя:
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. Передайте токен виджету. На странице, отрендеренной на сервере, добавьте его в тег script как data-user-token; в одностраничном приложении вызовите identify() после того, как пользователь войдет в систему:
<!-- 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>Плохой или истекший токен игнорируется — виджет просто остается анонимным, поэтому всегда безопасно пытаться идентифицировать.
beforeSend(fn) запускает вашу функцию на каждом исходящем сообщении посетителя перед тем, как оно достигнет API; afterReceive(fn) запускается на каждом ответе агента перед его отображением. Верните изменённую строку, чтобы изменить её, или верните null, чтобы отменить. Оба принимают Promise, так что вы можете сначала вызвать свой собственный сервис, и несколько перехватчиков выполняются в порядке регистрации.
// 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');});Вызовите trackConversion(), когда посетитель достигает цели, чтобы панель инструментов могла отнести это к разговору, который помог. Передайте слаг цели и, когда он есть, денежную сумму и валюту. Общие слаги: add_to_cart, checkout, signup, lead и booking, но любой выбранный вами слаг принимается. Передайте dedupKey (или metadata.order_id), чтобы перезагрузка не могла дважды учесть один и тот же заказ.
// 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), который возвращает функцию отписки. Обработчики получают конверт: { event, timestamp, data, context } — полезная нагрузка находится в envelope.data. Поздние подписчики немедленно получают последний конверт для этого события, так что вы никогда не пропустите его, присоединившись после загрузки.
widget.ready — iframe завершил свою начальную рукопожатие, и API активен.open / close — Чат-панель была развернута или свернута. Псевдонимы: widget.opened, widget.closed.message — Посетитель отправил сообщение. Псевдоним: message.sent.response — Агент ответил. Псевдоним: message.received.conversation.created / conversation.closed — Разговор начался или закончился.user.updated — identify() был вызван или подтвержденная личность пользователя изменилась.file.uploaded — Посетитель прикрепил файл.conversion.tracked — trackConversion() зафиксировала цель.theme.change — Активная палитра светлого/темного режима изменилась.authFailure — Аутентификация с сервером не удалась. Псевдоним: auth.failed.error — Виджет сообщил об ошибке.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();Каждое событие жизненного цикла также отправляется в window как CustomEvent с именем companin-widget:<event> — например, companin-widget:response. Тот же самый envelope находится в event.detail. Используйте их, когда код прослушивания не может удерживать ссылку на виджет, например, в теге аналитики или фрагменте менеджера тегов.
// 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' });});