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
- Tu página carga el loader desde
cdn.woku.app. - Llamas a
WokuWidget.init(config)con tu configuración. - 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. - La micro-app renderiza el modo según
captureType(wokumuestra estrellas 1-5;npsuna escala 0-10;cesycsatuna escala 1-5 con la pregunta de la herramienta), captura el feedback y lo envía a la API de woku. - El loader emite eventos (
open,submit,close,skip) que puedes escuchar conWokuWidget.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.
Autenticación: publishable key
El widget se autentica con la publishable key de tu empresa, enviándola en el headerx-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).
Configuración
El objeto que pasas aWokuWidget.init(...) acepta estos campos:
Tipo de captura: woku, NPS, CES y CSAT
- woku (1-5 estrellas)
- NPS (0-10)
- CES y CSAT (1-5)
Captura una calificación de 1 a 5 estrellas asociada a un En modo
wokuId.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:
- El campo
langde la configuración. - El idioma del navegador (
navigator.language). - Fallback a
es.
- Español
- Inglés
- Autodetección
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 (exceptozIndex, que controla el
overlay en tu página):
API programática
El loader exponewindow.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.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
El widget no aparece
El widget no aparece
- 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.appenscript-srcoframe-src. - Verifica que
companyIdypublishableKeysean correctos.
Error 401 al enviar feedback
Error 401 al enviar feedback
La
publishableKey es inválida o no corresponde al companyId.
Vuelve a copiarla desde Empresa → Integraciones.En modo woku no carga nada
En modo woku no carga nada
Falta
wokuId, que es requerido cuando captureType === 'woku'.El iframe se ve cortado en móvil
El iframe se ve cortado en móvil
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ón0.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.