Como configurar o Widget SoluCX
Introdução
O que é o Widget SoluCX
O Widget SoluCX é uma ferramenta de coleta de feedback que permite integrar pesquisas de satisfação diretamente em sites, aplicativos e plataformas digitais. Através dele, é possível capturar avaliações de clientes em tempo real utilizando métricas como NPS (Net Promoter Score), CSAT (Customer Satisfaction Score) e CES (Customer Effort Score).
O widget é compatível com dois tipos de pesquisa:
- Flex Survey: Formulários flexíveis e personalizáveis
- Survey (Smart Survey): Pesquisas inteligentes geradas pelo sistema
Visão Geral: Plataforma vs Código
As configurações do Widget SoluCX são divididas em dois domínios:
Plataforma Administrativa: Configurações visuais, de comportamento e de quarentena que são gerenciadas pela interface administrativa da SoluCX, sem necessidade de alterar código.
Integração via Código: Parâmetros de inicialização, dados do cliente, opções de exibição e callbacks que são definidos diretamente no código da aplicação.
| Domínio | Exemplos | Quem configura |
|---|---|---|
| Plataforma | Logo, cores, tipos de input, tela de agradecimento, quarentena por IP/CPF | Equipe de negócios ou administradores |
| Código | Tipo de widget, dados do cliente, callbacks, dimensões, retry | Equipe de desenvolvimento |
| Ambos | CSS personalizado, quarentena (plataforma + código) | Colaboração entre equipes |
Configurações de Estilização
Identidade Visual (Plataforma)
As configurações de identidade visual são gerenciadas exclusivamente pela plataforma administrativa da SoluCX:
| Configuração | Descrição | Onde configurar |
|---|---|---|
| Logo e marca | Upload do logotipo exibido no cabeçalho do widget | Plataforma > Configurações > Identidade Visual |
| Cores principais | Cor primária e secundária do widget | Plataforma > Configurações > Cores |
| Cores dinâmicas | Cores que mudam conforme a nota do cliente (ex: vermelho para detratores, verde para promotores) | Plataforma > Configurações > Cores Dinâmicas |
| Temas do Form Builder | Temas visuais pré-definidos para formulários flexíveis | Plataforma > Form Builder > Temas |
Essas configurações são aplicadas automaticamente a todos os widgets vinculados à instância, sem necessidade de alteração no código.
Tipos de Input de Avaliação (Plataforma)
O widget suporta diversos tipos de input de avaliação, todos configuráveis pela plataforma. Você pode editá-lo da mesma forma que edita o Smart Survey ou o Flex Survey:
NPS (Net Promoter Score)
Escala de 0 a 10 que mede a probabilidade de recomendação.
| Tipo de Input | Descrição |
|---|---|
| Seta | Input com seta deslizante na escala 0-10 |
| Botões | Botões numéricos individuais de 0 a 10 |
| Slider | Barra deslizante contínua de 0 a 10 |
| Botões Coloridos | Botões com gradiente de cores (vermelho ao verde) |
| Gradiente | Escala visual com gradiente de cores |
CSAT (Customer Satisfaction Score)
Mede a satisfação direta do cliente com um produto ou serviço.
| Tipo de Input | Escala | Descrição |
|---|---|---|
| Emoticons | 1-5 | Rostos expressivos de insatisfeito a muito satisfeito |
| Estrelas | 1-5 | Avaliação clássica por estrelas |
| Botões 1-5 | 1-5 | Botões numéricos de 1 a 5 |
| Botões 1-10 | 1-10 | Botões numéricos de 1 a 10 |
CES (Customer Effort Score)
Mede o esforço do cliente para resolver um problema ou completar uma ação.
| Tipo de Input | Descrição |
|---|---|
| Emoticon | Rostos expressivos representando nível de esforço |
| Botões | Botões com escala de esforço |
| Estrelas | Avaliação por estrelas do nível de facilidade |
A nomenclatura das escalas (labels dos extremos, título da pergunta) também é personalizável pela plataforma para cada tipo de pesquisa.
CSS Personalizado
A estilização avançada pode ser feita de duas formas:
Via Plataforma (customStyle)
A plataforma permite inserir CSS personalizado que será aplicado internamente ao iframe do widget:
- Acesse Plataforma > Configurações > Jornadas
- Insira regras CSS que serão injetadas dentro do widget
- Útil para ajustes finos de fontes, espaçamentos e cores internas
Via Código (options)
Para estilizar o container externo do widget (posição, dimensões, bordas), utilize os parâmetros no código:
Diferença importante: O CSS da plataforma (customStyle) atua dentro do iframe do widget. Já as opções via código controlam o container externo. Para personalizações completas, pode ser necessário combinar ambos.
Posicionamento e Dimensões (Código)
O posicionamento do widget é controlado pelo parâmetro type na inicialização:
Tipos de Widget
Embutido no conteúdo da página
O widget se integra ao fluxo natural do layout, sem sobrepor outros elementos.
- Respeita a posição no DOM
- Ideal para páginas dedicadas a feedback
- Requer um elemento
targetpara renderização
Parâmetros de Dimensão
100% auto inline. Padrão: null Configurações de Comportamento
Tela de Agradecimento (Plataforma)
Após o cliente responder a pesquisa, uma tela de agradecimento é exibida. As seguintes configurações são gerenciadas pela plataforma:
A opção customAcknowledgmentHTML permite total personalização da tela de agradecimento com HTML customizado, substituindo os campos successTitle e successMessage.
Redirecionamento e Automação (Plataforma)
| Configuração | Descrição |
|---|---|
completedUrlRedirection | URL para redirecionamento após a conclusão da pesquisa |
autoSendTimeout | Tempo (em segundos) para envio automático da pesquisa parcial |
Casos de uso práticos:
- E-commerce: Redirecionar para página de cupom de desconto após avaliação positiva
- Atendimento: Redirecionar para página de FAQ após coleta de feedback
- Auto-envio: Garantir coleta parcial caso o cliente abandone a pesquisa
Aceite e Consentimento (Plataforma)
Configurações relacionadas a LGPD e consentimento do usuário:
| Configuração | Descrição |
|---|---|
| Texto personalizado do aceite de contato | Texto personalizado do termo de aceite |
| Aceite vir selecionado por padrão | Se o checkbox de consentimento vem pré-marcado |
| Estratégia de aceite | Estratégia de aceite (ex: opt-in, opt-out) |
Considerações de LGPD: Recomenda-se que o checkbox de consentimento não venha pré-marcado (isUserConsentPreChecked: false) para estar em conformidade com a Lei Geral de Proteção de Dados. A estratégia de aceite deve ser definida em conjunto com a equipe jurídica.
Canais de Contato (Plataforma)
Configurações para habilitar solicitação de canais de contato baseada na classificação do respondente:
| Configuração | Descrição |
|---|---|
| Aceite de contato por canal se detrator | Solicitar contato se o cliente for detrator (NPS 0-6) |
| Aceite de contato por canal se neutro | Solicitar contato se o cliente for neutro (NPS 7-8) |
| Aceite de contato por canal se promotor | Solicitar contato se o cliente for promotor (NPS 9-10) |
Essa funcionalidade permite coletar informações de contato adicionais de forma estratégica, focando nos grupos que mais precisam de atenção (como detratores para recuperação de experiência).
Sistema de Quarentena
O sistema de quarentena controla a frequência com que um mesmo cliente é solicitado a responder pesquisas, evitando fadiga de pesquisa.
Quarentena na Plataforma
Configurações gerenciadas pela plataforma administrativa:
| Configuração | Descrição |
|---|---|
| Quarentena por Cookie | Habilita quarentena baseada em cookies do navegador |
| Quarentena por IP | Período de quarentena baseado no IP (em dias) |
| Quarentena por CPF | Período de quarentena baseado no CPF (em dias) |
| Antifraude por Fingerprint | Período de quarentena baseado em fingerprint do dispositivo (em dias) |
| Chave de API do Fingerprint | Chave da API de fingerprint |
| Habilitar coleta de fingerprint | Habilita coleta de fingerprint do dispositivo |
Limitações: A quarentena por cookie pode ser contornada se o usuário limpar cookies, usar modo anônimo ou trocar de dispositivo/navegador. Para controle mais rigoroso, combine com quarentena por IP, CPF ou fingerprint.
Quarentena no Código
Configurações definidas nos parâmetros options da inicialização do widget:
| Configuração | Tipo | Padrão | Descrição |
|---|---|---|---|
retry.attempts | number | 3 | Número de tentativas de exibição do widget antes de desistir |
retry.interval | number | 1 | Intervalo (em dias) entre tentativas de coleta |
waitDelayAfterRating | number | 60 | Tempo (em dias) para o widget reaparecer após uma avaliação |
Fluxo de Quarentena
O sistema de quarentena segue esta lógica:
- Primeira exibição: Widget aparece normalmente
- Cliente não responde: Após o intervalo configurado em
retry.interval, o widget tenta novamente - Tentativas esgotadas: Após
retry.attemptstentativas sem resposta, o widget para de aparecer - Cliente responde: Após a avaliação, o widget entra em quarentena por
waitDelayAfterRatingdias - Fim da quarentena: Após o período, o widget pode ser exibido novamente
Importante: O controle de quarentena do widget via código é baseado em cookies do navegador do cliente. Para cenários que exigem controle rigoroso, recomendamos implementar validações adicionais no lado do servidor ou utilizar as opções de quarentena da plataforma (IP, CPF, fingerprint).
Integração via Código
Parâmetros Obrigatórios
A função createSoluCXWidget requer dois parâmetros obrigatórios:
apiKey (string)
Chave de API fornecida pela SoluCX que identifica sua instância. Obtida na plataforma administrativa em Configurações > API.
type (string)
Define o modo de exibição do widget:
| Valor | Descrição |
|---|---|
inline | Embutido no conteúdo da página |
bottomBar | Barra fixa na parte inferior |
bottomBox | Caixa fixa no canto inferior direito |
bottomBoxLeft | Caixa fixa no canto inferior esquerdo |
modal | Modal centralizado na página |
No link do widget, os parâmetros obrigatórios são: name OU customer_id.
Dados do Cliente (data)
O objeto data contém as informações do cliente e da transação:
Campos de Identificação
transaction_id OU name E (email OU phone) Dados Pessoais
transaction_id OU customer_id transaction_id OU customer_id E phone transaction_id OU customer_id E email YYYY-MM-DD Dados Contextuais
transaction_id Parâmetros Customizados
param_ é considerado um parâmetro extra de transação para rastreabilidade.Opções de Configuração (options)
Parâmetro options
inline, define o ID do elemento DOM onde o widget será inserido. attempts: número de tentativas. interval: intervalo em dias entre tentativas. Sistema de Callbacks
O widget suporta callbacks para eventos do ciclo de vida da pesquisa:
| Callback | Parâmetro | Descrição |
|---|---|---|
onOpened | userId: string | Widget foi aberto/exibido |
onClosed | — | Widget foi fechado pelo usuário |
onCompleted | userId: string | Pesquisa concluída com sucesso |
onPartialCompleted | userId: string | Pesquisa concluída parcialmente |
onError | message: string | Ocorreu um erro no widget |
onPageChanged | page: string | Usuário navegou para outra página dentro do widget |
onQuestionAnswered | — | Usuário respondeu uma pergunta. Funciona apenas para Flex Survey |
onResize | height: number | Widget foi redimensionado |
Tratamento da Resposta
A função createSoluCXWidget retorna uma Promise:
Tabela Comparativa Completa
Estilização
| Funcionalidade | Plataforma | Código | Descrição |
|---|---|---|---|
| Logo e marca | ✓ | — | Upload e configuração do logotipo |
| Cores principais | ✓ | — | Cores primária e secundária |
| Cores dinâmicas | ✓ | — | Cores baseadas na nota do cliente |
| Temas Form Builder | ✓ | — | Temas visuais pré-definidos |
| Tipo de input (NPS/CSAT/CES) | ✓ | — | Estilo visual da escala de avaliação |
| CSS interno (customStyle) | ✓ | — | CSS dentro do iframe do widget |
| Tipo de widget | — | ✓ | inline, bottomBar, bottomBox, modal |
| Dimensões (width/height) | — | ✓ | Largura e altura do container |
| Elemento alvo (target) | — | ✓ | ID do elemento DOM para inline |
Comportamento
| Funcionalidade | Plataforma | Código | Descrição |
|---|---|---|---|
| Tela de agradecimento | ✓ | — | Mensagens e HTML pós-pesquisa |
| Redirecionamento | ✓ | — | URL de redirecionamento após conclusão |
| Auto-envio (timeout) | ✓ | — | Envio automático após tempo |
| Texto de aceite | ✓ | — | Personalização do termo de consentimento |
| Estratégia de aceite | ✓ | — | Opt-in vs opt-out |
| Canais de contato | ✓ | — | Solicitar contato por classificação |
| Ocultar créditos | ✓ | — | Remover "Powered by SoluCX" |
| Travar scroll | ✓ | — | Bloquear scroll durante exibição |
| Permitir HTML | ✓ | — | HTML em perguntas e descrições |
| Idioma | ✓ | — | Idioma do widget |
| Callbacks | — | ✓ | Funções para eventos do widget |
Quarentena
| Funcionalidade | Plataforma | Código | Descrição |
|---|---|---|---|
| Quarentena por cookie | ✓ | — | Baseada em cookies do navegador |
| Quarentena por IP | ✓ | — | Baseada no endereço IP |
| Quarentena por CPF | ✓ | — | Baseada no documento CPF |
| Quarentena por fingerprint | ✓ | — | Baseada em fingerprint do dispositivo |
| Tentativas (retry) | — | ✓ | Número de tentativas e intervalo |
| Delay pós-avaliação | — | ✓ | Tempo de espera após resposta |
Dados e Integração
| Funcionalidade | Plataforma | Código | Descrição |
|---|---|---|---|
| API Key | — | ✓ | Chave de autenticação |
| Tipo de widget | — | ✓ | Modo de exibição |
| Dados do cliente | — | ✓ | Nome, email, telefone, etc |
| Dados da transação | — | ✓ | ID, valor, loja, funcionário |
| Parâmetros custom (param_*) | — | ✓ | Campos extras para rastreabilidade |
| Jornada | — | ✓ | Identificador da jornada do cliente |
Guias Práticos
Cenários Comuns
E-commerce Pós-Compra
Ideal para coletar feedback após a finalização de um pedido:
Atendimento ao Cliente
Para coletar feedback após interação com suporte:
Pesquisa em Loja Física (Totem/Tablet)
Para coleta de feedback presencial em dispositivos dedicados:
Feedback em Aplicativo Web
Para integração em painéis/dashboards web:
Melhores Práticas
Quando usar cada tipo de widget
| Tipo | Melhor para | Evitar quando |
|---|---|---|
inline | Páginas dedicadas, totens, iframes | Não quer ocupar espaço no layout |
bottomBar | Coleta passiva, sites de conteúdo | Muitos elementos fixos no rodapé |
bottomBox | E-commerce, pós-transação | Site com chat no mesmo canto |
bottomBoxLeft | Alternativa ao bottomBox | Site com menu lateral esquerdo |
modal | Pesquisas obrigatórias, pós-atendimento | Experiências que não podem ser interrompidas |
Combinando configurações de Plataforma e Código
- Defina a identidade visual na plataforma antes de implementar o código
- Configure a quarentena na plataforma para controle robusto (IP, CPF, fingerprint)
- Complemente com quarentena no código para controle adicional via cookies
- Use callbacks no código para integrar com analytics e sistemas internos
- Personalize o CSS na plataforma para ajustes visuais finos
Otimização de Quarentena
- Ambiente de testes: Use
waitDelayAfterRating: 0eretry.attempts: 1para facilitar testes - Produção: Recomendado
waitDelayAfterRating: 30-60dias para evitar fadiga - Totens/Tablets: Use
waitDelayAfterRating: 0para permitir avaliações consecutivas de diferentes clientes - Combine métodos: Use quarentena por IP na plataforma + cookie no código para cobertura máxima
Troubleshooting
Widget não aparece
| Problema | Verificação | Solução |
|---|---|---|
| API Key inválida | Console do navegador | Verifique a chave na plataforma administrativa |
| Dados obrigatórios faltando | Console do navegador | Preencha name ou customer_id |
| Quarentena ativa | Cookies do navegador | Limpe cookies ou reduza waitDelayAfterRating para testes |
| Elemento target não existe | Inspetor do DOM | Verifique se o ID do target existe antes de chamar o widget |
| Script não carregado | Aba Network | Confirme que widget.js foi carregado com sucesso |
Problemas de CSS e posicionamento
| Problema | Causa provável | Solução |
|---|---|---|
| Widget cortado | Container com overflow: hidden | Remova overflow: hidden do container pai |
| Widget atrás de outros elementos | z-index baixo | Ajuste o z-index via CSS personalizado na plataforma |
| Widget não responsivo | Largura fixa | Não defina width ou use valores percentuais |
| Scroll travado após fechar | lockScroll ativo | Desative lockScroll na plataforma se necessário |
Debugging de callbacks
Exemplos de Código Completos
Exemplo Básico
Exemplo Avançado com Todos os Parâmetros
Exemplo com Callbacks e Analytics
Referências Técnicas
SDKs Disponíveis
| SDK | Tecnologia | Pacote |
|---|---|---|
| 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 do Script
Suporte
Para dúvidas ou problemas com a integração do widget, entre em contato com o suporte da SoluCX através da plataforma administrativa ou pelo email de suporte.