SoluCX Widget

El widget SoluCX permite la integración de encuestas directamente en su sitio web, proporcionando una manera fácil y eficiente de recopilar comentarios de los clientes.

Compatibilidad con Form Flex y Encuestas Survey

El widget es compatible con los tipos de encuesta Form Flex y Survey, permitiendo flexibilidad en la recopilación de datos de acuerdo con las necesidades de su negocio.

Instalación

Para usar el widget, agregue el siguiente script a su sitio web:

<script src="https://widget.solucx.com.br/widget.js"></script>

Este script expone la función global createSoluCXWidget, que se utiliza para inicializar el widget.

Uso vía Script Tag

Para inserción directa vía <script> en HTML:

  1. Agregue el script anterior en la etiqueta <head> o antes de la etiqueta de cierre <body> en su HTML.
  2. Cree el widget dentro de una etiqueta <script>.

Nota: Cuando se agrega en la etiqueta <head>, es necesario verificar si el DOM se ha cargado o agregar la función en algún método de disparo (por ejemplo, clic en botón).

Ejemplo:

<!DOCTYPE html>
<html lang="es">
    <head>
        <meta charset="UTF-8" />
        <title>Ejemplo de Widget SoluCX</title>
        <script src="https://widget.solucx.com.br/widget.js"></script>
    </head>
    <body>
        <script>
            const apiKey = "SU_API_KEY";
            const type = "inline";
            const data = {
                name: "Nombre del Cliente",
                transaction_id: "ID de la Transacción",
                email: "[email protected]",
                document: "123.456.789-00",
            };

            createSoluCXWidget(apiKey, type, data);
        </script>
    </body>
</html>

Uso vía Google Tag Manager

Para utilizar el SoluCX Widget dentro de Google Tag Manager (GTM):

  1. Acceda a su cuenta de GTM y seleccione el contenedor deseado.
  2. Haga clic en Etiquetas en el menú lateral y luego en Nueva.
  3. Dele un nombre a la etiqueta y haga clic en Configuración de la etiqueta.
  4. Seleccione HTML Personalizado.
  5. En el campo HTML Personalizado, inserte el siguiente código (ajustando según sea necesario):
    <script src="https://widget.solucx.com.br/widget.js"></script>
<script>
  (function () {
    var apiKey = "SU_API_KEY";
    var type = "modal"; // inline, bottomBar, bottomBox, bottomBoxLeft o modal
    var data = {
      name: "Nombre del Cliente",
      transaction_id: "ID de la Transacción",
      email: "[email protected]",
      document: "123.456.789-00",
    };
    var options = {
      width: 600,
      height: 400,
      retry: {
        attempts: 3,
        interval: 2,
      },
      waitDelayAfterRating: 30,
    };

    createSoluCXWidget(apiKey, type, data, options)
      .then(function (response) {
        console.log("Widget creado exitosamente:", response);
      })
      .catch(function (error) {
        console.error("Error al crear widget:", error);
      });
  })();
</script>
  6. En Activación, seleccione cuándo desea que se active la etiqueta (por ejemplo, en todas las páginas).
  7. Guarde la etiqueta y publique los cambios en el contenedor.

Nota: La etiqueta <script src="https://widget.solucx.com.br/widget.js"></script> puede colocarse junto con el código personalizado anterior en la misma Etiqueta de HTML Personalizado, o en una etiqueta separada que se dispare antes (por ejemplo, en la inicialización del sitio). Lo importante es que el script esté cargado antes de llamar a la función createSoluCXWidget.

Ejemplo Avanzado: Botón Flotante "Evalúe"

En este ejemplo, el script del widget se carga en una etiqueta separada en la inicialización del sitio. Una segunda etiqueta crea un botón flotante en el lateral de la página que, al hacer clic, abre el widget. El botón solo se muestra después de verificar que la función createSoluCXWidget está disponible.

Etiqueta 1 — Carga del Script (activada en todas las páginas):

<script src="https://widget.solucx.com.br/widget.js"></script>

Etiqueta 2 — Botón Flotante + Widget (activada en todas las páginas, después de la Etiqueta 1):

