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:

DominioEjemplosQuién configura
PlataformaLogo, colores, tipos de input, pantalla de agradecimientoEquipo de negocio o administradores
CódigoTipo de widget, datos del cliente, callbacks, dimensiones, retryEquipo de desarrollo
AmbosCSS 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ónDescripciónDónde configurar
Logo y marcaCarga del logotipo mostrado en el encabezado del widgetPlataforma > Configuraciones > Identidad Visual
Colores principalesColor primario y secundario del widgetPlataforma > Configuraciones > Colores
Colores dinámicosColores que cambian según la puntuación del cliente (ej: rojo para detractores, verde para promotores)Plataforma > Configuraciones > Colores Dinámicos
Temas del Form BuilderTemas visuales predefinidos para formularios flexiblesPlataforma > Form Builder > Temas

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 InputDescripción
FlechaInput con flecha deslizante en escala 0-10
BotonesBotones numéricos individuales de 0 a 10
SliderBarra deslizante continua de 0 a 10
Botones ColoridosBotones con gradiente de colores (rojo a verde)
GradienteEscala visual con gradiente de colores

CSAT (Customer Satisfaction Score)

Mide la satisfacción directa del cliente con un producto o servicio.

Tipo de InputEscalaDescripción
Emoticones1-5Caras expresivas de insatisfecho a muy satisfecho
Estrellas1-5Evaluación clásica por estrellas
Botones 1-51-5Botones numéricos de 1 a 5
Botones 1-101-10Botones 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 InputDescripción
EmoticónCaras expresivas representando nivel de esfuerzo
BotonesBotones con escala de esfuerzo
EstrellasEvaluación por estrellas del nivel de facilidad

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:

const options = {
    width: 600,
    height: 400
};

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.

createSoluCXWidget(apiKey, "inline", data, {
    target: "mi-contenedor",
    width: 600,
    height: 400
});
<div id="mi-contenedor"></div>
  • Respeta la posición en el DOM
  • Ideal para páginas dedicadas a feedback
  • Requiere un elemento target para renderización

Parámetros de Dimensión

widthnumber
Ancho del widget en píxeles. Predeterminado: 100%
heightnumber
Altura del widget en píxeles. Predeterminado: auto
targetstring
ID del elemento DOM para widgets 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:

showThanksScreenboolean
Mostrar u ocultar la pantalla de agradecimiento
successTitlestring
Título de la pantalla de éxito
successMessagestring
Mensaje principal de agradecimiento
thanksMessagestring
Mensaje complementario de agradecimiento
dateTimeMessagestring
Mensaje con fecha/hora de la evaluación
showInHouseAdsboolean
Mostrar anuncios internos en la pantalla de agradecimiento
customAcknowledgmentHTMLstring
HTML personalizado para la pantalla de agradecimiento

Redirección y Automatización (Plataforma)

