SoluCX Widget

O widget SoluCX permite a integração de pesquisas diretamente no seu site, proporcionando uma maneira fácil e eficiente de coletar feedback dos clientes.

Compatibilidade com Form Flex e Pesquisas Survey

O widget é compatível com os tipos de pesquisa Form Flex e Survey, permitindo flexibilidade na coleta de dados de acordo com as necessidades do seu negócio.

Instalação

Para usar o widget, adicione o seguinte script ao seu site:

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

Esse script expõe a função global createSoluCXWidget, que é utilizada para inicializar o widget.

Uso via Script Tag

Para inserção direta via <script> no HTML:

  1. Adicione o script acima na tag <head> ou antes da tag de fechamento <body> no seu HTML.
  2. Crie o widget dentro de uma tag <script>.

Nota: Quando adicionado na tag <head>, é necessário verificar se o DOM foi carregado ou adicionar a função em algum método de gatilho (por exemplo, clique em botão).

Exemplo:

<!DOCTYPE html>
<html lang="pt">
    <head>
        <meta charset="UTF-8" />
        <title>Exemplo de Widget SoluCX</title>
        <script src="https://widget.solucx.com.br/widget.js"></script>
    </head>
    <body>
        <script>
            const apiKey = "SUA_API_KEY";
            const type = "inline";
            const data = {
                name: "Nome do Cliente",
                transaction_id: "ID da Transação",
                email: "[email protected]",
                document: "123.456.789-00",
            };

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

Uso via Google Tag Manager

Para utilizar o SoluCX Widget dentro do Google Tag Manager (GTM):

  1. Acesse sua conta do GTM e selecione o container desejado.
  2. Clique em Tags no menu lateral e depois em Nova.
  3. Dê um nome à tag e clique em Configuração da tag.
  4. Selecione HTML Personalizado.
  5. No campo HTML Personalizado, insira o seguinte código (ajustando conforme necessário):
    <script src="https://widget.solucx.com.br/widget.js"></script>
    <script>
      (function () {
        var apiKey = "SUA_API_KEY";
        var type = "modal"; // inline, bottomBar, bottomBox, bottomBoxLeft ou modal
        var data = {
          name: "Nome do Cliente",
          transaction_id: "ID da Transação",
          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 criado com sucesso:", response);
          })
          .catch(function (error) {
            console.error("Erro ao criar widget:", error);
          });
      })();
    </script>
    
  6. Em Acionamento, selecione quando você deseja que a tag seja disparada (por exemplo, em todas as páginas).
  7. Salve a tag e publique as alterações no container.

Nota: A tag <script src="https://widget.solucx.com.br/widget.js"></script> pode ser colocada junto com o código personalizado acima na mesma Tag de HTML Personalizado, ou em uma tag separada que seja disparada antes (por exemplo, na inicialização do site). O importante é que o script esteja carregado antes da chamada à função createSoluCXWidget.

Exemplo Avançado: Botão Flutuante "Avalie"

Neste exemplo, o script do widget é carregado em uma tag separada na inicialização do site. Uma segunda tag cria um botão flutuante na lateral da página que, ao ser clicado, abre o widget. O botão só é exibido após verificar que a função createSoluCXWidget está disponível.

Tag 1 — Carregamento do Script (acionada em todas as páginas):

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

Tag 2 — Botão Flutuante + Widget (acionada em todas as páginas, após a Tag 1):

<script>
  (function () {
    if (typeof createSoluCXWidget !== "function") {
      console.warn("SoluCX Widget não está disponível.");
      return;
    }

    var button = document.createElement("button");
    button.innerText = "Avalie";
    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 = "SUA_API_KEY";
      var type = "modal";
      var data = {
        name: "Nome do Cliente",
        transaction_id: "ID da Transação",
        email: "[email protected]",
      };

      createSoluCXWidget(apiKey, type, data)
        .then(function (response) {
          console.log("Widget aberto com sucesso:", response);
        })
        .catch(function (error) {
          console.error("Erro ao abrir widget:", error);
        });
    });

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

Tipos de Widget