<script>
  (function () {
    if (typeof createSoluCXWidget !== "function") {
      console.warn("SoluCX Widget no está disponible.");
      return;
    }

    var button = document.createElement("button");
    button.innerText = "Evalúe";
    button.style.cssText =
      "position:fixed;right:0;top:50%;transform:translateY(-50%);" +
      "writing-mode:vertical-rl;text-orientation:mixed;" +
      "background-color:#4CAF50;color:#fff;border:none;padding:12px 8px;" +
      "cursor:pointer;font-size:14px;font-weight:bold;border-radius:8px 0 0 8px;" +
      "z-index:9999;box-shadow:0 2px 8px rgba(0,0,0,0.2);";

    button.addEventListener("click", function () {
      var apiKey = "SU_API_KEY";
      var type = "modal";
      var data = {
        name: "Nombre del Cliente",
        transaction_id: "ID de la Transacción",
        email: "[email protected]",
      };

      createSoluCXWidget(apiKey, type, data)
        .then(function (response) {
          console.log("Widget abierto exitosamente:", response);
        })
        .catch(function (error) {
          console.error("Error al abrir widget:", error);
        });
    });

    document.body.appendChild(button);
  })();
</script>

Tipos de Widget

Los tipos de widget disponibles son:

  • bottomBar: Muestra el widget como una barra fija en la parte inferior de la página.
    En modo bottomBar, el widget se muestra como una barra horizontal fija en la parte inferior de la página.
    Esto significa que permanece visible mientras el usuario desplaza la página, garantizando que el widget esté siempre accesible.
  • bottomBox: Muestra el widget como una caja fija en la esquina inferior derecha de la página.
    En modo bottomBox, el widget se muestra como una caja fija en la esquina inferior derecha de la página.
    Esto permite que el widget se destaque sin interferir con el contenido principal, ideal para capturar la atención del usuario.
  • bottomBoxLeft: Muestra el widget como una caja fija en la esquina inferior izquierda de la página.
    En modo bottomBoxLeft, el widget se muestra como una caja fija en la esquina inferior izquierda de la página.
    Al igual que bottomBox, destaca el widget sin interferir con el contenido principal, pero posicionado en el lado izquierdo.
  • inline: Muestra el widget integrado en el contenido de la página.
    En modo inline, el widget se muestra directamente dentro del diseño existente.
    Esto significa que se integra perfectamente con el contenido de la página, sin superponer ni cubrir otros elementos. Es ideal cuando desea que el widget sea parte del flujo natural del contenido.
  • modal: Muestra el widget como un modal centrado en la página.
    En modo modal, el widget se muestra como una ventana modal centrada en la página.
    Esto significa que se superpone al contenido de la página, capturando toda la atención del usuario. Es ideal cuando desea garantizar que el usuario interactúe con el widget antes de continuar navegando.

Parámetros de Inicialización

La función createSoluCXWidget acepta los siguientes parámetros:

Parámetro apiKey (string) Obligatorio

Clave de API proporcionada por SoluCX.

Ejemplo:

const apiKey = "SU_API_KEY";

Parámetro type (string) Obligatorio

Tipo de widget a crear. Valores aceptados:

  • inline
  • bottomBar
  • bottomBox (posicionado a la derecha por defecto)
  • bottomBoxLeft
  • modal

Ejemplo:

const type = "bottomBox";

Parámetro data

Datos del cliente a enviar al Widget.
transaction_idstring
ID de la transacción. Este es el ID externo proporcionado por el cliente.
form_idstring
ID del formulario. Obligatorio solo si se dirige a Formularios Flex
customer_idstring
ID del cliente. Obligatorio si no proporciona transaction_id O name Y (email O phone)
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.
birth_datestring
Fecha de nacimiento del cliente.
store_idstring
ID de la tienda. Obligatorio si no proporciona transaction_id
store_namestring
Nombre de la tienda.
employee_idstring
ID del empleado. Obligatorio si no proporciona transaction_id
employee_namestring
Nombre del empleado.
amountnumber
Valor de la transacción. Obligatorio si no proporciona transaction_id
scorenumber
Puntuación 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.

Ejemplo:

{
    transaction_id: 'ID de la Transacción',
    form_id: 'ID del Formulario',
    customer_id: 'ID del Cliente',
    name: 'Nombre del Cliente',
    email: '[email protected]',
    phone: '1234567890',
    phone2: '0987654321',
    document: 'ABC123',
    birth_date: '1990-01-01',
    store_id: 'ID de la Tienda',
    store_name: 'Nombre de la Tienda',
    employee_id: 'ID del Empleado',
    employee_name: 'Nombre del Empleado',
    amount: 100,
    score: 5,
    journey: 'compra',
    param_cupon: 'XXX-XXX'
}

Cualquier campo con el prefijo param_ se considera un parámetro extra de transacción que puede usarse para rastreabilidad.

Parámetro options

