Satify Survey Widget
Pon una encuesta en tu sitio en 2 minutos
El widget de Satify Survey muestra tus encuestas dentro de tu sitio o app: como ventana, panel lateral, tarjeta flotante o incrustadas. Pegas una línea de código y el usuario responde sin salir de donde está.
Formatos
Distribúyela donde quieras
Captura la atención total del usuario en momentos clave, después de una compra, al completar un registro o antes de cancelar. Ocupa el centro de la pantalla sin distracciones.
Para desarrolladores
Una línea de código, nada más.
Comparte este bloque con tu equipo. Funciona con cualquier stack: React, Vue, Angular, WordPress o HTML puro. El widget se carga de forma asíncrona, pesa menos de 14 KB gzip y no afecta el rendimiento de tu sitio.
- 1Instala el SDK con npm, pnpm, yarn o CDN
- 2Elige el formato: modal, drawer, popover o embed
- 3Personaliza disparadores, callbacks e idioma
npm install @satify/widget-sdk
Cómo funciona
De cero a feedback en 3 pasos
Arma tu encuesta
Configura la encuesta en el panel de Satify Survey: tipo de pregunta, diseño y lógica.
Pega el código
Satify Survey te da un snippet listo. Lo pegas en tu HTML y el widget aparece.
Ajusta desde el panel
Cambias posición, colores y disparadores desde Satify Survey. Se actualiza en tu sitio sin tocar el código de nuevo.
Referencia técnica
Todas las opciones, con sus valores por defecto
Cada función del SDK (createModal, createDrawer, createPopover, createEmbed) recibe el ID de tu encuesta y un objeto de configuración opcional. Todo tiene un valor por defecto razonable: configura solo lo que quieras cambiar.
Opciones de configuración
| Propiedad | Tipo | Por defecto | Qué hace |
|---|---|---|---|
| activator | "button" | "tab" | "button" | Cómo se abre: botón flotante o pestaña lateral. El formato embed lo ignora. |
| trigger | objeto | type: "manual" · frequency: "always" | Cuándo aparece: manual, auto (delay: 5000 ms), scroll (scrollPercentage: 50), exit-intent, event (eventName) o url-match (urlRules). frequency: once, daily, weekly o always. |
| button | objeto | texto según idioma · 💬 · "bottom-right" · show: true | Botón flotante. Con show: false queda en modo silencioso y lo abres tú con open(). |
| tab | objeto | "right" · texto según idioma · 💬 | Pestaña lateral. Se usa solo con activator: "tab". |
| appearance | objeto | "#6366f1" · "light" · 12 · 999999 | primaryColor, theme (light/dark), borderRadius y zIndex. Opcionales: fontFamily y backgroundGradient. |
| modal | objeto | "medium" · cierra con overlay y Esc · botón de cierre | Ajustes del formato modal: size (small/medium/large), closeOnOverlay, closeOnEscape, showCloseButton. |
| drawer | objeto | "right" · 400 px · overlay: true | Ajustes del panel lateral: side (left/right), width y overlay. |
| popover | objeto | "bottom-right" · 380 × 520 px | Ajustes de la tarjeta flotante: position (4 esquinas), width y height. |
| embed | objeto | container: "#satify-survey" | Selector CSS o elemento HTML donde se incrusta la encuesta. |
| user | objeto | Identidad del usuario: { id, email?, name?, ...datos extra }. Se adjunta a las respuestas. | |
| locale | "es" | "en" | detecta <html lang> · respaldo "es" | Idioma de la interfaz del widget. Las preguntas de la encuesta no dependen de esta opción. |
| testMode | boolean | false | Ignora los límites de frecuencia mientras desarrollas. |
| autoCloseDelay | number (ms) | 0 | Cierra la encuesta solo, N milisegundos después de enviarla. 0 = cierre manual. |
| apiUrl | string | "https://satify-survey.app/api" | API de Satify Survey (self-hosting). Debe ser HTTPS; http solo se permite en localhost. |
| appUrl | string | "https://satify-survey.app" | Origen que sirve el iframe de la encuesta. Misma regla HTTPS. |
| nonce | string | Nonce de CSP aplicado al <style> que el widget inyecta en su Shadow DOM. | |
| callbacks | objeto | onReady, onBeforeShow (devuelve false para cancelar), onShow, onClose, onStarted, onQuestionChanged, onSubmit, onError. |
Métodos de la instancia
Cada función devuelve un objeto WidgetInstance con estos métodos:
open()
Abre la encuesta. Si el widget aún está cargando, la llamada se encola y se ejecuta al terminar.
close()
Cierra la encuesta.
destroy()
Elimina el widget del DOM y limpia todos los listeners.
identify(user)
Asocia la identidad del usuario a las respuestas.
resetIdentity()
Limpia la identidad guardada (por ejemplo, al cerrar sesión).
on(evento, fn)
Se suscribe a un evento del widget.
off(evento, fn)
Cancela la suscripción.
Eventos
Puedes escucharlos con widget.on() o con los callbacks equivalentes de la configuración; ambos estilos funcionan a la vez.
| Evento | Datos | Qué hace |
|---|---|---|
| ready | El widget terminó de cargar. | |
| beforeShow | Antes de abrir. Devuelve false para cancelar la apertura. | |
| show | La encuesta se abrió. | |
| close | La encuesta se cerró. | |
| started | El usuario respondió la primera pregunta. | |
| questionChanged | { questionId, index, total } | El usuario pasó a otra pregunta. |
| submit | respuestas[] | La encuesta se envió completa. |
| error | Error | Algo falló. En errores fatales el widget se retira solo, sin romper tu página. |
Atributos HTML (auto-init)
Para el modo sin JavaScript: agrega estos atributos data-* a cualquier elemento y el SDK crea el widget al cargar la página.
| Atributo | Qué hace |
|---|---|
| data-satify-modal="id" | Crea el widget. También -drawer, -popover y -embed. |
| data-satify-trigger | auto:5000 · scroll:75 · exit-intent · event:nombre |
| data-satify-activator | Pestaña lateral ("tab") o botón flotante ("button"). |
| data-satify-position | Esquina del botón: bottom-right, bottom-left, top-right, top-left. |
| data-satify-theme | light o dark. |
| data-satify-color | Color principal en hex. |
| data-satify-locale | es o en. Sin este atributo, se detecta de <html lang>. |
| data-satify-nonce | Nonce de CSP para el <style> inyectado. |
Notas de comportamiento
- La configuración se combina en este orden: valores por defecto → panel de Satify Survey → código. Si defines lo mismo en ambos lados, gana lo del código.
- Si la encuesta restringe dominios, el widget valida el dominio actual y emite error en vez de mostrarse donde no corresponde.
- Con triggers auto, scroll y exit-intent el contenido se precarga en segundo plano, para que la encuesta abra al instante.
- La frecuencia (once, daily, weekly) se guarda en localStorage; no se usan cookies. testMode la ignora.
- El progreso se autoguarda como borrador y expira después de 1 hora.
- Si algo falla, todos los métodos pasan a no hacer nada: el widget nunca rompe tu aplicación.
Preguntas frecuentes
Lo que necesitas saber del widget
Tu primera encuesta en menos de 2 minutos
Crea una cuenta gratis, elige el tipo de métrica y publica. Sin tarjeta, sin fricción.
