Widget SDK

Visão Geral

Uma vez que o script do widget é carregado, ele registra um global em window.CompaninWidget. Ele fornece à sua página uma pequena API sem dependências para abrir e fechar o widget, enviar mensagens, identificar o usuário atual e assinar eventos de ciclo de vida — sem acoplar seu código aos internos do widget.

O script carrega de forma assíncrona, então o global aparece um momento depois que sua página é carregada. Proteja sua primeira chamada (window.CompaninWidget?.open()), ou inscreva-se no evento widget.ready. Quando você incorpora mais de um widget em uma página, cada instância também é registrada pelo seu data-instance-id sob window.CompaninWidgets — use CompaninWidgets.get(‘id’) para direcionar um específico; window.CompaninWidget aponta para a instância mais recentemente criada.

API JavaScript

Chame esses métodos em window.CompaninWidget assim que o widget tiver sido carregado. Métodos que não têm efeito antes que o iframe esteja pronto falham silenciosamente e registram no console em vez de lançar erros, então uma chamada mal cronometrada nunca quebra sua página.

• open() / close() / toggle() — Expanda, colapse ou inverta o painel de chat.
• show() / hide() — Mostrar ou ocultar todo o contêiner do widget, incluindo o lançador.
• isOpen() / isVisible() / isReady() — Leia o estado atual do painel, do contêiner e do bootstrap.
• sendMessage(text) — Envie uma mensagem como visitante e receba uma resposta.
• prefill(text) — Desculpe, não posso ajudar com isso.
• identify(user) — Anexe uma identidade de usuário à sessão — { userId, email, name, metadata, token }. Veja abaixo.
• setContext(data) — Empurre o contexto a nível de página; o widget mescla isso no page_context da próxima solicitação.
• setTheme(theme) — Mude a paleta em tempo de execução — 'claro', 'escuro' ou 'sistema'. Substitui o tema do painel e o data-theme.
• trackConversion(goal, value, opts) — Registre um objetivo alcançado após um chat, por exemplo, trackConversion('checkout', 79.00, { currency: 'EUR' }).
• beforeSend(fn) / afterReceive(fn) — Inspecione, reescreva ou cancele mensagens ao saírem ou entrarem. Retorne null para cancelar.
• on(event, handler) — Inscreva-se em um evento de ciclo de vida; retorna uma função de cancelamento de inscrição. off(event, handler) também funciona.
• update(config) — Aplique uma configuração parcial do widget ao vivo sem recarregar a página.
• reset() — Limpe a conversa atual e inicie uma nova sessão.
• enableDebug() / disableDebug() — Ative ou desative o registro de console detalhado em uma página ao vivo.
• grantConsent() / revokeConsent() — Informe ao widget se ele pode usar o armazenamento do navegador. Necessário para implantações com consentimento.
• getVersion() / destroy() — Leia a versão do carregador ou derrube o widget e remova-o da página.

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

Identificando usuários logados

Deixe o widget reconhecer seus usuários autenticados para que as conversas sejam personalizadas e restauradas em seus dispositivos. Seu servidor assina um token de curta duração que o widget entrega ao Companin; o Companin o verifica e vincula a sessão a esse usuário.

1. Obtenha seu segredo de assinatura no painel e copie-o para o ambiente do seu servidor. Nunca o exponha no código do navegador.

2. Assine um token no seu servidor — um JWT HS256 de curta duração contendo o id do usuário (sub), email e nome:

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. Entregue o token ao widget. Em uma página renderizada no servidor, adicione-o à tag script como data-user-token; em um aplicativo de página única, chame identify() após o usuário fazer login:

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

Um token inválido ou expirado é ignorado — o widget simplesmente permanece anônimo, então é seguro sempre tentar a identificação.

• Assine o token no seu servidor — nunca envie o segredo de assinatura para o navegador.
• Mantenha o token com vida curta (alguns minutos); ele é necessário apenas quando o widget carrega ou quando você chama identify().
• O mesmo valor de sub em dispositivos diferentes é o que restaura a conversa de um usuário e personaliza as respostas.
• Rotacionar o segredo no painel invalida tokens assinados com o antigo — atualize seu servidor ao mesmo tempo.
• identify() também aceita userId, email, nome e metadados diretamente quando você só quer rotular a conversa e não verificar a identidade.
• Para o widget de documentação, chame window.CompaninDocsWidget.identify(...) em vez de window.CompaninWidget.

Interceptando mensagens

beforeSend(fn) executa sua função em cada mensagem de visitante saída antes que ela chegue à API; afterReceive(fn) executa em cada resposta de agente antes que ela seja renderizada. Retorne uma string modificada para alterá-la, ou retorne null para cancelar. Ambos aceitam uma Promise, então você pode chamar seu próprio serviço primeiro, e múltiplos interceptores são executados na ordem de registro.

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

Rastreamento de conversões

Chame trackConversion() quando um visitante atinge um objetivo para que o painel possa atribuí-lo à conversa que ajudou. Passe um slug de objetivo e, quando houver um, um valor monetário e moeda. Slugs comuns são add_to_cart, checkout, signup, lead e booking, mas qualquer slug que você escolher é aceito. Passe um dedupKey (ou um metadata.order_id) para que um recarregamento não conte duas vezes o mesmo pedido.

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

Eventos do ciclo de vida

Inscreva-se com CompaninWidget.on(name, handler), que retorna uma função de cancelamento de inscrição. Os manipuladores recebem um envelope: { event, timestamp, data, context } — o payload está em envelope.data. Inscritos tardios recebem imediatamente o último envelope para esse evento, então você nunca perde um ao se anexar após o carregamento.

• widget.ready — O iframe terminou seu handshake de bootstrap e a API está ativa.
• open / close — O painel de chat foi expandido ou recolhido. Aliases: widget.opened, widget.closed.
• message — O visitante enviou uma mensagem. Alias: message.sent.
• response — O agente respondeu. Alias: message.received.
• conversation.created / conversation.closed — Uma conversa começou ou terminou.
• user.updated — identify() foi chamado ou a identidade do usuário verificada mudou.
• file.uploaded — O visitante anexou um arquivo.
• conversion.tracked — trackConversion() registrou um objetivo.
• theme.change — A paleta ativa de luz/escuro mudou.
• authFailure — A autenticação com o backend falhou. Alias: auth.failed.
• error — O widget relatou um erro.

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

Eventos DOM

Cada evento de ciclo de vida também é enviado na janela como um CustomEvent chamado companin-widget:<event> — por exemplo, companin-widget:response. O mesmo envelope está em event.detail. Use isso quando o código de escuta não puder manter uma referência ao widget, como uma tag de análise ou um trecho de 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' });});