Opciones de configuración adicionales para el Widget.
targetstring|null
Para widgets inline, define el ID del elemento donde se insertará el widget.
widthnumber
Ancho del widget. Cuando no se define, el ancho predeterminado es 100%.
heightnumber
Altura del widget. Cuando no se define, la altura es automática.
retryobject
Configura intentos de visualización del widget. attempts: Cuántas veces mostrar el widget antes de desistir, interval: Intervalo (en días) entre intentos de recopilación.
waitDelayAfterRatingnumber
Tiempo para que el widget reaparezca después de una respuesta (en días). Valor predeterminado: 60.
callbacksobject
Habilita las opciones de callback.

Ejemplo:

interface WidgetOptions {
    target?: string | null;
    width?: number;
    height?: number;
    retry?: {
        attempts?: number;
        interval?: number;
    };
    waitDelayAfterRating?: number;
    callbacks?: {
        onOpened?: (userId: string) => void;
        onClosed?: () => void;
        onError?: (message: string) => void;
        onPageChanged?: (page: string) => void;
        onQuestionAnswered?: () => void;
        onCompleted?: (userId: string) => void;
        onPartialCompleted?: (userId: string) => void;
        onResize?: (height: string) => void;
    };
}

const options: WidgetOptions = {
    target: "mi_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
};

Configuración de Callbacks

El widget soporta funciones de callback que se activan cuando ocurren eventos específicos. Agrégalas a tu objeto options:

  • callbacks (object): Funciones de callback opcionales para eventos del widget.
    • onOpened (function): Llamada cuando el widget se abre. Recibe userId como parámetro.
    • onClosed (function): Llamada cuando el widget se cierra.
    • onError (function): Llamada cuando ocurre un error. Recibe el message de error como parámetro.
    • onPageChanged (function): Llamada cuando el usuario navega a una página diferente dentro del widget. Recibe page como parámetro.
    • onQuestionAnswered (function): Llamada cuando el usuario responde una pregunta.
    • onCompleted (function): Llamada cuando el widget se completa exitosamente. Recibe userId como parámetro.
    • onPartialCompleted (function): Llamada cuando el widget se completa parcialmente. Recibe userId como parámetro.
    • onResize (function): Llamada cuando el widget se redimensiona. Recibe height como parámetro.

Ejemplo con callbacks:

const options = {
    target: "mi_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    callbacks: {
        onOpened: (userId) => {
            console.log('Widget abierto para usuario:', userId);
        },
        onCompleted: (userId) => {
            console.log('Widget completado por usuario:', userId);
            window.location.href = '/gracias';
        },
        onError: (message) => {
            console.error('Error en widget:', message);
        },
        onClosed: () => {
            console.log('Widget cerrado');
        }
    }
};

Ejemplo Completo:

const apiKey = "SU_API_KEY";
const type = "inline";
const data = {
    transaction_id: "ID de la Transacción",
    form_id: "ID del Formulario",
    customer_id: "ID del Cliente",
    name: "Nombre del Cliente",
    email: "[email protected]",
    phone: "1234567890",
    phone2: "0987654321",
    document: "ABC123",
    birth_date: "1990-01-01",
    store_id: "ID de la Tienda",
    store_name: "Nombre de la Tienda",
    employee_id: "ID del Empleado",
    employee_name: "Nombre del Empleado",
    amount: 100,
    score: 5,
    journey: "compra",
    param_cupon: "XXX-XXX",
};

const options = {
    target: "mi_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    callbacks: {
        onOpened: (userId) => console.log('Widget abierto:', userId),
        onCompleted: (userId) => console.log('Widget completado:', userId),
        onError: (message) => console.error('Error en widget:', message),
        onClosed: () => console.log('Widget cerrado')
    }
};

createSoluCXWidget(apiKey, type, data, options);

Tratamiento de la Respuesta del Widget

La función createSoluCXWidget devuelve una promesa que resuelve a un objeto con la siguiente estructura:

  • status: "success" o "error"
  • message: Una cadena que contiene un mensaje de error si el status es "error"

Ejemplo:

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

Conclusión

Siguiendo las instrucciones anteriores, puede integrar y configurar rápidamente el Widget SoluCX en su aplicación o sitio web. Utilice los ejemplos proporcionados para ajustar y personalizar el widget según sus necesidades de recopilación de datos y comentarios de los clientes.

Si tiene dudas o encuentra algún problema, contacte al soporte de SoluCX. ¡Buena implementación!

Cómo configurar
Documentación completa sobre el Widget SoluCX - configuraciones de plataforma y código
Flutter
Paquete Flutter para integración con el SoluCX Widget