Os tipos de widget disponíveis são:

  • bottomBar: Exibe o widget como uma barra fixa na parte inferior da página.
    No modo bottomBar, o widget é exibido como uma barra horizontal fixa na parte inferior da página.
    Isso significa que ele permanece visível enquanto o usuário rola a página, garantindo que o widget esteja sempre acessível.
  • bottomBox: Exibe o widget como uma caixa fixa no canto inferior direito da página.
    No modo bottomBox, o widget é exibido como uma caixa fixa no canto inferior direito da página.
    Isso permite que o widget seja destacado sem interferir no conteúdo principal, ideal para capturar a atenção do usuário.
  • bottomBoxLeft: Exibe o widget como uma caixa fixa no canto inferior esquerdo da página.
    No modo bottomBoxLeft, o widget é exibido como uma caixa fixa no canto inferior esquerdo da página.
    Assim como o bottomBox, ele destaca o widget sem interferir no conteúdo principal, mas posicionado no lado esquerdo.
  • inline: Exibe o widget embutido no conteúdo da página.
    No modo inline, o widget é exibido diretamente dentro do layout existente.
    Isso significa que ele se integra perfeitamente ao conteúdo da página, sem sobrepor ou cobrir outros elementos. É ideal para quando você deseja que o widget faça parte do fluxo natural do conteúdo.
  • modal: Exibe o widget como um modal centralizado na página.
    No modo modal, o widget é exibido como uma janela modal centralizada na página.
    Isso significa que ele sobrepõe o conteúdo da página, capturando toda a atenção do usuário. É ideal para quando você deseja garantir que o usuário interaja com o widget antes de continuar navegando.

Parâmetros de Inicialização

A função createSoluCXWidget aceita os seguintes parâmetros:

Parâmetro apiKey (string) Obrigatório

Chave de API fornecida pela SoluCX.

Exemplo:

const apiKey = "SUA_API_KEY";

Parâmetro type (string) Obrigatório

Tipo de widget a ser criado. Valores aceitos:

  • inline
  • bottomBar
  • bottomBox (posicionado à direita por padrão)
  • bottomBoxLeft
  • modal

Exemplo:

const type = "bottomBox";

Parâmetro data

Dados do cliente a serem enviados para o Widget.
transaction_idstring
ID da transação. Este é o ID externo fornecido pelo cliente.
form_idstring
ID do formulário. Obrigatório apenas se direcionado para Formulários Flex
customer_idstring
ID do cliente. Obrigatório se não fornecer transaction_id OU name E (email OU phone)
namestring
Nome do cliente. Obrigatório se não fornecer transaction_id OU customer_id
emailstring
Email do cliente. Obrigatório se não fornecer transaction_id OU customer_id E phone
phonestring
Telefone do cliente. Obrigatório se não fornecer transaction_id OU customer_id E email
phone2string
Telefone secundário do cliente.
documentstring
Documento do cliente.
birth_datestring
Data de nascimento do cliente.
store_idstring
ID da loja. Obrigatório se não fornecer transaction_id
store_namestring
Nome da loja.
employee_idstring
ID do funcionário. Obrigatório se não fornecer transaction_id
employee_namestring
Nome do funcionário.
amountnumber
Valor da transação. Obrigatório se não fornecer transaction_id
scorenumber
Pontuação do cliente.
journeystring
Jornada do cliente. Obrigatório se mais de uma jornada estiver registrada para a instância. Se não fornecido, a jornada padrão será usada. Um erro será exibido se fornecido incorretamente.

Exemplo:

{
    transaction_id: 'ID da Transação',
    form_id: 'ID do Formulário',
    customer_id: 'ID do Cliente',
    name: 'Nome do Cliente',
    email: '[email protected]',
    phone: '1234567890',
    phone2: '0987654321',
    document: 'ABC123',
    birth_date: '1990-01-01',
    store_id: 'ID da Loja',
    store_name: 'Nome da Loja',
    employee_id: 'ID do Funcionário',
    employee_name: 'Nome do Funcionário',
    amount: 100,
    score: 5,
    journey: 'compra',
    param_cupom: 'XXX-XXX'
}

