@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.0
      }}
      options={{
        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 {
  height?: number; // Altura fixa em pontos (points, não pixels)
  // Se não fornecido, será dinâmica baseada em eventos de resize
  // Se fornecido, será fixa independente do tipo de widget
  retry?: {
    attempts?: number; // Tentativas (padrão: 3)
    interval?: number; // Intervalo em ms (padrão: 1000)
  };
  waitDelayAfterRating?: number; // Delay após avaliação
}

Comportamento da Altura (height):

• Altura Dinâmica (padrão): Quando height não é fornecido, o widget se ajusta automaticamente baseado em eventos de resize do conteúdo. Isso funciona para todos os tipos: bottom, top, inline e modal.

  // Altura dinâmica - se adapta ao conteúdo
  <SoluCXWidget
    type='bottom'
    options={{}} // ou options={{ retry: { attempts: 3 } }}
    {...props}
  />
  

• Altura Fixa: Quando height é especificado, o valor é fixo e eventos de resize são ignorados. Funciona para todos os tipos de widget.

  // Altura fixa de 400 pontos
  <SoluCXWidget type='modal' options={{ height: 400 }} {...props} />
  

⚠️ Importante: O valor de height é sempre em pontos (points), não pixels, seguindo o padrão do React e React Native. O sistema operacional converte automaticamente para pixels considerando a densidade da tela.

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