Saltar al contenido principal
El widget web de woku es una micro-app alojada en el CDN de woku (cdn.woku.app) que captura calificaciones woku (1 a 5) o NPS (0 a 10) directamente desde tu sitio web. Lo embebes con un loader <script> ligero (~2.5 KB gzip) que inyecta un <iframe> cuando se dispara un trigger; no necesitas cargar CSS ni frameworks en tu página.
Todos los estilos del widget viven dentro del <iframe>, en un documento aislado. No hay riesgo de que choquen con los estilos de tu sitio ni de que tu JavaScript interfiera con el del widget.

Cómo funciona

  1. Tu página carga el loader desde cdn.woku.app.
  2. Llamas a WokuWidget.init(config) con tu configuración.
  3. El loader evalúa los triggers (tiempo, scroll, salida, evento, clic) y, al dispararse el primero, inyecta un <iframe> que apunta a la micro-app alojada.
  4. La micro-app renderiza el modo según captureType (woku muestra estrellas 1-5; nps una escala 0-10; ces y csat una escala 1-5 con la pregunta de la herramienta), captura el feedback y lo envía a la API de woku.
  5. El loader emite eventos (open, submit, close, skip) que puedes escuchar con WokuWidget.on(...).

Instalación

1

Obtén tu publishable key

En la aplicación administrativa, entra a Empresa → Integraciones y copia la publishable key (pk_...). Es segura para embeber en el HTML público de tu sitio.
2

Pega el loader en tu sitio

Coloca este snippet antes de </body> en las páginas donde quieras mostrar el widget.
3

Verifica

Abre tu sitio y espera a que se dispare el trigger (en el ejemplo, 5 segundos). El widget aparecerá como modal.
Usa siempre la publishable key (pk_...) en el widget, nunca la clave secreta de la API. El widget es código público: cualquiera puede inspeccionar su configuración. La publishable key solo permite capturar feedback; no expone datos de tu cuenta.

Autenticación: publishable key

El widget se autentica con la publishable key de tu empresa, enviándola en el header x-woku-key de cada captura. A diferencia de la clave secreta (usada por integraciones server-side), la publishable key:
  • Empieza con el prefijo pk_ (ej. pk_live_...).
  • Es segura de embeber en HTML público.
  • Solo tiene permiso de captura (no lee ni administra recursos).
La encuentras en Empresa → Integraciones del panel administrativo (https://admin.woku.app).

Configuración

El objeto que pasas a WokuWidget.init(...) acepta estos campos:

Tipo de captura: woku, NPS, CES y CSAT

Captura una calificación de 1 a 5 estrellas asociada a un wokuId.
En modo woku el usuario ve estrellas 1-5 y, opcionalmente, deja un comentario en texto o audio.

Idioma (i18n)

El widget incluye dos idiomas: español (es, por defecto) e inglés (en). El idioma se resuelve en este orden:
  1. El campo lang de la configuración.
  2. El idioma del navegador (navigator.language).
  3. Fallback a es.

Triggers

Cada trigger define cuándo aparece el widget y cómo se presenta (behavior). Puedes combinar varios; se dispara el primero que cumpla.
Modos de presentación (behavior): modal (ventana centrada con overlay), banner (barra fija), side-tab (pestaña lateral) y fullscreen (pantalla completa).

Tema

Personaliza la apariencia del widget. Los valores se aplican como CSS custom properties dentro del iframe (excepto zIndex, que controla el overlay en tu página):

API programática

El loader expone window.WokuWidget:
open se emite cada vez que el panel se abre, por un clic o solo (modal, fullscreen o startOpen), y de nuevo cuando la persona vuelve a calificar. Después de submit, la pantalla de agradecimiento queda visible 10 segundos antes de cerrarse. A una persona identificada por email o dispatchToken no se le ofrece volver a calificar, para no duplicar su respuesta.

Requisitos de CSP

Si tu sitio usa Content-Security-Policy, debes permitir el origen del CDN tanto para el script del loader como para el iframe de la micro-app:
El loader se carga como <script src="..."> externo y no usa eval ni scripts inline, así que no necesitas configurar un nonce ni unsafe-inline.
Para las notas de voz, el iframe delega el micrófono (allow="microphone"). Si tu sitio envía una cabecera Permissions-Policy, debe delegarlo también al origen del widget, por ejemplo microphone=(self "https://cdn.woku.app"). Sin eso el texto funciona igual y el audio no está disponible.

Resolución de problemas

  • Confirma que algún trigger se cumple (por ejemplo, espera los segundos de un trigger time).
  • Revisa la consola del navegador: errores de CSP indican que falta permitir cdn.woku.app en script-src o frame-src.
  • Verifica que companyId y publishableKey sean correctos.
La publishableKey es inválida o no corresponde al companyId. Vuelve a copiarla desde Empresa → Integraciones.
Falta wokuId, que es requerido cuando captureType === 'woku'.
El widget ajusta su alto automáticamente vía postMessage. Si tu sitio aplica overflow: hidden o un transform al <body>, puede interferir con el overlay. Usa behavior: 'fullscreen' como alternativa.

Procedencia de la captura

Desde la versión 0.3.0 (npm y CDN), WokuWidget.init acepta collectionKind y flowId. Las capturas nuevas Woku/NPS declaran standalone por defecto. Un Flow externo debe enviar collectionKind: 'flow' y su ID real. El loader, postMessage, la configuración y los cuerpos texto/audio conservan el contexto, incluida la creación de NPS y sus comentarios posteriores. Cambiar la procedencia inicia una evaluación nueva para evitar adjuntar comentarios a otra respuesta. Una respuesta de Flow no activa seguimiento, aunque el Flow tenga un solo paso o quede incompleto; puede generar su ticket normal. Un instrumento individual de un Viaje conserva standalone si no pertenece a un Flow. El widget sigue capturando Woku/NPS y no muestra conversaciones de soporte.
Última modificación el 2 de noviembre de 2026