Qualquer campo prefixado com param_ é considerado um parâmetro extra de transação que pode ser usado para rastreabilidade.

Parâmetro options

Opções de configuração adicionais para o Widget.
targetstring|null
Para widgets inline, define o ID do elemento onde o widget será inserido.
widthnumber
Largura do widget. Quando não definido, a largura padrão é 100%.
heightnumber
Altura do widget. Quando não definido, a altura é automática.
retryobject
Configura tentativas de exibição do widget. attempts: Quantas vezes mostrar o widget antes de desistir, interval: Intervalo (em dias) entre tentativas de coleta.
waitDelayAfterRatingnumber
Tempo para o widget reaparecer após a resposta (em dias). Valor padrão: 60.
callbacksobject
Habilita as opções de callback.

Exemplo:

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: "meu_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
};

Configuração de Callbacks

O widget suporta funções de callback que são acionadas quando eventos específicos ocorrem. Adicione-as ao seu objeto options:

  • callbacks (object): Funções de callback opcionais para eventos do widget.
    • onOpened (function): Chamada quando o widget é aberto. Recebe userId como parâmetro.
    • onClosed (function): Chamada quando o widget é fechado.
    • onError (function): Chamada quando ocorre um erro. Recebe a message de erro como parâmetro.
    • onPageChanged (function): Chamada quando o usuário navega para uma página diferente dentro do widget. Recebe page como parâmetro.
    • onQuestionAnswered (function): Chamada quando o usuário responde uma pergunta.
    • onCompleted (function): Chamada quando o widget é completado com sucesso. Recebe userId como parâmetro.
    • onPartialCompleted (function): Chamada quando o widget é completado parcialmente. Recebe userId como parâmetro.
    • onResize (function): Chamada quando o widget é redimensionado. Recebe height como parâmetro.

Exemplo com callbacks:

const options = {
    target: "meu_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    callbacks: {
        onOpened: (userId) => {
            console.log('Widget aberto para usuário:', userId);
        },
        onCompleted: (userId) => {
            console.log('Widget completado pelo usuário:', userId);
            window.location.href = '/obrigado';
        },
        onError: (message) => {
            console.error('Erro no widget:', message);
        },
        onClosed: () => {
            console.log('Widget fechado');
        }
    }
};

Exemplo Completo:

const apiKey = "SUA_API_KEY";
const type = "inline";
const data = {
    transaction_id: "ID da Transação",
    form_id: "ID do Formulário",
    customer_id: "ID do Cliente",
    name: "Nome do Cliente",
    email: "[email protected]",
    phone: "1234567890",
    phone2: "0987654321",
    document: "ABC123",
    birth_date: "1990-01-01",
    store_id: "ID da Loja",
    store_name: "Nome da Loja",
    employee_id: "ID do Funcionário",
    employee_name: "Nome do Funcionário",
    amount: 100,
    score: 5,
    journey: "compra",
    param_cupom: "XXX-XXX",
};

const options = {
    target: "meu_div_id",
    width: 600,
    height: 400,
    retry: {
        attempts: 5,
        interval: 1,
    },
    waitDelayAfterRating: 30,
    callbacks: {
        onOpened: (userId) => console.log('Widget aberto:', userId),
        onCompleted: (userId) => console.log('Widget completado:', userId),
        onError: (message) => console.error('Erro no widget:', message),
        onClosed: () => console.log('Widget fechado')
    }
};

createSoluCXWidget(apiKey, type, data, options);

Tratamento da Resposta do Widget

A função createSoluCXWidget retorna uma promessa que resolve para um objeto com a seguinte estrutura:

  • status: "success" ou "error"
  • message: Uma string contendo uma mensagem de erro se o status for "error"

Exemplo:

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

Conclusão

Seguindo as instruções acima, você pode integrar e configurar rapidamente o Widget SoluCX em sua aplicação ou site. Use os exemplos fornecidos para ajustar e personalizar o widget de acordo com suas necessidades de coleta de dados e feedback dos clientes.

Se você tiver dúvidas ou encontrar problemas, entre em contato com o suporte da SoluCX. Boa implementação!