@solucx/react-native-solucx-widget 0.1.15 → 0.2.0

package/README.intern.md

@@ -1,513 +1,513 @@
-# SoluCX Widget
-
-Um widget React Native modular para coleta de feedback e pesquisas, desenvolvido seguindo princípios de Clean Code e arquitetura escalável.
-
-## 📋 Visão Geral
-
-O SoluCX Widget oferece quatro modos de renderização flexíveis para integração em aplicações React Native/Expo:
-
-- **Top**: Widget fixo no topo da tela
-- **Bottom**: Widget fixo na parte inferior
-- **Modal**: Widget em sobreposição centralizada
-- **Inline**: Widget integrado ao fluxo do layout
-
-## 🏗️ Arquitetura
-
-### Componentes Principais
-
-- [`SoluCXWidget.tsx`](src/SoluCXWidget.tsx) - Componente principal
-- [`useWidgetState.ts`](src/hooks/useWidgetState.ts) - Hook para gerenciamento de estado
-- [`useWidgetHeight.ts`](src/hooks/useWidgetHeight.ts) - Hook para gerenciamento de altura (dinâmica/fixa)
-- [`WidgetEventService`](src/services/widgetEventService.ts) - Serviço de eventos
-- [`StorageService`](src/services/storage.ts) - Persistência local
-
-### Estrutura de Arquivos
-
-```
-src/
-├── SoluCXWidget.tsx           # Componente principal
-├── components/                # Componentes especializados
-│   ├── ModalWidget.tsx        # Widget modal
-│   ├── InlineWidget.tsx       # Widget inline
-│   └── OverlayWidget.tsx      # Widget overlay (top/bottom)
-├── hooks/                     # Hooks personalizados
-│   ├── useWidgetState.ts      # Estado do widget
-│   ├── useWidgetHeight.ts     # Gerenciamento de altura (dinâmica/fixa)
-│   └── useHeightAnimation.ts  # Animação de altura
-├── services/                  # Serviços
-│   ├── widgetEventService.ts  # Gerenciamento de eventos
-│   └── storage.ts             # Persistência de dados
-├── interfaces/                # Tipos TypeScript
-│   ├── index.ts               # Exports centralizados
-│   ├── WidgetData.ts          # Dados do widget
-│   ├── WidgetOptions.ts       # Opções de configuração
-│   ├── WidgetResponse.ts      # Respostas e erros
-│   └── WidgetSamplerLog.ts    # Log de tentativas
-├── styles/                    # Estilos
-│   └── widgetStyles.ts        # Estilos por tipo
-├── utils/                     # Utilitários
-│   └── urlUtils.ts            # Construção de URLs
-├── constants/                 # Constantes
-│   └── webViewConstants.ts    # URLs e configurações
-└── __tests__/                 # Testes
-    ├── urlUtils.test.ts
-    └── useWidgetState.test.ts
-```
-
-## 🚀 Instalação e Uso
-
-### Instalação
-
-```bash
-# Como dependência local (monorepo)
-npm install solucx_widget@file:./modules/solucx_widget
-
-# Dependências peer necessárias
-npm install react-native-webview @react-native-async-storage/async-storage
-```
-
-### Uso Básico
-
-```tsx
-import React from 'react';
-import { SoluCXWidget } from 'solucx_widget';
-
-export default function MyComponent() {
-  return (
-    <SoluCXWidget
-      soluCXKey='sua-chave-solucx'
-      type='bottom' // 'top' | 'bottom' | 'modal' | 'inline'
-      data={{
-        journey: 'nome_da_jornada',
-        name: 'Nome do Cliente',
-        email: 'cliente@email.com',
-        phone: '11999999999',
-        store_id: '1',
-        employee_id: '1',
-        amount: 100,
-        param_REGIAO: 'SUDESTE'
-      }}
-      options={{
-        height: 400
-      }}
-    />
-  );
-}
-```
-
-## 🎛️ API do Componente
-
-### Props do SoluCXWidget
-
-```typescript
-interface SoluCXWidgetProps {
-  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
-}
-```
-
-### Tipos de Widget
-
-```typescript
-type WidgetType = 'bottom' | 'top' | 'inline' | 'modal';
-```
-
-### Dados do Widget
-
-```typescript
-interface WidgetData {
-  // Identificadores
-  transaction_id?: string;
-  customer_id?: string;
-
-  // Dados do cliente
-  name?: string;
-  email?: string;
-  phone?: string;
-  birth_date?: string;
-  document?: string;
-
-  // Dados da transação
-  store_id?: string;
-  store_name?: string;
-  employee_id?: string;
-  employee_name?: string;
-  amount?: number;
-  score?: number;
-
-  // Parâmetros customizados
-  journey?: string;
-  [key: string]: string | number | undefined;
-}
-```
-
-### Opções de Configuração
-
-```typescript
-interface WidgetOptions {
-  height?: number; // Altura fixa em pontos (não pixels)
-  // Se não fornecido: altura dinâmica baseada em eventos de resize
-  // Se fornecido: altura fixa para todos os tipos de widget
-  retry?: {
-    // Configuração de retry
-    attempts?: number; // Número de tentativas
-    interval?: number; // Intervalo entre tentativas (ms)
-  };
-  waitDelayAfterRating?: number; // Delay após avaliação (ms)
-}
-```
-
-**⚙️ Gerenciamento de Altura:**
-
-O widget possui dois modos de altura:
-
-1. **Altura Dinâmica (padrão)**: Quando `height` não é fornecido, o widget se ajusta automaticamente através de eventos `FORM_RESIZE` do conteúdo. Funciona para todos os tipos (`bottom`, `top`, `inline`, `modal`).
-
-2. **Altura Fixa**: Quando `height` é especificado, o valor é fixo e eventos de resize são ignorados. Funciona para todos os tipos de widget.
-
-```tsx
-// Altura dinâmica - se adapta ao conteúdo
-<SoluCXWidget
-  type="bottom"
-  options={{}}  // height não especificado
-  {...props}
-/>
-
-// Altura fixa de 400 pontos
-<SoluCXWidget
-  type="modal"
-  options={{ height: 400 }}  // altura fixa
-  {...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 do dispositivo.
-
-## 🔄 Sistema de Eventos
-
-O widget comunica através de mensagens WebView bidirecionais:
-
-### Eventos Suportados
-
-```typescript
-type EventKey =
-  | 'FORM_OPENED' // Widget foi aberto
-  | 'FORM_CLOSE' // Usuário fechou o widget
-  | 'FORM_ERROR' // Erro no carregamento
-  | 'FORM_RESIZE' // Widget redimensionado
-  | 'FORM_PAGECHANGED' // Mudança de página
-  | 'QUESTION_ANSWERED' // Pergunta respondida
-  | 'FORM_COMPLETED' // Formulário concluído
-  | 'FORM_PARTIALCOMPLETED'; // Completado parcialmente
-```
-
-### Tratamento de Eventos
-
-Os eventos são processados automaticamente pelo [`WidgetEventService`](src/services/widgetEventService.ts):
-
-```typescript
-const eventService = new WidgetEventService(
-  setIsWidgetVisible, // Função para controlar visibilidade
-  resize, // Função para redimensionar
-  open // Função para abrir widget
-);
-```
-
-## 💾 Persistência de Dados
-
-O widget utiliza [`AsyncStorage`](@react-native-async-storage/async-storage) para persistir:
-
-- **Histórico de tentativas**: Controla quantas vezes o widget foi exibido
-- **Última avaliação**: Data da última interação
-- **Controle de frequência**: Evita spam de widgets
-
-### Estrutura dos Dados
-
-```typescript
-interface WidgetSamplerLog {
-  attempts: number; // Número de tentativas
-  lastAttempt: number; // Timestamp da última tentativa
-  lastRating: number; // Timestamp da última avaliação
-  lastParcial: number; // Timestamp do último parcial
-}
-```
-
-## 🎨 Customização de Estilos
-
-### Estilos por Tipo
-
-Cada tipo de widget possui estilos específicos definidos em [`widgetStyles.ts`](src/styles/widgetStyles.ts):
-
-```typescript
-export const getWidgetStyles = (type: WidgetType) => {
-  const styleMap = {
-    bottom: { container: styles.wrapper, content: styles.bottom },
-    top: { container: styles.wrapper, content: styles.top },
-    inline: { container: styles.inlineWrapper, content: styles.inline },
-    modal: { container: styles.wrapper, content: styles.inline }
-  };
-
-  return styleMap[type] || styleMap.bottom;
-};
-```
-
-### Características Visuais
-
-- **Bottom/Top**: Position absolute com z-index elevado
-- **Modal**: Overlay com background semitransparente
-- **Inline**: Integrado ao fluxo normal do layout
-
-## 🔧 Utilitários
-
-### Construção de URLs
-
-O [`urlUtils.ts`](src/utils/urlUtils.ts) gerencia a construção de URLs da pesquisa:
-
-```typescript
-export function buildWidgetURL(key: string, data: WidgetData): string {
-  const params = new URLSearchParams(data as Record<string, string>);
-  const baseURL = `${BASE_URL}/${key}/?mode=widget`;
-
-  if (data.transaction_id) {
-    return `${baseURL}&${params.toString()}`;
-  }
-
-  return `${baseURL}&transaction_id=&${params.toString()}`;
-}
-```
-
-## 🧪 Testes
-
-### Executando Testes
-
-```bash
-# Todos os testes
-npm test
-
-# Teste específico
-npm test -- urlUtils.test.ts
-npm test -- useWidgetState.test.ts
-```
-
-### Cobertura de Testes
-
-- ✅ Construção de URLs
-- ✅ Gerenciamento de eventos
-- ✅ Estados do widget
-- ✅ Persistência de dados
-
-## ⚙️ Configuração
-
-### Constantes
-
-Configurações centralizadas em [`webViewConstants.ts`](src/constants/webViewConstants.ts):
-
-```typescript
-export const BASE_URL = 'https://survey-link.solucx.com.br/link';
-export const STORAGE_KEY = '@solucxWidgetLog';
-export const MIN_HEIGHT = 200;
-export const FIXED_Z_INDEX = 9999;
-export const MODAL_Z_INDEX = 10000;
-```
-
-### JavaScript Injection
-
-Listener para comunicação WebView:
-
-```typescript
-export const WEB_VIEW_MESSAGE_LISTENER = `
-  window.addEventListener('message', function(event) {
-    window.ReactNativeWebView.postMessage(event.data);
-  });
-`;
-```
-
-## 🚨 Considerações Importantes
-
-### 1. **Comportamento de Posicionamento**
-
-⚠️ **Ponto Crítico**: A posição no JSX **não determina** onde widgets `top`, `bottom` e `modal` aparecem:
-
-```tsx
-// ❌ Isso NÃO faz o widget aparecer no meio
-<Text>Conteúdo antes</Text>
-<SoluCXWidget type="bottom" {...props} /> {/* Sempre aparece embaixo */}
-<Text>Conteúdo depois</Text>
-
-// ✅ Apenas o tipo "inline" respeita a posição no código
-<Text>Conteúdo antes</Text>
-<SoluCXWidget type="inline" {...props} /> {/* Aparece aqui */}
-<Text>Conteúdo depois</Text>
-```
-
-### 2. **Performance**
-
-- Widget usa WebView interna (overhead de performance)
-- Carregamento lazy das pesquisas
-- Cache automático via AsyncStorage
-- JavaScript injection para comunicação
-
-### 3. **Segurança**
-
-- **Chaves API**: Nunca hardcode em produção
-- **Dados sensíveis**: Não são logados automaticamente
-- **URLs**: Validadas antes do carregamento
-- **HTTPS**: Obrigatório para comunicação
-
-### 4. **Limitações Técnicas**
-
-- Requer conexão com internet
-- Dependente do WebView do sistema
-- Eventos assíncronos (não bloqueantes)
-- Storage limitado do dispositivo
-
-## 📝 Desenvolvimento
-
-### Adicionando Novos Tipos
-
-1. **Estenda o tipo WidgetType**:
-
-```typescript
-// modules/solucx_widget/src/interfaces/index.ts
-export type WidgetType = 'bottom' | 'top' | 'inline' | 'modal' | 'novo_tipo';
-```
-
-2. **Adicione estilos correspondentes**:
-
-```typescript
-// modules/solucx_widget/src/styles/widgetStyles.ts
-const styleMap = {
-  // ... estilos existentes
-  novo_tipo: { container: styles.novoWrapper, content: styles.novoContent }
-};
-```
-
-3. **Implemente lógica no componente principal**:
-
-```typescript
-// modules/solucx_widget/src/SoluCXWidget.tsx
-if (type === 'novo_tipo') {
-  return <NovoTipoWidget>{/* ... */}</NovoTipoWidget>;
-}
-```
-
-### Adicionando Novos Eventos
-
-1. **Estenda EventKey**:
-
-```typescript
-// modules/solucx_widget/src/interfaces/index.ts
-export type EventKey = 'FORM_OPENED' | 'NOVO_EVENTO'; // Novo evento
-```
-
-2. **Implemente handler**:
-
-```typescript
-// modules/solucx_widget/src/services/widgetEventService.ts
-private executeEvent(eventKey: EventKey, value: string): WidgetResponse {
-  const eventHandlers = {
-    // ... handlers existentes
-    NOVO_EVENTO: (value: string) => this.handleNovoEvento(value),
-  };
-}
-```
-
-3. **Adicione testes**:
-
-```typescript
-// modules/solucx_widget/src/__tests__/widgetEventService.test.ts
-it('should handle NOVO_EVENTO correctly', () => {
-  const result = service.handleMessage('NOVO_EVENTO-data', true);
-  expect(result).toEqual({ status: 'success' });
-});
-```
-
-## 🔍 Troubleshooting
-
-### Problemas Comuns
-
-#### 1. **Widget não aparece**
-
-```bash
-# Verificações:
-✅ Chave SoluCX válida?
-✅ Conectividade com internet?
-✅ Logs do WebView no console?
-✅ Evento FORM_OPENED sendo disparado?
-```
-
-#### 2. **Eventos não funcionam**
-
-```bash
-# Verificações:
-✅ JavaScript listener injetado?
-✅ Formato das mensagens correto?
-✅ WebView carregou completamente?
-✅ postMessage funcionando?
-```
-
-#### 3. **Layout quebrado**
-
-```bash
-# Verificações:
-✅ Dimensões adequadas para o dispositivo?
-✅ Estilos corretos para o tipo?
-✅ Z-index conflitando?
-✅ SafeArea configurada?
-```
-
-#### 4. **Storage não persiste**
-
-```bash
-# Verificações:
-✅ AsyncStorage instalado?
-✅ Permissões de storage?
-✅ Dados sendo serializados corretamente?
-✅ Chaves de storage únicas?
-```
-
-### Debug Avançado
-
-```typescript
-// Habilitar logs detalhados
-console.log('Widget event received:', processedKey, value);
-
-// Verificar dados persistidos
-const data = await storageService.read();
-console.log('Stored data:', data);
-
-// Verificar URL construída
-const url = buildWidgetURL(soluCXKey, data);
-console.log('Widget URL:', url);
-```
-
-## 📚 Dependências
-
-### Peer Dependencies
-
-```json
-{
-  "react-native-webview": "^13.0.0",
-  "@react-native-async-storage/async-storage": "^2.0.0",
-  "react": "^19.0.0",
-  "react-native": "^0.79.0"
-}
-```
-
-### Compatibilidade
-
-- **React Native**: 0.70+
-- **Expo**: 50+
-- **iOS**: 11+
-- **Android**: API 21+
-- **Web**: Suporte limitado (WebView)
-
-## 📄 Licença
-
-Este projeto é privado e proprietário da SoluCX.
-
----
-
-**Desenvolvido com ❤️ pela equipe SoluCX**
+# SoluCX Widget
+
+Um widget React Native modular para coleta de feedback e pesquisas, desenvolvido seguindo princípios de Clean Code e arquitetura escalável.
+
+## 📋 Visão Geral
+
+O SoluCX Widget oferece quatro modos de renderização flexíveis para integração em aplicações React Native/Expo:
+
+- **Top**: Widget fixo no topo da tela
+- **Bottom**: Widget fixo na parte inferior
+- **Modal**: Widget em sobreposição centralizada
+- **Inline**: Widget integrado ao fluxo do layout
+
+## 🏗️ Arquitetura
+
+### Componentes Principais
+
+- [`SoluCXWidget.tsx`](src/SoluCXWidget.tsx) - Componente principal
+- [`useWidgetState.ts`](src/hooks/useWidgetState.ts) - Hook para gerenciamento de estado
+- [`useWidgetHeight.ts`](src/hooks/useWidgetHeight.ts) - Hook para gerenciamento de altura (dinâmica/fixa)
+- [`WidgetEventService`](src/services/widgetEventService.ts) - Serviço de eventos
+- [`StorageService`](src/services/storage.ts) - Persistência local
+
+### Estrutura de Arquivos
+
+```
+src/
+├── SoluCXWidget.tsx           # Componente principal
+├── components/                # Componentes especializados
+│   ├── ModalWidget.tsx        # Widget modal
+│   ├── InlineWidget.tsx       # Widget inline
+│   └── OverlayWidget.tsx      # Widget overlay (top/bottom)
+├── hooks/                     # Hooks personalizados
+│   ├── useWidgetState.ts      # Estado do widget
+│   ├── useWidgetHeight.ts     # Gerenciamento de altura (dinâmica/fixa)
+│   └── useHeightAnimation.ts  # Animação de altura
+├── services/                  # Serviços
+│   ├── widgetEventService.ts  # Gerenciamento de eventos
+│   └── storage.ts             # Persistência de dados
+├── interfaces/                # Tipos TypeScript
+│   ├── index.ts               # Exports centralizados
+│   ├── WidgetData.ts          # Dados do widget
+│   ├── WidgetOptions.ts       # Opções de configuração
+│   ├── WidgetResponse.ts      # Respostas e erros
+│   └── WidgetSamplerLog.ts    # Log de tentativas
+├── styles/                    # Estilos
+│   └── widgetStyles.ts        # Estilos por tipo
+├── utils/                     # Utilitários
+│   └── urlUtils.ts            # Construção de URLs
+├── constants/                 # Constantes
+│   └── webViewConstants.ts    # URLs e configurações
+└── __tests__/                 # Testes
+    ├── urlUtils.test.ts
+    └── useWidgetState.test.ts
+```
+
+## 🚀 Instalação e Uso
+
+### Instalação
+
+```bash
+# Como dependência local (monorepo)
+npm install solucx_widget@file:./modules/solucx_widget
+
+# Dependências peer necessárias
+npm install react-native-webview @react-native-async-storage/async-storage
+```
+
+### Uso Básico
+
+```tsx
+import React from 'react';
+import { SoluCXWidget } from 'solucx_widget';
+
+export default function MyComponent() {
+  return (
+    <SoluCXWidget
+      soluCXKey='sua-chave-solucx'
+      type='bottom' // 'top' | 'bottom' | 'modal' | 'inline'
+      data={{
+        journey: 'nome_da_jornada',
+        name: 'Nome do Cliente',
+        email: 'cliente@email.com',
+        phone: '11999999999',
+        store_id: '1',
+        employee_id: '1',
+        amount: 100,
+        param_REGIAO: 'SUDESTE'
+      }}
+      options={{
+        height: 400
+      }}
+    />
+  );
+}
+```
+
+## 🎛️ API do Componente
+
+### Props do SoluCXWidget
+
+```typescript
+interface SoluCXWidgetProps {
+  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
+}
+```
+
+### Tipos de Widget
+
+```typescript
+type WidgetType = 'bottom' | 'top' | 'inline' | 'modal';
+```
+
+### Dados do Widget
+
+```typescript
+interface WidgetData {
+  // Identificadores
+  transaction_id?: string;
+  customer_id?: string;
+
+  // Dados do cliente
+  name?: string;
+  email?: string;
+  phone?: string;
+  birth_date?: string;
+  document?: string;
+
+  // Dados da transação
+  store_id?: string;
+  store_name?: string;
+  employee_id?: string;
+  employee_name?: string;
+  amount?: number;
+  score?: number;
+
+  // Parâmetros customizados
+  journey?: string;
+  [key: string]: string | number | undefined;
+}
+```
+
+### Opções de Configuração
+
+```typescript
+interface WidgetOptions {
+  height?: number; // Altura fixa em pontos (não pixels)
+  // Se não fornecido: altura dinâmica baseada em eventos de resize
+  // Se fornecido: altura fixa para todos os tipos de widget
+  retry?: {
+    // Configuração de retry
+    attempts?: number; // Número de tentativas
+    interval?: number; // Intervalo entre tentativas (ms)
+  };
+  waitDelayAfterRating?: number; // Delay após avaliação (ms)
+}
+```
+
+**⚙️ Gerenciamento de Altura:**
+
+O widget possui dois modos de altura:
+
+1. **Altura Dinâmica (padrão)**: Quando `height` não é fornecido, o widget se ajusta automaticamente através de eventos `FORM_RESIZE` do conteúdo. Funciona para todos os tipos (`bottom`, `top`, `inline`, `modal`).
+
+2. **Altura Fixa**: Quando `height` é especificado, o valor é fixo e eventos de resize são ignorados. Funciona para todos os tipos de widget.
+
+```tsx
+// Altura dinâmica - se adapta ao conteúdo
+<SoluCXWidget
+  type="bottom"
+  options={{}}  // height não especificado
+  {...props}
+/>
+
+// Altura fixa de 400 pontos
+<SoluCXWidget
+  type="modal"
+  options={{ height: 400 }}  // altura fixa
+  {...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 do dispositivo.
+
+## 🔄 Sistema de Eventos
+
+O widget comunica através de mensagens WebView bidirecionais:
+
+### Eventos Suportados
+
+```typescript
+type EventKey =
+  | 'FORM_OPENED' // Widget foi aberto
+  | 'FORM_CLOSE' // Usuário fechou o widget
+  | 'FORM_ERROR' // Erro no carregamento
+  | 'FORM_RESIZE' // Widget redimensionado
+  | 'FORM_PAGECHANGED' // Mudança de página
+  | 'QUESTION_ANSWERED' // Pergunta respondida
+  | 'FORM_COMPLETED' // Formulário concluído
+  | 'FORM_PARTIALCOMPLETED'; // Completado parcialmente
+```
+
+### Tratamento de Eventos
+
+Os eventos são processados automaticamente pelo [`WidgetEventService`](src/services/widgetEventService.ts):
+
+```typescript
+const eventService = new WidgetEventService(
+  setIsWidgetVisible, // Função para controlar visibilidade
+  resize, // Função para redimensionar
+  open // Função para abrir widget
+);
+```
+
+## 💾 Persistência de Dados
+
+O widget utiliza [`AsyncStorage`](@react-native-async-storage/async-storage) para persistir:
+
+- **Histórico de tentativas**: Controla quantas vezes o widget foi exibido
+- **Última avaliação**: Data da última interação
+- **Controle de frequência**: Evita spam de widgets
+
+### Estrutura dos Dados
+
+```typescript
+interface WidgetSamplerLog {
+  attempts: number; // Número de tentativas
+  lastAttempt: number; // Timestamp da última tentativa
+  lastRating: number; // Timestamp da última avaliação
+  lastParcial: number; // Timestamp do último parcial
+}
+```
+
+## 🎨 Customização de Estilos
+
+### Estilos por Tipo
+
+Cada tipo de widget possui estilos específicos definidos em [`widgetStyles.ts`](src/styles/widgetStyles.ts):
+
+```typescript
+export const getWidgetStyles = (type: WidgetType) => {
+  const styleMap = {
+    bottom: { container: styles.wrapper, content: styles.bottom },
+    top: { container: styles.wrapper, content: styles.top },
+    inline: { container: styles.inlineWrapper, content: styles.inline },
+    modal: { container: styles.wrapper, content: styles.inline }
+  };
+
+  return styleMap[type] || styleMap.bottom;
+};
+```
+
+### Características Visuais
+
+- **Bottom/Top**: Position absolute com z-index elevado
+- **Modal**: Overlay com background semitransparente
+- **Inline**: Integrado ao fluxo normal do layout
+
+## 🔧 Utilitários
+
+### Construção de URLs
+
+O [`urlUtils.ts`](src/utils/urlUtils.ts) gerencia a construção de URLs da pesquisa:
+
+```typescript
+export function buildWidgetURL(key: string, data: WidgetData): string {
+  const params = new URLSearchParams(data as Record<string, string>);
+  const baseURL = `${BASE_URL}/${key}/?mode=widget`;
+
+  if (data.transaction_id) {
+    return `${baseURL}&${params.toString()}`;
+  }
+
+  return `${baseURL}&transaction_id=&${params.toString()}`;
+}
+```
+
+## 🧪 Testes
+
+### Executando Testes
+
+```bash
+# Todos os testes
+npm test
+
+# Teste específico
+npm test -- urlUtils.test.ts
+npm test -- useWidgetState.test.ts
+```
+
+### Cobertura de Testes
+
+- ✅ Construção de URLs
+- ✅ Gerenciamento de eventos
+- ✅ Estados do widget
+- ✅ Persistência de dados
+
+## ⚙️ Configuração
+
+### Constantes
+
+Configurações centralizadas em [`webViewConstants.ts`](src/constants/webViewConstants.ts):
+
+```typescript
+export const BASE_URL = 'https://survey-link.solucx.com.br/link';
+export const STORAGE_KEY = '@solucxWidgetLog';
+export const MIN_HEIGHT = 200;
+export const FIXED_Z_INDEX = 9999;
+export const MODAL_Z_INDEX = 10000;
+```
+
+### JavaScript Injection
+
+Listener para comunicação WebView:
+
+```typescript
+export const WEB_VIEW_MESSAGE_LISTENER = `
+  window.addEventListener('message', function(event) {
+    window.ReactNativeWebView.postMessage(event.data);
+  });
+`;
+```
+
+## 🚨 Considerações Importantes
+
+### 1. **Comportamento de Posicionamento**
+
+⚠️ **Ponto Crítico**: A posição no JSX **não determina** onde widgets `top`, `bottom` e `modal` aparecem:
+
+```tsx
+// ❌ Isso NÃO faz o widget aparecer no meio
+<Text>Conteúdo antes</Text>
+<SoluCXWidget type="bottom" {...props} /> {/* Sempre aparece embaixo */}
+<Text>Conteúdo depois</Text>
+
+// ✅ Apenas o tipo "inline" respeita a posição no código
+<Text>Conteúdo antes</Text>
+<SoluCXWidget type="inline" {...props} /> {/* Aparece aqui */}
+<Text>Conteúdo depois</Text>
+```
+
+### 2. **Performance**
+
+- Widget usa WebView interna (overhead de performance)
+- Carregamento lazy das pesquisas
+- Cache automático via AsyncStorage
+- JavaScript injection para comunicação
+
+### 3. **Segurança**
+
+- **Chaves API**: Nunca hardcode em produção
+- **Dados sensíveis**: Não são logados automaticamente
+- **URLs**: Validadas antes do carregamento
+- **HTTPS**: Obrigatório para comunicação
+
+### 4. **Limitações Técnicas**
+
+- Requer conexão com internet
+- Dependente do WebView do sistema
+- Eventos assíncronos (não bloqueantes)
+- Storage limitado do dispositivo
+
+## 📝 Desenvolvimento
+
+### Adicionando Novos Tipos
+
+1. **Estenda o tipo WidgetType**:
+
+```typescript
+// modules/solucx_widget/src/interfaces/index.ts
+export type WidgetType = 'bottom' | 'top' | 'inline' | 'modal' | 'novo_tipo';
+```
+
+2. **Adicione estilos correspondentes**:
+
+```typescript
+// modules/solucx_widget/src/styles/widgetStyles.ts
+const styleMap = {
+  // ... estilos existentes
+  novo_tipo: { container: styles.novoWrapper, content: styles.novoContent }
+};
+```
+
+3. **Implemente lógica no componente principal**:
+
+```typescript
+// modules/solucx_widget/src/SoluCXWidget.tsx
+if (type === 'novo_tipo') {
+  return <NovoTipoWidget>{/* ... */}</NovoTipoWidget>;
+}
+```
+
+### Adicionando Novos Eventos
+
+1. **Estenda EventKey**:
+
+```typescript
+// modules/solucx_widget/src/interfaces/index.ts
+export type EventKey = 'FORM_OPENED' | 'NOVO_EVENTO'; // Novo evento
+```
+
+2. **Implemente handler**:
+
+```typescript
+// modules/solucx_widget/src/services/widgetEventService.ts
+private executeEvent(eventKey: EventKey, value: string): WidgetResponse {
+  const eventHandlers = {
+    // ... handlers existentes
+    NOVO_EVENTO: (value: string) => this.handleNovoEvento(value),
+  };
+}
+```
+
+3. **Adicione testes**:
+
+```typescript
+// modules/solucx_widget/src/__tests__/widgetEventService.test.ts
+it('should handle NOVO_EVENTO correctly', () => {
+  const result = service.handleMessage('NOVO_EVENTO-data', true);
+  expect(result).toEqual({ status: 'success' });
+});
+```
+
+## 🔍 Troubleshooting
+
+### Problemas Comuns
+
+#### 1. **Widget não aparece**
+
+```bash
+# Verificações:
+✅ Chave SoluCX válida?
+✅ Conectividade com internet?
+✅ Logs do WebView no console?
+✅ Evento FORM_OPENED sendo disparado?
+```
+
+#### 2. **Eventos não funcionam**
+
+```bash
+# Verificações:
+✅ JavaScript listener injetado?
+✅ Formato das mensagens correto?
+✅ WebView carregou completamente?
+✅ postMessage funcionando?
+```
+
+#### 3. **Layout quebrado**
+
+```bash
+# Verificações:
+✅ Dimensões adequadas para o dispositivo?
+✅ Estilos corretos para o tipo?
+✅ Z-index conflitando?
+✅ SafeArea configurada?
+```
+
+#### 4. **Storage não persiste**
+
+```bash
+# Verificações:
+✅ AsyncStorage instalado?
+✅ Permissões de storage?
+✅ Dados sendo serializados corretamente?
+✅ Chaves de storage únicas?
+```
+
+### Debug Avançado
+
+```typescript
+// Habilitar logs detalhados
+console.log('Widget event received:', processedKey, value);
+
+// Verificar dados persistidos
+const data = await storageService.read();
+console.log('Stored data:', data);
+
+// Verificar URL construída
+const url = buildWidgetURL(soluCXKey, data);
+console.log('Widget URL:', url);
+```
+
+## 📚 Dependências
+
+### Peer Dependencies
+
+```json
+{
+  "react-native-webview": "^13.0.0",
+  "@react-native-async-storage/async-storage": "^2.0.0",
+  "react": "^19.0.0",
+  "react-native": "^0.79.0"
+}
+```
+
+### Compatibilidade
+
+- **React Native**: 0.70+
+- **Expo**: 50+
+- **iOS**: 11+
+- **Android**: API 21+
+- **Web**: Suporte limitado (WebView)
+
+## 📄 Licença
+
+Este projeto é privado e proprietário da SoluCX.
+
+---
+
+**Desenvolvido com ❤️ pela equipe SoluCX**