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 | 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 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 sobre Quarentena: O controle de quarentena do widget é baseado em cookies do navegador do cliente. Isso significa que a quarentena não é 100% garantida, pois o usuário pode limpar os cookies, usar navegadores diferentes, dispositivos diferentes ou modo de navegação anônima/privada. Para cenários que exigem controle rigoroso de quarentena, recomendamos implementar validações adicionais no lado do servidor.
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 |
| 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.