Cómo configurar el Widget SoluCX
Introducción
Qué es el Widget SoluCX
El Widget SoluCX es una herramienta de recolección de feedback que permite integrar encuestas de satisfacción directamente en sitios web, aplicaciones y plataformas digitales. A través de él, es posible capturar evaluaciones de clientes en tiempo real utilizando métricas como NPS (Net Promoter Score), CSAT (Customer Satisfaction Score) y CES (Customer Effort Score).
El widget es compatible con dos tipos de encuestas:
- Flex Survey: Formularios flexibles y personalizables
- Survey (Smart Survey): Encuestas inteligentes generadas por el sistema
Visión General: Plataforma vs Código
Las configuraciones del Widget SoluCX se dividen en dos dominios:
Plataforma Administrativa: Configuraciones visuales y de comportamiento gestionadas a través de la interfaz administrativa de SoluCX, sin necesidad de modificar código.
Integración vía Código: Parámetros de inicialización, datos del cliente, opciones de visualización y callbacks definidos directamente en el código de la aplicación.
| Dominio | Ejemplos | Quién configura |
|---|---|---|
| Plataforma | Logo, colores, tipos de input, pantalla de agradecimiento | Equipo de negocio o administradores |
| Código | Tipo de widget, datos del cliente, callbacks, dimensiones, retry | Equipo de desarrollo |
| Ambos | CSS personalizado, cuarentena (código) | Colaboración entre equipos |
Configuraciones de Estilización
Identidad Visual (Plataforma)
Las configuraciones de identidad visual se gestionan exclusivamente a través de la plataforma administrativa de SoluCX:
| Configuración | Descripción | Dónde configurar |
|---|---|---|
| Logo y marca | Carga del logotipo mostrado en el encabezado del widget | Plataforma > Configuraciones > Identidad Visual |
| Colores principales | Color primario y secundario del widget | Plataforma > Configuraciones > Colores |
| Colores dinámicos | Colores que cambian según la puntuación del cliente (ej: rojo para detractores, verde para promotores) | Plataforma > Configuraciones > Colores Dinámicos |
| Temas del Form Builder | Temas visuales predefinidos para formularios flexibles | Plataforma > Form Builder > Temas |
Estas configuraciones se aplican automáticamente a todos los widgets vinculados a la instancia, sin necesidad de modificar el código.
Tipos de Input de Evaluación (Plataforma)
El widget soporta diversos tipos de input de evaluación, todos configurables desde la plataforma. Puede editarlos de la misma forma que edita el Smart Survey o el Flex Survey:
NPS (Net Promoter Score)
Escala de 0 a 10 que mide la probabilidad de recomendación.
| Tipo de Input | Descripción |
|---|---|
| Flecha | Input con flecha deslizante en escala 0-10 |
| Botones | Botones numéricos individuales de 0 a 10 |
| Slider | Barra deslizante continua de 0 a 10 |
| Botones Coloridos | Botones con gradiente de colores (rojo a verde) |
| Gradiente | Escala visual con gradiente de colores |
CSAT (Customer Satisfaction Score)
Mide la satisfacción directa del cliente con un producto o servicio.
| Tipo de Input | Escala | Descripción |
|---|---|---|
| Emoticones | 1-5 | Caras expresivas de insatisfecho a muy satisfecho |
| Estrellas | 1-5 | Evaluación clásica por estrellas |
| Botones 1-5 | 1-5 | Botones numéricos de 1 a 5 |
| Botones 1-10 | 1-10 | Botones numéricos de 1 a 10 |
CES (Customer Effort Score)
Mide el esfuerzo del cliente para resolver un problema o completar una acción.
| Tipo de Input | Descripción |
|---|---|
| Emoticón | Caras expresivas representando nivel de esfuerzo |
| Botones | Botones con escala de esfuerzo |
| Estrellas | Evaluación por estrellas del nivel de facilidad |
La nomenclatura de las escalas (etiquetas de los extremos, título de la pregunta) también es personalizable desde la plataforma para cada tipo de encuesta.
CSS Personalizado
La estilización avanzada se puede hacer de dos formas:
Vía Plataforma (customStyle)
La plataforma permite insertar CSS personalizado que se aplicará internamente al iframe del widget:
- Acceda a Plataforma > Configuraciones > Jornadas
- Inserte reglas CSS que serán inyectadas dentro del widget
- Útil para ajustes finos de fuentes, espaciados y colores internos
Vía Código (options)
Para estilizar el contenedor externo del widget (posición, dimensiones, bordes), utilice los parámetros en el código:
Diferencia importante: El CSS de la plataforma (customStyle) actúa dentro del iframe del widget. Las opciones vía código controlan el contenedor externo. Para personalizaciones completas, puede ser necesario combinar ambos.
Posicionamiento y Dimensiones (Código)
El posicionamiento del widget se controla mediante el parámetro type en la inicialización:
Tipos de Widget
Integrado en el contenido de la página
El widget se integra al flujo natural del layout, sin superponer otros elementos.
- Respeta la posición en el DOM
- Ideal para páginas dedicadas a feedback
- Requiere un elemento
targetpara renderización
Parámetros de Dimensión
100% auto inline. Predeterminado: null Configuraciones de Comportamiento
Pantalla de Agradecimiento (Plataforma)
Después de que el cliente responde la encuesta, se muestra una pantalla de agradecimiento. Las siguientes configuraciones se gestionan desde la plataforma:
La opción customAcknowledgmentHTML permite total personalización de la pantalla de agradecimiento con HTML personalizado, reemplazando los campos successTitle y successMessage.
Redirección y Automatización (Plataforma)
| Configuración | Descripción |
|---|---|
completedUrlRedirection | URL de redirección después de completar la encuesta |
autoSendTimeout | Tiempo (en segundos) para envío automático de la encuesta parcial |
Casos de uso prácticos:
- E-commerce: Redirigir a página de cupón de descuento después de evaluación positiva
- Atención al cliente: Redirigir a página de FAQ después de recolección de feedback
- Auto-envío: Garantizar recolección parcial si el cliente abandona la encuesta
Aceptación y Consentimiento (Plataforma)
Configuraciones relacionadas con LGPD/GDPR y consentimiento del usuario:
| Configuración | Descripción |
|---|---|
| Texto personalizado del consentimiento de contacto | Texto personalizado del término de aceptación |
| Consentimiento preseleccionado por defecto | Si la casilla de consentimiento viene pre-marcada |
| Estrategia de aceptación | Estrategia de aceptación (ej: opt-in, opt-out) |
Consideraciones de LGPD/GDPR: Se recomienda que la casilla de consentimiento no venga pre-marcada (isUserConsentPreChecked: false) para cumplir con las leyes de protección de datos. La estrategia de aceptación debe definirse en conjunto con el equipo legal.
Canales de Contacto (Plataforma)
Configuraciones para habilitar solicitud de canales de contacto basada en la clasificación del encuestado:
| Configuración | Descripción |
|---|---|
| Consentimiento de contacto por canal si detractor | Solicitar contacto si el cliente es detractor (NPS 0-6) |
| Consentimiento de contacto por canal si neutro | Solicitar contacto si el cliente es neutro (NPS 7-8) |
| Consentimiento de contacto por canal si promotor | Solicitar contacto si el cliente es promotor (NPS 9-10) |
Esta funcionalidad permite recolectar información de contacto adicional de forma estratégica, enfocándose en los grupos que más necesitan atención (como detractores para recuperación de experiencia).
Sistema de Cuarentena
El sistema de cuarentena controla la frecuencia con que un mismo cliente es solicitado a responder encuestas, evitando fatiga de encuestas.
Cuarentena en el Código
Configuraciones definidas en los parámetros options de la inicialización del widget:
| Configuración | Tipo | Predeterminado | Descripción |
|---|---|---|---|
retry.attempts | number | 3 | Número de intentos de visualización del widget antes de desistir |
retry.interval | number | 1 | Intervalo (en días) entre intentos de recolección |
waitDelayAfterRating | number | 60 | Tiempo (en días) para que el widget reaparezca después de una evaluación |
Flujo de Cuarentena
El sistema de cuarentena sigue esta lógica:
- Primera visualización: Widget aparece normalmente
- Cliente no responde: Después del intervalo configurado en
retry.interval, el widget intenta nuevamente - Intentos agotados: Después de
retry.attemptsintentos sin respuesta, el widget deja de aparecer - Cliente responde: Después de la evaluación, el widget entra en cuarentena por
waitDelayAfterRatingdías - Fin de cuarentena: Después del período, el widget puede mostrarse nuevamente
Importante sobre Cuarentena: El control de cuarentena del widget se basa en las cookies del navegador del cliente. Esto significa que la cuarentena no está 100% garantizada, ya que el usuario puede borrar las cookies, usar diferentes navegadores, diferentes dispositivos o modo de navegación incógnito/privado. Para escenarios que requieren un control estricto de cuarentena, recomendamos implementar validaciones adicionales en el lado del servidor.
Integración vía Código
Parámetros Obligatorios
La función createSoluCXWidget requiere dos parámetros obligatorios:
apiKey (string)
Clave de API proporcionada por SoluCX que identifica su instancia. Se obtiene en la plataforma administrativa en Configuraciones > API.
type (string)
Define el modo de visualización del widget:
| Valor | Descripción |
|---|---|
inline | Integrado en el contenido de la página |
bottomBar | Barra fija en la parte inferior |
bottomBox | Caja fija en la esquina inferior derecha |
bottomBoxLeft | Caja fija en la esquina inferior izquierda |
modal | Modal centrado en la página |
Para el enlace del widget, los parámetros obligatorios son: name O customer_id.
Datos del Cliente (data)
El objeto data contiene la información del cliente y de la transacción:
Campos de Identificación
transaction_id O name Y (email O phone) Datos Personales
transaction_id O customer_id transaction_id O customer_id Y phone transaction_id O customer_id Y email YYYY-MM-DD Datos Contextuales
transaction_id Parámetros Personalizados
param_ se considera un parámetro extra de transacción para trazabilidad.Opciones de Configuración (options)
Parámetro options
inline, define el ID del elemento DOM donde se insertará el widget. attempts: número de intentos. interval: intervalo en días entre intentos. Sistema de Callbacks
El widget soporta callbacks para eventos del ciclo de vida de la encuesta:
| Callback | Parámetro | Descripción |
|---|---|---|
onOpened | userId: string | Widget fue abierto/mostrado |
onClosed | — | Widget fue cerrado por el usuario |
onCompleted | userId: string | Encuesta completada con éxito |
onPartialCompleted | userId: string | Encuesta completada parcialmente |
onError | message: string | Ocurrió un error en el widget |
onPageChanged | page: string | Usuario navegó a otra página dentro del widget |
onQuestionAnswered | — | Usuario respondió una pregunta. Funciona solo para Flex Survey |
onResize | height: number | Widget fue redimensionado |
Manejo de la Respuesta
La función createSoluCXWidget retorna una Promise:
Tabla Comparativa Completa
Estilización
| Funcionalidad | Plataforma | Código | Descripción |
|---|---|---|---|
| Logo y marca | ✓ | — | Carga y configuración del logotipo |
| Colores principales | ✓ | — | Colores primario y secundario |
| Colores dinámicos | ✓ | — | Colores basados en puntuación del cliente |
| Temas Form Builder | ✓ | — | Temas visuales predefinidos |
| Tipo de input (NPS/CSAT/CES) | ✓ | — | Estilo visual de la escala de evaluación |
| CSS interno (customStyle) | ✓ | — | CSS dentro del iframe del widget |
| Tipo de widget | — | ✓ | inline, bottomBar, bottomBox, modal |
| Dimensiones (width/height) | — | ✓ | Ancho y alto del contenedor |
| Elemento objetivo (target) | — | ✓ | ID del elemento DOM para inline |
Comportamiento
| Funcionalidad | Plataforma | Código | Descripción |
|---|---|---|---|
| Pantalla de agradecimiento | ✓ | — | Mensajes y HTML post-encuesta |
| Redirección | ✓ | — | URL de redirección después de completar |
| Auto-envío (timeout) | ✓ | — | Envío automático después de tiempo |
| Texto de aceptación | ✓ | — | Personalización del término de consentimiento |
| Estrategia de aceptación | ✓ | — | Opt-in vs opt-out |
| Canales de contacto | ✓ | — | Solicitar contacto por clasificación |
| Ocultar créditos | ✓ | — | Remover "Powered by SoluCX" |
| Bloquear scroll | ✓ | — | Bloquear scroll durante visualización |
| Permitir HTML | ✓ | — | HTML en preguntas y descripciones |
| Idioma | ✓ | — | Idioma del widget |
| Callbacks | — | ✓ | Funciones para eventos del widget |
Cuarentena
| Funcionalidad | Plataforma | Código | Descripción |
|---|---|---|---|
| Cuarentena por cookie | ✓ | — | Basada en cookies del navegador |
| Reintentos (retry) | — | ✓ | Número de intentos e intervalo |
| Delay post-evaluación | — | ✓ | Tiempo de espera después de respuesta |
Datos e Integración
| Funcionalidad | Plataforma | Código | Descripción |
|---|---|---|---|
| API Key | — | ✓ | Clave de autenticación |
| Tipo de widget | — | ✓ | Modo de visualización |
| Datos del cliente | — | ✓ | Nombre, email, teléfono, etc |
| Datos de transacción | — | ✓ | ID, valor, tienda, empleado |
| Parámetros custom (param_*) | — | ✓ | Campos extras para trazabilidad |
| Jornada | — | ✓ | Identificador de la jornada del cliente |
Guías Prácticas
Escenarios Comunes
E-commerce Post-Compra
Ideal para recolectar feedback después de la finalización de un pedido:
Atención al Cliente
Para recolectar feedback después de interacción con soporte:
Encuesta en Tienda Física (Tótem/Tablet)
Para recolección de feedback presencial en dispositivos dedicados:
Feedback en Aplicación Web
Para integración en paneles/dashboards web:
Mejores Prácticas
Cuándo usar cada tipo de widget
| Tipo | Mejor para | Evitar cuando |
|---|---|---|
inline | Páginas dedicadas, tótems, iframes | No desea ocupar espacio en el layout |
bottomBar | Recolección pasiva, sitios de contenido | Muchos elementos fijos en el pie |
bottomBox | E-commerce, post-transacción | Sitio con chat en la misma esquina |
bottomBoxLeft | Alternativa al bottomBox | Sitio con menú lateral izquierdo |
modal | Encuestas obligatorias, post-atención | Experiencias que no pueden ser interrumpidas |
Combinando configuraciones de Plataforma y Código
- Defina la identidad visual en la plataforma antes de implementar el código
- Configure la cuarentena en la plataforma para control robusto (IP, CPF, fingerprint)
- Complemente con cuarentena en el código para control adicional vía cookies
- Use callbacks en el código para integrar con analytics y sistemas internos
- Personalice el CSS en la plataforma para ajustes visuales finos
Optimización de Cuarentena
- Ambiente de pruebas: Use
waitDelayAfterRating: 0yretry.attempts: 1para facilitar pruebas - Producción: Recomendado
waitDelayAfterRating: 30-60días para evitar fatiga - Tótems/Tablets: Use
waitDelayAfterRating: 0para permitir evaluaciones consecutivas de diferentes clientes - Combine métodos: Use cuarentena por IP en la plataforma + cookie en el código para cobertura máxima
Solución de Problemas
Widget no aparece
| Problema | Verificación | Solución |
|---|---|---|
| API Key inválida | Consola del navegador | Verifique la clave en la plataforma administrativa |
| Datos obligatorios faltantes | Consola del navegador | Complete name o customer_id |
| Cuarentena activa | Cookies del navegador | Limpie cookies o reduzca waitDelayAfterRating para pruebas |
| Elemento target no existe | Inspector del DOM | Verifique que el ID del target existe antes de llamar al widget |
| Script no cargado | Pestaña Network | Confirme que widget.js se cargó con éxito |
Problemas de CSS y posicionamiento
| Problema | Causa probable | Solución |
|---|---|---|
| Widget cortado | Contenedor con overflow: hidden | Remueva overflow: hidden del contenedor padre |
| Widget detrás de otros elementos | z-index bajo | Ajuste el z-index vía CSS personalizado en la plataforma |
| Widget no responsivo | Ancho fijo | No defina width o use valores porcentuales |
| Scroll bloqueado después de cerrar | lockScroll activo | Desactive lockScroll en la plataforma si es necesario |
Depuración de callbacks
Ejemplos de Código Completos
Ejemplo Básico
Ejemplo Avanzado con Todos los Parámetros
Ejemplo con Callbacks y Analytics
Referencias Técnicas
SDKs Disponibles
| SDK | Tecnología | Paquete |
|---|---|---|
| Widget JavaScript | JavaScript vanilla | widget.js (CDN) |
| SDK React Native | React Native / Expo | @solucx/react-native-solucx-widget |
| SDK Web Component | Vue.js / Web Components | solucx-survey-widget |
| SDK Flutter | Flutter / Dart | solucx_widget |
URL del Script
Soporte
Para dudas o problemas con la integración del widget, contacte al soporte de SoluCX a través de la plataforma administrativa o por el email de soporte.