@solucx/react-native-solucx-widget 0.2.5 → 2.0.7

package/README.md

@@ -1,285 +1,629 @@
 # @solucx/react-native-solucx-widget
 
-[![npm version](https://badge.fury.io/js/@solucx%2Freact-native-solucx-widget.svg)](https://badge.fury.io/js/@solucx%2Freact-native-solucx-widget)
 [![React Native](https://img.shields.io/badge/React%20Native-0.70+-blue.svg)](https://reactnative.dev/)
 [![Expo](https://img.shields.io/badge/Expo-50+-lightgrey.svg)](https://expo.dev/)
 [![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue.svg)](https://www.typescriptlang.org/)
-[![iOS](https://img.shields.io/badge/iOS-11+-lightgrey.svg)](https://developer.apple.com/ios/)
-[![Android](https://img.shields.io/badge/Android-API%2021+-green.svg)](https://developer.android.com/)
-[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
 
-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.
+Widget React Native para coleta de feedback e pesquisas de satisfacao, desenvolvido pela SoluCX.
 
-## 🛠️ Tecnologias
+---
 
-![React Native](https://img.shields.io/badge/React_Native-20232A?style=for-the-badge&logo=react&logoColor=61DAFB)
-![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=for-the-badge&logo=typescript&logoColor=white)
-![WebView](https://img.shields.io/badge/WebView-4285F4?style=for-the-badge&logo=googlechrome&logoColor=white)
-![AsyncStorage](https://img.shields.io/badge/AsyncStorage-FF6B6B?style=for-the-badge&logo=react&logoColor=white)
-![Jest](https://img.shields.io/badge/Jest-C21325?style=for-the-badge&logo=jest&logoColor=white)
+## Instalacao
 
-## 📋 Visão Geral
+```bash
+npm install @solucx/react-native-solucx-widget
+```
 
-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
+## Inicio Rapido
 
-- **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
+Voce pode integrar o widget de duas formas:
 
-## 🚀 Instalação
+- **Por funcao**: monta um `SoluCXWidgetHost` no root e dispara a exibicao com `SoluCXWidget.create(...).show()`.
+- **Por componente**: renderiza `SoluCXWidget` diretamente no JSX, no ponto exato em que o widget deve aparecer.
 
-```bash
-npm install @solucx/react-native-solucx-widget
+### 1. Uso por funcao: adicione o `SoluCXWidgetHost` no root do app
+
+O `SoluCXWidgetHost` deve ser montado **uma unica vez** no componente raiz da aplicacao. Ele e responsavel por renderizar o widget quando solicitado via `SoluCXWidget.create(...).show()`.
+
+```tsx
+// App.tsx
+import { SoluCXWidgetHost } from '@solucx/react-native-solucx-widget';
+
+export default function App() {
+  return (
+    <>
+      <NavigationContainer>
+        <Stack.Navigator>{/* suas telas */}</Stack.Navigator>
+      </NavigationContainer>
+
+      {/* Obrigatorio: monte uma vez no root */}
+      <SoluCXWidgetHost />
+    </>
+  );
+}
 ```
 
-## 🎛️ Uso Básico
+### 2. Uso por funcao: dispare o widget em qualquer tela
+
+Use `SoluCXWidget.create()` para construir e exibir o widget. **As opcoes de supressao (dias de espera) sao opcionais** — se nao forem passadas, o widget as busca automaticamente do painel de configuracao da jornada (configurado remotamente).
 
 ```tsx
-import React from 'react';
+// CheckoutScreen.tsx
 import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
 
-export default function MyScreen() {
+function onCheckoutComplete() {
+  SoluCXWidget
+    .create('SUA_CHAVE_SOLUCX')
+    .setType('modal')
+    .setData({
+      journey: 'pos_venda',
+      user_id: 'user_123',
+      email: 'cliente@email.com',
+      name: 'Joao Silva',
+    })
+    .show();
+}
+```
+
+Pronto! O widget vai buscar as configuracoes de supressao remotamente e decidir se deve exibir ou nao.
+
+### 3. Uso por componente: renderize o widget diretamente no JSX
+
+Quando voce quiser controlar a exibicao pelo proprio componente React, use `SoluCXWidget`. Nesse modo, nao e necessario montar `SoluCXWidgetHost`.
+
+```tsx
+// CheckoutScreen.tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+export function CheckoutScreen() {
   return (
     <SoluCXWidget
-      soluCXKey='sua-chave-solucx'
-      type='bottom'
+      soluCXKey="SUA_CHAVE_SOLUCX"
+      type="inline"
       data={{
-        journey: 'checkout_flow',
-        name: 'João Silva',
-        email: 'joao@email.com',
-        store_id: 'loja_01',
-        amount: 150.0
+        journey: 'pos_venda',
+        user_id: 'user_123',
+        email: 'cliente@email.com',
+        name: 'Joao Silva',
       }}
-      options={{
-        height: 400
+      callbacks={{
+        onOpened: (userId) => {
+          console.log('Widget exibido para:', userId);
+        },
       }}
     />
   );
 }
 ```
 
-## 📱 Modos de Renderização
+---
+
+## Exemplos Completos
 
-### Bottom (Padrão)
+### Exemplo 1: Uso minimo (opcoes configuradas remotamente)
 
-Widget fixo na parte inferior da tela, ideal para feedback não intrusivo.
+Este e o caso de uso mais comum. As regras de supressao (quantos dias esperar apos cada evento) sao configuradas no **painel de configuracao da jornada** e buscadas automaticamente pelo widget. Voce nao precisa passar nenhuma opcao.
 
 ```tsx
-<SoluCXWidget type='bottom' {...props} />
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+// Disparar apos uma compra
+function afterPurchase() {
+  SoluCXWidget
+    .create('SUA_CHAVE_SOLUCX')
+    .setType('bottom')
+    .setData({
+      journey: 'pos_venda',
+      user_id: 'user_123',
+      email: 'cliente@email.com',
+      name: 'Joao Silva',
+      store_id: 'loja_01',
+    })
+    .show();
+  // As opcoes de supressao serao buscadas automaticamente da API
+  // com base na configuracao da jornada "pos_venda"
+}
 ```
 
-### Top
+### Exemplo 2: Com callbacks para monitorar eventos
 
-Widget fixo no topo da tela, perfeito para notificações importantes.
+```tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+function showSurvey() {
+  SoluCXWidget
+    .create('SUA_CHAVE_SOLUCX')
+    .setType('modal')
+    .setData({
+      journey: 'atendimento',
+      user_id: 'user_456',
+      email: 'maria@email.com',
+      name: 'Maria Santos',
+      employee_id: 'atendente_01',
+      employee_name: 'Carlos',
+    })
+    .setCallbacks({
+      onPreOpen: (userId) => {
+        console.log('Preparando widget para:', userId);
+      },
+      onOpened: (userId) => {
+        console.log('Widget exibido para:', userId);
+        analytics.track('survey_shown', { userId });
+      },
+      onBlocked: (reason) => {
+        // Widget nao foi exibido por causa de uma regra de supressao
+        console.log('Widget bloqueado:', reason);
+        // Ex: "BLOCKED_BY_WIDGET_DISMISS_INTERVAL"
+      },
+      onClosed: () => {
+        console.log('Usuario fechou o widget');
+      },
+      onCompleted: (userId) => {
+        console.log('Pesquisa respondida por:', userId);
+        analytics.track('survey_completed', { userId });
+      },
+      onPartialCompleted: (userId) => {
+        console.log('Pesquisa parcialmente respondida por:', userId);
+      },
+      onError: (message) => {
+        console.error('Erro no widget:', message);
+      },
+    })
+    .show();
+}
+```
+
+### Exemplo 3: Com opcoes locais (sobrescrevendo configuracao remota)
+
+Se voce precisar sobrescrever as configuracoes da jornada para um caso especifico, passe as opcoes diretamente. Quando `setOptions()` e chamado, o widget **nao busca configuracoes da API** e usa os valores fornecidos.
 
 ```tsx
-<SoluCXWidget type='top' {...props} />
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+function showUrgentSurvey() {
+  SoluCXWidget
+    .create('SUA_CHAVE_SOLUCX')
+    .setType('modal')
+    .setData({
+      journey: 'nps_trimestral',
+      user_id: 'user_789',
+      email: 'pedro@email.com',
+    })
+    .setOptions({
+      height: 600,
+      maxAttemptsAfterDismiss: 5,        // Máximo de 5 tentativas para essa jornada
+      waitDaysAfterWidgetDismiss: 90,    // Esperar 90 dias após o usuário fechar
+      waitDaysAfterWidgetSubmit: 30,     // Esperar 30 dias após resposta completa
+      waitDaysAfterWidgetDisplay: 7,     // Esperar 7 dias após qualquer exibição
+    })
+    .setCallbacks({
+      onOpened: (userId) => console.log('Abriu:', userId),
+      onCompleted: (userId) => console.log('Respondeu:', userId),
+    })
+    .show();
+}
 ```
 
-### Modal
+### Exemplo 4: Diferentes tipos de widget
+
+```tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+const data = {
+  journey: 'pos_venda',
+  user_id: 'user_123',
+  email: 'cliente@email.com',
+};
+
+// Bottom: barra fixa na parte inferior (padrao)
+SoluCXWidget.create('KEY').setType('bottom').setData(data).show();
+
+// Top: barra fixa no topo
+SoluCXWidget.create('KEY').setType('top').setData(data).show();
+
+// Modal: sobreposicao centralizada que bloqueia o fundo
+SoluCXWidget.create('KEY').setType('modal').setData(data).show();
+
+// Inline: integrado ao fluxo do layout (respeita a posicao no JSX)
+SoluCXWidget.create('KEY').setType('inline').setData(data).show();
+```
 
-Sobreposição centralizada que bloqueia interação com o fundo.
+### Exemplo 5: Fechar o widget programaticamente
 
 ```tsx
-<SoluCXWidget type='modal' {...props} />
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+// Fechar o widget a qualquer momento
+function handleTimeout() {
+  SoluCXWidget.dismiss();
+}
 ```
 
-### Inline
+### Exemplo 6: Consultar logs de supressao
 
-Integrado ao fluxo normal do layout, respeitando a posição no código.
+Os metodos de log sao **metodos de instancia** — usam os dados do builder (`instanceKey` do `create()`, `journey` e `userId` do `setData()`) para identificar automaticamente qual registro acessar. Nao e necessario passar esses parametros novamente.
 
 ```tsx
-<SoluCXWidget type='inline' {...props} />
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+// Cria a instancia com os dados que identificam o registro
+const widget = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda', user_id: 'user_123' });
+
+// Consultar os logs de supressao
+const logs = await widget.getWidgetLogs();
+console.log(logs);
+// {
+//   attempts: 3,                       // quantas vezes o widget foi exibido nesta experiencia
+//   answeredTransactionIds: ['txn-1'], // transacoes que ja responderam e nao devem reabrir o widget
+//   lastExperienceId: 'pos_venda',     // ultima jornada associada ao contador
+//   lastDisplayAttempt: 1741000000000, // ultima tentativa de exibicao bloqueada
+//   lastFirstAccess: 1740000000000,    // primeira vez que o widget foi exibido
+//   lastDisplay: 1741000000000,        // ultima exibicao do widget
+//   lastDismiss: 1741000000000,        // ultima vez que o usuario fechou
+//   lastSubmit: 0,                     // ultimo envio completo
+//   lastPartialSubmit: 0,              // ultimo envio parcial
+// }
 ```
 
-## 🔧 API Completa
+### Exemplo 7: Sobrescrever datas de eventos (debug/teste)
 
-### Props
+Use `overrideTimestamp` para simular cenarios de teste sem esperar os dias reais.
 
-| 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      |
+```tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
 
-### WidgetData
+const widget = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda', user_id: 'user_123' });
 
-```typescript
-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;
-}
-```
+// Informar primeiro acesso do usuário 
+await widget.overrideTimestamp('lastFirstAccess', new Date('2026-01-01T00:00:00Z'));
 
-### WidgetOptions
+// Ou usar timestamp em milissegundos diretamente
+await widget.overrideTimestamp('lastFirstAccess', 1700000000000);
 
-```typescript
-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
-}
+// Resetar um campo para "nunca aconteceu" (valor 0)
+await widget.overrideTimestamp('lastSubmit', 0);
+
+// Depois de sobrescrever, pode exibir o widget normalmente
+widget.show();
 ```
 
-**Comportamento da Altura (height):**
+**Campos disponiveis para `overrideTimestamp`:**
 
-- **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`.
+| Campo | Descricao |
+|---|---|
+| `lastDisplayAttempt` | Ultima tentativa de exibicao (widget foi bloqueado) |
+| `lastFirstAccess` | Primeira vez que o widget foi exibido para o usuario |
+| `lastDisplay` | Ultima exibicao do widget |
+| `lastDismiss` | Ultima vez que o usuario fechou o widget |
+| `lastSubmit` | Ultimo envio completo da pesquisa |
+| `lastPartialSubmit` | Ultimo envio parcial da pesquisa |
+| `answeredTransactionIds` | Lista de `transaction_id` que ja responderam e devem ser bloqueados localmente |
 
-  ```tsx
-  // Altura dinâmica - se adapta ao conteúdo
-  <SoluCXWidget
-    type='bottom'
-    options={{}} // ou options={{ retry: { attempts: 3 } }}
-    {...props}
-  />
-  ```
+### Exemplo 8: Limpar logs de supressao
 
-- **Altura Fixa**: Quando `height` é especificado, o valor é fixo e eventos de resize são ignorados. Funciona para todos os tipos de widget.
+```tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
 
-  ```tsx
-  // Altura fixa de 400 pontos
-  <SoluCXWidget type='modal' options={{ height: 400 }} {...props} />
-  ```
+const widget = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda', user_id: 'user_123' });
 
-**⚠️ 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.
+// Limpar TODOS os logs (reseta contadores e timestamps)
+await widget.clearWidgetLogs();
 
-### WidgetType
+// Apos limpar, o widget vai se comportar como se nunca tivesse sido exibido
+widget.show();
+```
 
-```typescript
-type WidgetType = 'bottom' | 'top' | 'inline' | 'modal';
+### Exemplo 9: Forcar exibicao do widget (ignorar bloqueio)
+
+Se o widget esta sendo bloqueado por uma regra de supressao e voce quer forca-lo a exibir (por exemplo, para testes), sobrescreva a data do evento que esta bloqueando:
+
+```tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+const widget = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda', user_id: 'user_123' });
+
+// Verificar qual evento esta bloqueando
+const logs = await widget.getWidgetLogs();
+console.log('Ultimo dismiss:', new Date(logs.lastDismiss));
+console.log('Tentativas:', logs.attempts);
+
+// Resetar o dismiss para desbloquear
+await widget.overrideTimestamp('lastDismiss', 0);
+
+// Agora o widget vai exibir (se nao houver outra regra bloqueando)
+widget.show();
 ```
 
-## 🔄 Sistema de Eventos
+### Exemplo 10: Isolamento por jornada — dois widgets independentes
 
-O widget processa automaticamente os seguintes eventos da pesquisa:
+Cada combinacao de `instanceKey + journey + userId` tem seus proprios logs. Widgets de jornadas diferentes nao interferem entre si.
 
-- `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
+```tsx
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
 
-## 💾 Persistência Inteligente
+// Widget da jornada "pos_venda"
+const widgetPosVenda = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda', user_id: 'user_123' });
 
-O widget controla automaticamente:
+// Widget da jornada "atendimento"
+const widgetAtendimento = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'atendimento', user_id: 'user_123' });
 
-- **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
+// Os logs sao independentes:
+const logsPosVenda = await widgetPosVenda.getWidgetLogs();
+const logsAtendimento = await widgetAtendimento.getWidgetLogs();
+// logsPosVenda pode ter 5 tentativas enquanto logsAtendimento tem 0
+
+// Limpar os logs de uma jornada NAO afeta a outra
+await widgetPosVenda.clearWidgetLogs();
+// Apenas os logs de pos_venda foram resetados
+```
 
-## ⚙️ Múltiplos Widgets
+### Exemplo 11: Widget sem userId (dispositivo anonimo)
+
+Quando nao ha `user_id`, `email` ou `cpf`, os logs sao compartilhados por todos os usuarios daquela jornada naquele dispositivo.
 
 ```tsx
-const widgets = ['bottom', 'top'] as WidgetType[];
-
-return (
-  <>
-    {widgets.map((type) => (
-      <SoluCXWidget
-        key={type}
-        soluCXKey={key}
-        type={type}
-        data={data}
-        options={options}
-      />
-    ))}
-  </>
-);
+import { SoluCXWidget } from '@solucx/react-native-solucx-widget';
+
+// Sem userId — logs sao por instanceKey:journey (compartilhado no dispositivo)
+const widget = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda' });
+
+const logs = await widget.getWidgetLogs();
+// Chave de armazenamento: "SUA_CHAVE_SOLUCX:pos_venda"
+
+// Com userId — logs sao por instanceKey:journey:userId (isolado por usuario)
+const widgetComUser = SoluCXWidget
+  .create('SUA_CHAVE_SOLUCX')
+  .setData({ journey: 'pos_venda', user_id: 'user_123' });
+
+const logsComUser = await widgetComUser.getWidgetLogs();
+// Chave de armazenamento: "SUA_CHAVE_SOLUCX:pos_venda:user_123"
 ```
 
-## 🚨 Considerações Importantes
+---
+
+## Opcoes de Supressao (waitDays)
+
+> **Importante:** Voce **nao precisa passar essas opcoes no codigo**. Elas podem (e devem) ser configuradas remotamente no painel de configuracao da jornada. O widget busca automaticamente as configuracoes da API quando `setOptions()` nao e chamado.
+
+As opcoes controlam quantos dias o widget deve esperar apos cada tipo de evento antes de exibir novamente:
+
+| Opcao | Descricao |
+|---|---|
+| `enabled` | Habilita/desabilita o widget. Quando `false`, bloqueia imediatamente sem validar outras regras |
+| `samplingPercentage` | Porcentagem de usuarios que verao o widget (0-100). Valor 100 ou undefined = sem amostragem |
+| `maxAttemptsAfterDismiss` | Numero maximo de tentativas de exibicao por experiencia |
+| `waitDaysAfterWidgetDisplayAttempt` | Dias apos uma tentativa de exibicao bloqueada |
+| `waitDaysAfterWidgetFirstAccess` | Dias apos o primeiro acesso do usuario a jornada |
+| `waitDaysAfterWidgetDisplay` | Dias apos qualquer exibicao do widget |
+| `waitDaysAfterWidgetDismiss` | Dias apos o usuario fechar o widget |
+| `waitDaysAfterWidgetSubmit` | Dias apos o usuario responder a pesquisa |
+| `waitDaysAfterWidgetPartialSubmit` | Dias apos o usuario responder parcialmente |
+
+**Regras:**
+- `enabled: false` bloqueia o widget **imediatamente** com `BLOCKED_BY_DISABLED`, sem verificar nenhuma outra regra
+- `enabled: true` ou `undefined` = widget habilitado (comportamento padrao)
+- `samplingPercentage`: sorteia se o usuario vera o widget. Ex: `50` = 50% de chance. Valor `100` ou `undefined` = todos veem. Valor `0` = ninguem ve
+- Valor `0` ou `undefined` nos campos de dias = sem restricao (o campo nao bloqueia)
+- Se **qualquer** regra bloquear, o widget nao exibe e chama `onBlocked(reason)`
+- Quando bloqueado, o `reason` indica qual regra bloqueou (ex: `"BLOCKED_BY_WIDGET_DISMISS_INTERVAL"`)
+- `maxAttemptsAfterDismiss` conta quantas vezes o widget foi exibido para aquela experiencia (jornada). Se o ID da experiencia (`journey` ou `form_id`) mudar, o contador de tentativas e resetado automaticamente
+- Quando o usuario engaja na pesquisa (`QUESTION_ANSWERED`, envio completo ou envio parcial), o contador de tentativas tambem e resetado para nao bloquear exibicoes futuras por tentativas antigas
+- Quando existe `transaction_id` e essa transacao ja foi concluida ou parcialmente concluida antes, o widget bloqueia localmente e nao faz chamadas de opcoes nem de preflight
+
+---
+
+## API Completa
+
+### `SoluCXWidget` (classe principal)
+
+#### Metodos de construcao (builder pattern)
+
+| Metodo | Descricao |
+|---|---|
+| `SoluCXWidget.create(soluCXKey)` | Cria uma nova instancia do widget |
+| `.setType(type)` | Define o tipo: `'bottom'`, `'top'`, `'modal'`, `'inline'` |
+| `.setData(data)` | Define os dados do usuario/transacao |
+| `.setOptions(options)` | Define opcoes locais (**opcional** - se nao chamar, busca da API) |
+| `.setCallbacks(callbacks)` | Define callbacks de eventos |
+| `.show()` | Exibe o widget |
+
+#### Metodos estaticos
+
+| Metodo | Descricao |
+|---|---|
+| `SoluCXWidget.dismiss()` | Fecha o widget programaticamente |
 
-### Posicionamento
+#### Metodos de instancia (log management)
 
-⚠️ **Comportamento Crítico**: A posição no JSX **não determina** onde widgets `top`, `bottom` e `modal` aparecem:
+Usam os dados do builder (instanceKey, journey, userId) para acessar os logs da combinacao correta.
+
+| Metodo | Descricao |
+|---|---|
+| `.getWidgetLogs()` | Retorna os logs de supressao |
+| `.overrideTimestamp(field, date)` | Sobrescreve uma data de evento (debug/teste) |
+| `.clearWidgetLogs()` | Limpa todos os logs |
+
+> **Isolamento de armazenamento:** Os logs sao isolados por `instanceKey:journey:userId`. Um app com 2 widgets de jornadas diferentes tera dados de supressao independentes. O `userId` e opcional — quando presente, os logs sao por usuario.
+
+### `SoluCXWidgetHost` (componente React)
+
+Componente que deve ser montado **uma vez** no root do app quando a integracao for feita por funcao com `SoluCXWidget.create(...).show()`. Nao e necessario ao usar `SoluCXWidgetView` diretamente.
 
 ```tsx
-// ❌ 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>
+import { SoluCXWidgetHost } from '@solucx/react-native-solucx-widget';
+
+// No root do app
+<SoluCXWidgetHost />
 ```
 
-## 🔍 Troubleshooting
+### `SoluCXWidgetView` (componente React)
 
-### Widget não aparece
+Componente para uso direto no JSX. Pode ser usado no lugar do fluxo por funcao quando fizer mais sentido controlar a renderizacao pelo componente.
 
-```typescript
-// Verificações essenciais:
-// ✅ Chave SoluCX válida?
-// ✅ Conectividade com internet?
-// ✅ Logs do WebView no console?
-// ✅ Dados obrigatórios preenchidos?
+```tsx
+import { SoluCXWidgetView } from '@solucx/react-native-solucx-widget';
+
+<SoluCXWidgetView
+  soluCXKey="SUA_CHAVE_SOLUCX"
+  type="inline"
+  data={{ journey: 'pos_venda', user_id: 'user_123' }}
+/>
 ```
 
-### Eventos não funcionam
+**Props:**
+
+| Prop | Descricao |
+|---|---|
+| `soluCXKey` | Chave de instancia do widget |
+| `type` | Tipo do widget: `'bottom'`, `'top'`, `'modal'`, `'inline'` |
+| `data` | Dados do usuario/transacao |
+| `options` | Opcoes locais de configuracao e supressao |
+| `callbacks` | Callbacks de ciclo de vida e eventos |
+
+### WidgetData
 
 ```typescript
-// Debug de comunicação:
-const handleMessage = (message: string) => {
-  console.log('Widget event:', message);
-};
+interface WidgetData {
+  journey?: string;          // Nome da jornada (obrigatorio na pratica)
+  user_id?: string;          // ID do usuario
+  email?: string;            // Email do usuario
+  name?: string;             // Nome do usuario
+  cpf?: string;              // CPF
+  document?: string;         // Documento
+  phone?: string;            // Telefone
+  phone2?: string;           // Telefone secundario
+  birth_date?: string;       // Data de nascimento (YYYY-MM-DD)
+  transaction_id?: string;   // ID da transacao
+  customer_id?: string;      // ID do cliente
+  store_id?: string;         // ID da loja
+  store_name?: string;       // Nome da loja
+  employee_id?: string;      // ID do funcionario
+  employee_name?: string;    // Nome do funcionario
+  amount?: number;           // Valor da transacao
+  score?: number;            // Score
+  [key: `param_${string}`]: string | number | undefined;  // Parametros customizados
+}
+```
+
+### WidgetCallbacks
 
-// Verificar se JavaScript foi injetado corretamente
+```typescript
+interface WidgetCallbacks {
+  onPreOpen?: (userId: string) => void;        // Antes de abrir
+  onOpened?: (userId: string) => void;         // Widget aberto
+  onBlocked?: (reason: BlockReason) => void;   // Widget bloqueado por regra de supressao
+  onClosed?: () => void;                       // Usuario fechou
+  onCompleted?: (userId: string) => void;      // Pesquisa respondida
+  onPartialCompleted?: (userId: string) => void; // Pesquisa parcialmente respondida
+  onError?: (message: string) => void;         // Erro no widget
+  onPageChanged?: (page: string) => void;      // Pagina mudou
+  onQuestionAnswered?: () => void;             // Pergunta respondida
+  onResize?: (height: string) => void;         // Widget redimensionou
+}
 ```
 
-### Layout quebrado
+### WidgetOptions
 
 ```typescript
-// Ajustar dimensões para o dispositivo:
-const { height } = Dimensions.get('window');
+interface WidgetOptions {
+  enabled?: boolean;  // Habilita/desabilita o widget (default: true). Quando false, bloqueia sem validar.
+  samplingPercentage?: number;  // Porcentagem de usuarios que verao o widget (0-100). Default: 100 (todos).
+  height?: number;  // Altura fixa em pontos (se nao informado, altura dinamica)
+  maxAttemptsAfterDismiss?: number;  // Maximo de tentativas por experiencia (0 ou undefined = sem limite)
+  // Regras de supressao (opcionais - configuradas remotamente pelo painel da jornada):
+  waitDaysAfterWidgetDisplayAttempt?: number;
+  waitDaysAfterWidgetFirstAccess?: number;
+  waitDaysAfterWidgetDisplay?: number;
+  waitDaysAfterWidgetDismiss?: number;
+  waitDaysAfterWidgetSubmit?: number;
+  waitDaysAfterWidgetPartialSubmit?: number;
+}
+```
 
-const options = {
-  height: Math.min(height * 0.6, 400)
-};
+### BlockReason
+
+Valores possiveis retornados no callback `onBlocked`:
+
+| Valor | Significado |
+|---|---|
+| `BLOCKED_BY_DISABLED` | Widget desabilitado (enabled: false) |
+| `BLOCKED_BY_SAMPLING` | Usuario nao foi selecionado pela amostragem (samplingPercentage) |
+| `BLOCKED_BY_MAX_ATTEMPTS` | Numero maximo de tentativas atingido para esta experiencia |
+| `BLOCKED_BY_WIDGET_DISPLAY_ATTEMPT_INTERVAL` | Dentro do intervalo apos tentativa de exibicao |
+| `BLOCKED_BY_WIDGET_FIRST_ACCESS_INTERVAL` | Dentro do intervalo apos primeira visualizacao |
+| `BLOCKED_BY_WIDGET_DISPLAY_INTERVAL` | Dentro do intervalo apos exibicao |
+| `BLOCKED_BY_WIDGET_DISMISS_INTERVAL` | Dentro do intervalo apos fechamento |
+| `BLOCKED_BY_WIDGET_SUBMIT_INTERVAL` | Dentro do intervalo apos envio completo |
+| `BLOCKED_BY_WIDGET_PARTIAL_SUBMIT_INTERVAL` | Dentro do intervalo apos envio parcial |
+
+---
+
+## Fluxo Interno
+
+```
+App chama SoluCXWidget.create('KEY').setData({...}).show()
+  |
+  v
+SoluCXWidgetHost recebe a configuracao
+  |
+  v
+Widget monta e executa bootstrap():
+  |
+  +-- Se setOptions() FOI chamado --> usa opcoes locais
+  +-- Se setOptions() NAO foi chamado --> busca opcoes da API (painel da jornada)
+  |
+  +-- shouldDisplayWidget() verifica enabled + maxAttemptsAfterDismiss + 6 regras de supressao
+  +-- (validacao LOCAL, antes de chamar a API, para reduzir carga no servidor):
+  |     +-- Se transaction_id ja respondido --> onBlocked('BLOCKED_BY_TRANSACTION_ALREADY_ANSWERED'), widget NAO exibe
+  |     +-- Se enabled === false --> onBlocked('BLOCKED_BY_DISABLED'), widget NAO exibe
+  |     +-- Sorteia baseado em samplingPercentage --> se nao selecionado, onBlocked('BLOCKED_BY_SAMPLING')
+  |     +-- Se experiencia mudou --> reseta contador de tentativas
+  |     +-- Se tentativas >= maxAttemptsAfterDismiss --> onBlocked('BLOCKED_BY_MAX_ATTEMPTS')
+  |     +-- Para cada regra: timestamp do evento + dias de espera > agora?
+  |     +-- Se QUALQUER regra bloqueia --> onBlocked(reason), widget NAO exibe
+  |     +-- Se NENHUMA bloqueia --> continua
+  |
+  +-- Busca URL do formulario na API (preflight)
+  |
+  +-- Se EXIBE:
+  |     +-- Incrementa contador de tentativas
+  |     +-- Salva lastDisplay (e lastFirstAccess na primeira vez)
+  |     +-- Renderiza WebView com o formulario
+  |     +-- onOpened(userId)
+  |
+  +-- Eventos do usuario:
+        +-- Fecha widget --> salva lastDismiss, onClosed()
+      +-- Responde pergunta --> zera contador de tentativas, onQuestionAnswered()
+    +-- Responde pesquisa --> zera contador de tentativas, salva transaction_id respondido, salva lastSubmit, onCompleted(userId)
+    +-- Resposta parcial --> zera contador de tentativas, salva transaction_id respondido, salva lastPartialSubmit, onPartialCompleted(userId)
 ```
 
-## 📚 Compatibilidade
+---
+
+## Compatibilidade
 
-| Versão | React Native | Expo | iOS | Android |
-| ------ | ------------ | ---- | --- | ------- |
-| 1.0.x  | 0.70+        | 50+  | 11+ | API 21+ |
+| Versao | React Native | Expo | iOS | Android |
+|---|---|---|---|---|
+| 1.0.x | 0.70+ | 50+ | 11+ | API 21+ |
 
-## 📄 Licença
+## Licenca
 
-Este pacote é proprietário da SoluCX. O uso é restrito a clientes licenciados da plataforma SoluCX.
+Proprietario - SoluCX. Uso restrito a clientes licenciados.
 
 ---