React Native SoluCX Widget

Um widget React Native modular para coleta de feedback e pesquisas de satisfação, desenvolvido pela SoluCX seguindo princípios de Clean Code e arquitetura escalável.

🛠️ Tecnologias

📋 Visão Geral

O SoluCX Widget permite integrar pesquisas de satisfação diretamente em aplicações React Native/Expo de forma simples e flexível. Desenvolvido para empresas que precisam coletar feedback em tempo real através de diferentes modalidades de apresentação.

🎯 Principais Características

  • 4 Modos de Renderização: Bottom, Top, Modal e Inline
  • Persistência Automática: Controle inteligente de frequência
  • Comunicação WebView: Integração transparente com plataforma SoluCX
  • TypeScript: Totalmente tipado para melhor experiência de desenvolvimento
  • Performático: Carregamento otimizado e cache local

🚀 Instalação

npm
pnpm
bun
yarn
npm i @solucx/react-native-solucx-widget

🎛️ Uso Básico

🎛️ Uso Básico
app.tsx
import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
import { StyleSheet, Text, View } from 'react-native';

export default function App() {
  return (
    <View style={styles.container}>
      <Text>Open up App.js to start working on your app!</Text>
      <SoluCXWidget
        soluCXKey=""
        type="inline"
        data={{
          journey: "",
          name: "Cliente",
          email: '[email protected]',
          store_id: '1',
          employee_id: '1',
          amount: 10,
          param_REGIAO: 'SUDESTE'
        }}
        options={{}}
      />
    </View>
  );
}
package.json
{
  "dependencies": {
    "@solucx/react-native-solucx-widget": "^0.1.5"
  }
}

Playground

📱 Modos de Renderização

Bottom (Padrão)

Widget fixo na parte inferior da tela, ideal para feedback não intrusivo.

<SoluCXWidget type="bottom" {...props} />

Top

Widget fixo no topo da tela, perfeito para notificações importantes.

<SoluCXWidget type="top" {...props} />

Modal

Sobreposição centralizada que bloqueia interação com o fundo.

<SoluCXWidget type="modal" {...props} />

Inline

Integrado ao fluxo normal do layout, respeitando a posição no código.

<SoluCXWidget type="inline" {...props} />

🔧 API Completa

Props

PropriedadeTipoObrigatórioDescrição
soluCXKeystring✅Chave de autenticação SoluCX
typeWidgetType✅Modo de renderização
dataWidgetData✅Dados do cliente/transação
optionsWidgetOptions✅Configurações do widget

WidgetData

interface WidgetData {
  // Identificadores
  transaction_id?: string;
  customer_id?: string;
  
  // Dados do cliente
  name?: string;
  email?: string;
  phone?: string;
  birth_date?: string;     // Formato: YYYY-MM-DD
  document?: string;
  
  // Contexto da transação
  store_id?: string;
  store_name?: string;
  employee_id?: string;
  employee_name?: string;
  amount?: number;
  score?: number;
  journey?: string;        // Nome da jornada/fluxo
  
  // Parâmetros customizados (prefixo param_)
  param_REGIAO?: string;
  [key: string]: string | number | undefined;
}

WidgetOptions

interface WidgetOptions {
  height?: number;         // Altura
  retry?: {
    attempts?: number;     // Tentativas (padrão: 3)
    interval?: number;     // Intervalo em ms (padrão: 1000)
  };
  waitDelayAfterRating?: number; // Delay após avaliação
}

WidgetType

type WidgetType = "bottom" | "top" | "inline" | "modal";

🔄 Sistema de Eventos

O widget processa automaticamente os seguintes eventos da pesquisa:

  • FORM_OPENED - Widget foi aberto
  • FORM_CLOSE - Usuário fechou o widget
  • FORM_COMPLETED - Pesquisa concluída
  • FORM_PARTIALCOMPLETED - Completada parcialmente
  • FORM_RESIZE - Widget redimensionado
  • FORM_ERROR - Erro no carregamento

💾 Persistência Inteligente

O widget controla automaticamente:

  • Histórico de tentativas: Evita spam de widgets
  • Última avaliação: Data da última interação
  • Controle de frequência: Respeita configurações de exibição
  • Armazenamento local: Dados persistem entre sessões

⚙️ Múltiplos Widgets

const widgets = ['bottom', 'top'] as WidgetType[];

return (
  <>
    {widgets.map((type) => (
      <SoluCXWidget
        key={type}
        soluCXKey={key}
        type={type}
        data={data}
        options={options}
      />
    ))}
  </>
);

🚨 Considerações Importantes

Posicionamento

⚠️ Comportamento Crítico: A posição no JSX não determina onde widgets top, bottom e modal aparecem:

// ❌ Widget "bottom" sempre aparece embaixo, independente da posição
<Text>Conteúdo antes</Text>
<SoluCXWidget type="bottom" {...props} />
<Text>Conteúdo depois</Text>

// ✅ Apenas "inline" respeita a posição no código
<Text>Conteúdo antes</Text>
<SoluCXWidget type="inline" {...props} />
<Text>Conteúdo depois</Text>

🔍 Troubleshooting

Widget não aparece

// Verificações essenciais:
// ✅ Chave SoluCX válida?
// ✅ Conectividade com internet?
// ✅ Logs do WebView no console?
// ✅ Dados obrigatórios preenchidos?

Eventos não funcionam

// Debug de comunicação:
const handleMessage = (message: string) => {
  console.log('Widget event:', message);
};

// Verificar se JavaScript foi injetado corretamente

Layout quebrado

// Ajustar dimensões para o dispositivo:
const { height } = Dimensions.get('window');

const options = {
  height: Math.min(height * 0.6, 400)
};

📚 Compatibilidade

VersãoReact NativeExpoiOSAndroid
1.0.x0.70+50+11+API 21+

📄 Licença

Este pacote é proprietário da SoluCX. O uso é restrito a clientes licenciados da plataforma SoluCX.

Flutter
Pacote Flutter para integração com o SoluCX Widget
Web Component
Um componente de widget de pesquisa personalizável construído com Vue.js que pode ser integrado a vários frameworks web.