ConfiguraciónDescripción
completedUrlRedirectionURL de redirección después de completar la encuesta
autoSendTimeoutTiempo (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ónDescripción
Texto personalizado del consentimiento de contactoTexto personalizado del término de aceptación
Consentimiento preseleccionado por defectoSi la casilla de consentimiento viene pre-marcada
Estrategia de aceptaciónEstrategia de aceptación (ej: opt-in, opt-out)

Canales de Contacto (Plataforma)

Configuraciones para habilitar solicitud de canales de contacto basada en la clasificación del encuestado:

ConfiguraciónDescripción
Consentimiento de contacto por canal si detractorSolicitar contacto si el cliente es detractor (NPS 0-6)
Consentimiento de contacto por canal si neutroSolicitar contacto si el cliente es neutro (NPS 7-8)
Consentimiento de contacto por canal si promotorSolicitar contacto si el cliente es promotor (NPS 9-10)

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ónTipoPredeterminadoDescripción
retry.attemptsnumber3Número de intentos de visualización del widget antes de desistir
retry.intervalnumber1Intervalo (en días) entre intentos de recolección
waitDelayAfterRatingnumber60Tiempo (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:

  1. Primera visualización: Widget aparece normalmente
  2. Cliente no responde: Después del intervalo configurado en retry.interval, el widget intenta nuevamente
  3. Intentos agotados: Después de retry.attempts intentos sin respuesta, el widget deja de aparecer
  4. Cliente responde: Después de la evaluación, el widget entra en cuarentena por waitDelayAfterRating días
  5. Fin de cuarentena: Después del período, el widget puede mostrarse nuevamente
const options = {
    retry: {
        attempts: 5,
        interval: 2
    },
    waitDelayAfterRating: 30
};

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.

const apiKey = "SU_API_KEY";

type (string)

Define el modo de visualización del widget:

ValorDescripción
inlineIntegrado en el contenido de la página
bottomBarBarra fija en la parte inferior
bottomBoxCaja fija en la esquina inferior derecha
bottomBoxLeftCaja fija en la esquina inferior izquierda
modalModal centrado en la página
createSoluCXWidget(apiKey, type, data, options);

Datos del Cliente (data)

El objeto data contiene la información del cliente y de la transacción:

Campos de Identificación

transaction_idstring
ID externo de la transacción proporcionado por el cliente.
customer_idstring
ID del cliente. Obligatorio si no proporciona transaction_id O name Y (email O phone)
form_idstring
ID del formulario. Obligatorio solo para Flex Survey

Datos Personales

namestring
Nombre del cliente. Obligatorio si no proporciona transaction_id O customer_id
emailstring
Email del cliente. Obligatorio si no proporciona transaction_id O customer_id Y phone
phonestring
Teléfono del cliente. Obligatorio si no proporciona transaction_id O customer_id Y email
phone2string
Teléfono secundario del cliente.
documentstring
Documento del cliente (CPF, CNPJ, etc).
birth_datestring
Fecha de nacimiento del cliente. Formato: YYYY-MM-DD

Datos Contextuales

store_idstring
ID de la tienda/unidad. Obligatorio si no proporciona transaction_id
store_namestring
Nombre de la tienda/unidad.
employee_idstring
ID del empleado/colaborador.
employee_namestring
Nombre del empleado/colaborador.
amountnumber
Valor de la transacción.
scorenumber
Puntuación/score del cliente.
journeystring
Jornada del cliente. Obligatorio si más de una jornada está registrada para la instancia. Si no se proporciona, se usará la jornada predeterminada. Se mostrará un error si se proporciona incorrectamente.

Parámetros Personalizados

Cualquier campo con prefijo param_ se considera un parámetro extra de transacción para trazabilidad.
const data = {
    name: "Juan García",
    email: "[email protected]",
    store_id: "tienda-001",
    param_canal: "sitio-web",
    param_campaña: "black-friday",
    param_region: "sureste"
};

Opciones de Configuración (options)

Parámetro options

Opciones adicionales para configuración del widget.
targetstring|null
Para widgets inline, define el ID del elemento DOM donde se insertará el widget.
widthnumber
Ancho del widget en píxeles. Predeterminado: 100%.
heightnumber
Altura del widget en píxeles. Predeterminado: automática.
retryobject
Configuración de reintentos. attempts: número de intentos. interval: intervalo en días entre intentos.
waitDelayAfterRatingnumber
Tiempo (en días) para que el widget reaparezca después de la respuesta. Predeterminado: 60.
callbacksobject
Objeto con funciones de callback para eventos del widget.
interface WidgetOptions {
    target?: string | null;
    width?: number;
    height?: number;
    retry?: {
        attempts?: number;
        interval?: number;
    };
    waitDelayAfterRating?: number;
    callbacks?: WidgetCallbacks;
}

Sistema de Callbacks

El widget soporta callbacks para eventos del ciclo de vida de la encuesta:

CallbackParámetroDescripción
onOpeneduserId: stringWidget fue abierto/mostrado
onClosedWidget fue cerrado por el usuario
onCompleteduserId: stringEncuesta completada con éxito
onPartialCompleteduserId: stringEncuesta completada parcialmente
onErrormessage: stringOcurrió un error en el widget
onPageChangedpage: stringUsuario navegó a otra página dentro del widget
onQuestionAnsweredUsuario respondió una pregunta. Funciona solo para Flex Survey
onResizeheight: numberWidget fue redimensionado
const options = {
    callbacks: {
        onOpened: (userId) => {
            console.log("Widget abierto para:", userId);
            analytics.track("widget_opened", { userId });
        },
        onCompleted: (userId) => {
            console.log("Encuesta completada:", userId);
            analytics.track("survey_completed", { userId });
        },
        onPartialCompleted: (userId) => {
            console.log("Encuesta parcial:", userId);
        },
        onError: (message) => {
            console.error("Error en widget:", message);
            errorTracker.capture(message);
        },
        onClosed: () => {
            console.log("Widget cerrado");
        },
        onPageChanged: (page) => {
            console.log("Página cambiada:", page);
        },
        onQuestionAnswered: () => {
            console.log("Pregunta respondida");
        },
        onResize: (height) => {
            console.log("Nueva altura:", height);
        }
    }
};

Manejo de la Respuesta

La función createSoluCXWidget retorna una Promise:

createSoluCXWidget(apiKey, type, data, options)
    .then(response => {
        console.log(response); // { status: "success" }
    })
    .catch(error => {
        console.log(error); // WidgetError { status: "error", message: "Mensaje de error" }
    });

Tabla Comparativa Completa

Estilización

FuncionalidadPlataformaCódigoDescripción
Logo y marcaCarga y configuración del logotipo
Colores principalesColores primario y secundario
Colores dinámicosColores basados en puntuación del cliente
Temas Form BuilderTemas 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 widgetinline, bottomBar, bottomBox, modal
Dimensiones (width/height)Ancho y alto del contenedor
Elemento objetivo (target)ID del elemento DOM para inline

Comportamiento

FuncionalidadPlataformaCódigoDescripción
Pantalla de agradecimientoMensajes y HTML post-encuesta
RedirecciónURL de redirección después de completar
Auto-envío (timeout)Envío automático después de tiempo
Texto de aceptaciónPersonalización del término de consentimiento
Estrategia de aceptaciónOpt-in vs opt-out
Canales de contactoSolicitar contacto por clasificación
Ocultar créditosRemover "Powered by SoluCX"
Bloquear scrollBloquear scroll durante visualización
Permitir HTMLHTML en preguntas y descripciones
IdiomaIdioma del widget
CallbacksFunciones para eventos del widget

Cuarentena

FuncionalidadPlataformaCódigoDescripción
Cuarentena por cookieBasada en cookies del navegador
Reintentos (retry)Número de intentos e intervalo
Delay post-evaluaciónTiempo de espera después de respuesta

Datos e Integración

FuncionalidadPlataformaCódigoDescripción
API KeyClave de autenticación
Tipo de widgetModo de visualización
Datos del clienteNombre, email, teléfono, etc
Datos de transacciónID, valor, tienda, empleado
Parámetros custom (param_*)Campos extras para trazabilidad
JornadaIdentificador 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:

const apiKey = "SU_API_KEY";
const type = "bottomBox";
const data = {
    transaction_id: "pedido-12345",
    name: "María García",
    email: "[email protected]",
    store_id: "ecommerce-principal",
    amount: 299.90,
    journey: "post-compra",
    param_producto: "Smartphone XYZ",
    param_categoria: "Electrónicos"
};
const options = {
    width: 400,
    retry: { attempts: 3, interval: 2 },
    waitDelayAfterRating: 30,
    callbacks: {
        onCompleted: (userId) => {
            dataLayer.push({
                event: "survey_completed",
                userId: userId
            });
        }
    }
};

createSoluCXWidget(apiKey, type, data, options);

Atención al Cliente

Para recolectar feedback después de interacción con soporte:

const apiKey = "SU_API_KEY";
const type = "modal";
const data = {
    name: "Carlos Oliveira",
    email: "[email protected]",
    store_id: "central-atencion",
    employee_id: "agente-42",
    employee_name: "Ana Souza",
    journey: "post-atencion",
    param_protocolo: "2024-ABC-789",
    param_canal: "chat"
};
const options = {
    callbacks: {
        onCompleted: () => {
            window.location.href = "/feedback-gracias";
        },
        onClosed: () => {
            console.log("Cliente cerró encuesta de atención");
        }
    }
};

createSoluCXWidget(apiKey, type, data, options);

Encuesta en Tienda Física (Tótem/Tablet)

Para recolección de feedback presencial en dispositivos dedicados:

const apiKey = "SU_API_KEY";
const type = "inline";
const data = {
    store_id: "tienda-centro",
    store_name: "Tienda Centro",
    journey: "experiencia-tienda",
    param_totem: "totem-entrada-01"
};
const options = {
    target: "encuesta-container",
    width: 800,
    height: 600,
    waitDelayAfterRating: 0,
    retry: { attempts: 1, interval: 0 },
    callbacks: {
        onCompleted: () => {
            setTimeout(() => {
                location.reload();
            }, 5000);
        }
    }
};

createSoluCXWidget(apiKey, type, data, options);

Feedback en Aplicación Web

Para integración en paneles/dashboards web:

const apiKey = "SU_API_KEY";
const type = "inline";
const data = {
    customer_id: "usr-98765",
    name: "Pedro Santos",
    email: "[email protected]",
    journey: "uso-plataforma",
    param_plan: "enterprise",
    param_feature: "reportes"
};
const options = {
    target: "feedback-section",
    width: 600,
    callbacks: {
        onOpened: (userId) => {
            console.log("Encuesta mostrada para:", userId);
        },
        onCompleted: (userId) => {
            showNotification("¡Gracias por su feedback!");
        },
        onResize: (height) => {
            document.getElementById("feedback-section").style.height = height + "px";
        }
    }
};

createSoluCXWidget(apiKey, type, data, options);

Mejores Prácticas

Cuándo usar cada tipo de widget

TipoMejor paraEvitar cuando
inlinePáginas dedicadas, tótems, iframesNo desea ocupar espacio en el layout
bottomBarRecolección pasiva, sitios de contenidoMuchos elementos fijos en el pie
bottomBoxE-commerce, post-transacciónSitio con chat en la misma esquina
bottomBoxLeftAlternativa al bottomBoxSitio con menú lateral izquierdo
modalEncuestas obligatorias, post-atenciónExperiencias que no pueden ser interrumpidas

Combinando configuraciones de Plataforma y Código

  1. Defina la identidad visual en la plataforma antes de implementar el código
  2. Configure la cuarentena en la plataforma para control robusto (IP, CPF, fingerprint)
  3. Complemente con cuarentena en el código para control adicional vía cookies
  4. Use callbacks en el código para integrar con analytics y sistemas internos
  5. Personalice el CSS en la plataforma para ajustes visuales finos

Optimización de Cuarentena

  • Ambiente de pruebas: Use waitDelayAfterRating: 0 y retry.attempts: 1 para facilitar pruebas
  • Producción: Recomendado waitDelayAfterRating: 30-60 días para evitar fatiga
  • Tótems/Tablets: Use waitDelayAfterRating: 0 para 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

ProblemaVerificaciónSolución
API Key inválidaConsola del navegadorVerifique la clave en la plataforma administrativa
Datos obligatorios faltantesConsola del navegadorComplete name o customer_id
Cuarentena activaCookies del navegadorLimpie cookies o reduzca waitDelayAfterRating para pruebas
Elemento target no existeInspector del DOMVerifique que el ID del target existe antes de llamar al widget
Script no cargadoPestaña NetworkConfirme que widget.js se cargó con éxito

Problemas de CSS y posicionamiento

ProblemaCausa probableSolución
Widget cortadoContenedor con overflow: hiddenRemueva overflow: hidden del contenedor padre
Widget detrás de otros elementosz-index bajoAjuste el z-index vía CSS personalizado en la plataforma
Widget no responsivoAncho fijoNo defina width o use valores porcentuales
Scroll bloqueado después de cerrarlockScroll activoDesactive lockScroll en la plataforma si es necesario

Depuración de callbacks

const options = {
    callbacks: {
        onOpened: (userId) => console.log("[DEBUG] Abierto:", userId),
        onClosed: () => console.log("[DEBUG] Cerrado"),
        onCompleted: (userId) => console.log("[DEBUG] Completado:", userId),
        onPartialCompleted: (userId) => console.log("[DEBUG] Parcial:", userId),
        onError: (msg) => console.error("[DEBUG] Error:", msg),
        onPageChanged: (page) => console.log("[DEBUG] Página:", page),
        onQuestionAnswered: () => console.log("[DEBUG] Pregunta respondida"),
        onResize: (h) => console.log("[DEBUG] Resize:", h)
    }
};

Ejemplos de Código Completos

Ejemplo Básico

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8" />
    <title>Widget SoluCX - Básico</title>
    <script src="https://widget.solucx.com.br/widget.js"></script>
</head>
<body>
    <script>
        createSoluCXWidget("SU_API_KEY", "bottomBox", {
            name: "Nombre del Cliente",
            email: "[email protected]",
            store_id: "tienda-001"
        });
    </script>
</body>
</html>

Ejemplo Avanzado con Todos los Parámetros

<!DOCTYPE html>
<html lang="es">
<head>
    <meta charset="UTF-8" />
    <title>Widget SoluCX - Avanzado</title>
    <script src="https://widget.solucx.com.br/widget.js"></script>
</head>
<body>
    <div id="widget-container"></div>

    <script>
        const apiKey = "SU_API_KEY";
        const type = "inline";

        const data = {
            transaction_id: "TXN-2024-001",
            form_id: "form-flex-001",
            customer_id: "CLI-12345",
            name: "María García",
            email: "[email protected]",
            phone: "11999887766",
            phone2: "1133445566",
            document: "123.456.789-00",
            birth_date: "1990-05-15",
            store_id: "tienda-centro",
            store_name: "Tienda Centro",
            employee_id: "emp-042",
            employee_name: "Ana Souza",
            amount: 1599.90,
            score: 8,
            journey: "post-compra",
            param_canal: "sitio-web",
            param_campaña: "verano-2024",
            param_categoria: "electronicos"
        };

        const options = {
            target: "widget-container",
            width: 700,
            height: 500,
            retry: {
                attempts: 5,
                interval: 2
            },
            waitDelayAfterRating: 30,
            callbacks: {
                onOpened: (userId) => {
                    console.log("Widget abierto para:", userId);
                },
                onCompleted: (userId) => {
                    console.log("Encuesta completada por:", userId);
                },
                onPartialCompleted: (userId) => {
                    console.log("Encuesta parcial de:", userId);
                },
                onError: (message) => {
                    console.error("Error:", message);
                },
                onClosed: () => {
                    console.log("Widget cerrado");
                },
                onPageChanged: (page) => {
                    console.log("Página:", page);
                },
                onQuestionAnswered: () => {
                    console.log("Pregunta respondida");
                },
                onResize: (height) => {
                    console.log("Nueva altura:", height);
                }
            }
        };

        createSoluCXWidget(apiKey, type, data, options)
            .then(response => console.log("Éxito:", response))
            .catch(error => console.error("Error:", error));
    </script>
</body>
</html>

Ejemplo con Callbacks y Analytics

function initSoluCXWidget(customerData) {
    const apiKey = "SU_API_KEY";
    const type = "bottomBox";

    const data = {
        ...customerData,
        journey: "post-compra"
    };

    const options = {
        width: 400,
        retry: { attempts: 3, interval: 1 },
        waitDelayAfterRating: 60,
        callbacks: {
            onOpened: (userId) => {
                gtag("event", "widget_opened", {
                    event_category: "SoluCX",
                    event_label: userId
                });
            },
            onCompleted: (userId) => {
                gtag("event", "survey_completed", {
                    event_category: "SoluCX",
                    event_label: userId
                });
                showThankYouBanner();
            },
            onError: (message) => {
                Sentry.captureMessage("SoluCX Widget Error: " + message);
            },
            onClosed: () => {
                gtag("event", "widget_closed", {
                    event_category: "SoluCX"
                });
            }
        }
    };

    return createSoluCXWidget(apiKey, type, data, options);
}

initSoluCXWidget({
    name: "Juan García",
    email: "[email protected]",
    store_id: "tienda-01",
    amount: 150.00,
    param_pedido: "PED-9876"
});

Referencias Técnicas

SDKs Disponibles

SDKTecnologíaPaquete
Widget JavaScriptJavaScript vanillawidget.js (CDN)
SDK React NativeReact Native / Expo@solucx/react-native-solucx-widget
SDK Web ComponentVue.js / Web Componentssolucx-survey-widget
SDK FlutterFlutter / Dartsolucx_widget

URL del Script

https://widget.solucx.com.br/widget.js

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.