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.

Uso baseado no exemplo de HTML

Para usar o widget, adicione o seguinte código HTML ao seu site:

<!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]",
                cpf: "123.456.789-00",
            };

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

Como usar:

  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).

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.
enableQuarantineOptionsboolean
Habilita as configurações de quarentena.
callbacksobject
Habilita as opções de callback.

Exemplo:

interface WidgetOptions {
    target?: string | null;
    width?: number;
    height?: number;
    retry?: {
        attempts?: number;
        interval?: number;
    };
    waitDelayAfterRating?: number;
    enableQuarantineOptions?: boolean;
    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: number) => void;
    };
}

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

Configuração de Callbacks

O widget agora 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,
    enableQuarantineOptions: false,
    callbacks: {
        onOpened: (userId) => {
            console.log('Widget aberto para usuário:', userId);
            // Rastrear evento de abertura do widget
        },
        onCompleted: (userId) => {
            console.log('Widget completado pelo usuário:', userId);
            // Redirecionar para página de agradecimento ou mostrar mensagem de sucesso
            window.location.href = '/obrigado';
        },
        onError: (message) => {
            console.error('Erro no widget:', message);
            // Reportar erro para seu serviço de rastreamento de erros
        },
        onClosed: () => {
            console.log('Widget fechado');
            // Limpeza ou rastreamento de fechamento
        }
    }
};

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,
    enableQuarantineOptions: false,
    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);

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.

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" }
    });

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

Renovação de Token
Flutter
Pacote Flutter para integração com o SoluCX Widget