@solucx/react-native-solucx-widget

@solucx/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 install @solucx/react-native-solucx-widget

🎛️ Uso Básico

import React from 'react';
import { SoluCXWidget } from '@solucx/react-native-solucx-widget';

export default function MyScreen() {
  return (
    <SoluCXWidget
      soluCXKey="sua-chave-solucx"
      type="bottom"
      data={{
        journey: "checkout_flow",
        name: "João Silva",
        email: "[e-mail]",
        store_id: "loja_01",
        amount: 150.00
      }}
      options={{ 
        width: 380, 
        height: 400 
      }}
    />
  );
}

📱 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

Propriedade	Tipo	Obrigatório	Descrição
soluCXKey	string	✅	Chave de autenticação SoluCX
type	WidgetType	✅	Modo de renderização
data	WidgetData	✅	Dados do cliente/transação
options	WidgetOptions	✅	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 {
  width?: number;          // Largura (padrão: 380)
  height?: number;         // Altura (padrão: 400)
  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 { width, height } = Dimensions.get('window');

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

📚 Compatibilidade

Versão	React Native	Expo	iOS	Android
1.0.x	0.70+	50+	11+	API 21+

📄 Licença

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