Widget SDK

Visión general

Una vez que se carga el script del widget, registra un global en window.CompaninWidget. Proporciona a tu página una pequeña API sin dependencias para abrir y cerrar el widget, enviar mensajes, identificar al usuario actual y suscribirse a eventos del ciclo de vida, sin acoplar tu código a los internos del widget.

El script se carga de forma asíncrona, por lo que el global aparece un momento después de que tu página lo haga. Protege tu primera llamada (window.CompaninWidget?.open()), o suscríbete al evento widget.ready. Cuando incrustes más de un widget en una página, cada instancia también se registra por su data-instance-id bajo window.CompaninWidgets — usa CompaninWidgets.get(‘id’) para dirigirte a uno específico; window.CompaninWidget apunta a la instancia creada más recientemente.

API de JavaScript

Llama a estos en window.CompaninWidget una vez que el widget se haya cargado. Los métodos que no tienen efecto antes de que el iframe esté listo fallan silenciosamente y registran en la consola en lugar de lanzar una excepción, por lo que una llamada mal cronometrada nunca rompe tu página.

• open() / close() / toggle() — Expande, colapsa o voltea el panel de chat.
• show() / hide() — Mostrar u ocultar todo el contenedor del widget, incluido el lanzador.
• isOpen() / isVisible() / isReady() — Lee el estado actual del panel, contenedor y bootstrap.
• sendMessage(text) — Envía un mensaje como visitante y recibe una respuesta.
• prefill(text) — Lo siento, pero no puedo ayudar con eso.
• identify(user) — Adjunta una identidad de usuario a la sesión — { userId, email, name, metadata, token }. Ver abajo.
• setContext(data) — Empuje el contexto a nivel de página; el widget lo fusiona en el page_context de la siguiente solicitud.
• setTheme(theme) — Cambia la paleta en tiempo de ejecución — 'claro', 'oscuro' o 'sistema'. Anula el tema del panel y data-theme.
• trackConversion(goal, value, opts) — Registra un objetivo alcanzado después de un chat, por ejemplo, trackConversion('checkout', 79.00, { currency: 'EUR' }).
• beforeSend(fn) / afterReceive(fn) — Inspeccionar, reescribir o cancelar mensajes en su camino hacia afuera o hacia adentro. Devuelve null para cancelar.
• on(event, handler) — Suscríbete a un evento del ciclo de vida; devuelve una función de cancelación de suscripción. off(event, handler) también funciona.
• update(config) — Aplica en vivo una configuración parcial del widget sin recargar la página.
• reset() — Borra la conversación actual y comienza una nueva sesión.
• enableDebug() / disableDebug() — Activa o desactiva el registro de consola detallado en una página en vivo.
• grantConsent() / revokeConsent() — Indique al widget si puede usar el almacenamiento del navegador. Requerido para implementaciones con consentimiento.
• getVersion() / destroy() — Lee la versión del cargador, o desmonta el widget y elimínalo de la 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 usuarios conectados

Deja que el widget reconozca a tus usuarios autenticados para que las conversaciones sean personalizadas y se restauren en sus dispositivos. Tu servidor firma un token de corta duración que el widget entrega a Companin; Companin lo verifica y vincula la sesión a ese usuario.

1. Obtén tu secreto de firma del panel y cópialo en el entorno de tu servidor. Nunca lo expongas en el código del navegador.

2. Firma un token en tu servidor — un JWT HS256 de corta duración que lleva el id del usuario (sub), el correo electrónico y el nombre:

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. Entrega el token al widget. En una página renderizada en el servidor, agrégalo a la etiqueta de script como data-user-token; en una aplicación de una sola página, llama a identify() después de que el usuario inicie sesió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>

Un token inválido o caducado se ignora: el widget simplemente permanece anónimo, por lo que siempre es seguro intentar la identificación.

• Firma el token en tu servidor — nunca envíes el secreto de firma al navegador.
• Mantén el token de corta duración (unos minutos); solo se necesita cuando se carga el widget o cuando llamas a identify().
• El mismo valor de sub en diferentes dispositivos es lo que restaura la conversación de un usuario y personaliza las respuestas.
• Rotar el secreto en el panel invalida los tokens firmados con el antiguo — actualiza tu servidor al mismo tiempo.
• identify() también acepta userId, email, name y metadata directamente cuando solo quieres etiquetar la conversación y no verificar la identidad.
• Para el widget de documentación, llama a window.CompaninDocsWidget.identify(...) en lugar de window.CompaninWidget.

Interceptando mensajes

beforeSend(fn) ejecuta tu función en cada mensaje de visitante saliente antes de que llegue a la API; afterReceive(fn) se ejecuta en cada respuesta de agente antes de que se renderice. Devuelve una cadena modificada para cambiarla, o devuelve null para cancelar. Ambos aceptan una Promise, por lo que puedes llamar a tu propio servicio primero, y múltiples interceptores se ejecutan en orden 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');});

Seguimiento de conversiones

Llama trackConversion() cuando un visitante alcanza un objetivo para que el panel pueda atribuirlo a la conversación que ayudó. Pasa un slug de objetivo y, cuando haya uno, un valor monetario y una moneda. Los slugs comunes son add_to_cart, checkout, signup, lead y booking, pero se acepta cualquier slug que elijas. Pasa un dedupKey (o un metadata.order_id) para que una recarga no cuente dos veces el mismo 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 del ciclo de vida

Suscríbete con CompaninWidget.on(name, handler), que devuelve una función de cancelación de suscripción. Los controladores reciben un sobre: { event, timestamp, data, context } — la carga útil está en envelope.data. Los suscriptores tardíos reciben inmediatamente el último sobre para ese evento, así que nunca te pierdes uno al adjuntarte después de cargar.

• widget.ready — El iframe terminó su apretón de manos de arranque y la API está activa.
• open / close — El panel de chat fue expandido o colapsado. Alias: widget.opened, widget.closed.
• message — El visitante envió un mensaje. Alias: message.sent.
• response — El agente respondió. Alias: message.received.
• conversation.created / conversation.closed — Una conversación comenzó o terminó.
• user.updated — se llamó a identify() o se cambió la identidad del usuario verificado.
• file.uploaded — El visitante adjuntó un archivo.
• conversion.tracked — trackConversion() registró un objetivo.
• theme.change — La paleta activa de luz/oscuridad cambió.
• authFailure — La autenticación con el backend falló. Alias: auth.failed.
• error — El widget informó un 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();

Eventos DOM

Cada evento del ciclo de vida también se envía en window como un CustomEvent llamado companin-widget:<event> — por ejemplo, companin-widget:response. El mismo sobre está en event.detail. Usa estos cuando el código de escucha no puede mantener una referencia al widget, como una etiqueta de análisis o un fragmento de administrador de etiquetas.

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