@agenus-io/recovery

v0.0.15

Published

16 days ago

Recuperação de leads para Upsely

Downloads

521

0High
0Medium
0Low

davidpimenta

agenus.io

recovery upsely agenus form-abandonment lead-capture form-tracking

@agenus-io/recovery

Sistema robusto de recuperação de abandono de formulários para capturar leads que não completaram o preenchimento. Detecta automaticamente quando usuários preenchem formulários mas não os enviam, capturando os dados preenchidos e enviando para sua API..

Repositório: github.com/techionext/upsely-recovery

🚀 Características

✅ Detecção Automática: Monitora interações do usuário com formulários automaticamente
✅ Captura Inteligente: Coleta dados de todos os campos preenchidos
✅ Sessão Persistente: Sistema de sessão com localStorage e cookies
✅ Fingerprint de Dispositivo: Identificação única do dispositivo
✅ Envio Confiável: Usa sendBeacon com fallback para fetch com keepalive
✅ Auto-inicialização: Suporte a inicialização via script tag
✅ TypeScript: Totalmente tipado para melhor DX
✅ Zero Dependencies: Apenas ua-parser-js para detecção de dispositivo

📦 Instalação

Via NPM

npm install @agenus-io/recovery
# ou
pnpm add @agenus-io/recovery
# ou
yarn add @agenus-io/recovery

Via CDN

Opção 1: unpkg (Recomendado)

<!-- Versão mais recente -->
<script src="https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js"></script>

<!-- Versão específica (recomendado para produção) -->
<script src="https://unpkg.com/@agenus-io/[email protected]/dist/index.global.js"></script>

Opção 2: jsDelivr

<!-- Versão mais recente -->
<script src="https://cdn.jsdelivr.net/npm/@agenus-io/recovery@latest/dist/index.global.js"></script>

<!-- Versão específica (recomendado para produção) -->
<script src="https://cdn.jsdelivr.net/npm/@agenus-io/[email protected]/dist/index.global.js"></script>

Opção 3: esm.sh (ES Modules)

<script type="module">
  import UpselyRecovery from 'https://esm.sh/@agenus-io/[email protected]';
  // Use UpselyRecovery aqui
</script>

Nota: Para produção, sempre use uma versão específica em vez de @latest para evitar quebras inesperadas.

📖 Uso

Inicialização Manual

import UpselyRecovery from '@agenus-io/recovery';

const recovery = new UpselyRecovery({
  apiEndpoint: 'https://sua-api.com/pixel/public/event',
  apiKey: 'sua-chave-api',
  debug: true, // Ativa logs no console
  timeout: 5000
});

Auto-inicialização via Script Tag

<!DOCTYPE html>
<html>
<head>
  <!-- CDN - Use versão específica em produção -->
  <script
    src="https://unpkg.com/@agenus-io/[email protected]/dist/index.global.js"
    data-api-endpoint="https://sua-api.com/pixel/public/event"
    data-api-key="sua-chave-api"
    data-debug="true"
    data-timeout="5000"
  ></script>
</head>
<body>
  <form id="contactForm">
    <input type="text" name="nome" placeholder="Nome" />
    <input type="email" name="email" placeholder="Email" />
    <textarea name="mensagem" placeholder="Mensagem"></textarea>
    <button type="submit">Enviar</button>
  </form>
</body>
</html>

O sistema será inicializado automaticamente e estará disponível em window.upselyRecovery.

URLs do CDN Disponíveis

| CDN | URL | |-----|-----| | unpkg (Recomendado) | https://unpkg.com/@agenus-io/[email protected]/dist/index.global.js | | jsDelivr | https://cdn.jsdelivr.net/npm/@agenus-io/[email protected]/dist/index.global.js | | unpkg (latest) | https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js ⚠️ | | jsDelivr (latest) | https://cdn.jsdelivr.net/npm/@agenus-io/recovery@latest/dist/index.global.js ⚠️ |

⚠️ Atenção: Use @latest apenas em desenvolvimento. Para produção, sempre use uma versão específica.

🔧 Configuração

Interface de Configuração

interface UpselyRecoveryConfig {
  apiEndpoint: string;  // URL da sua API (obrigatório)
  apiKey?: string;      // Chave de autenticação
  debug?: boolean;       // Ativar logs de debug (padrão: false)
  timeout?: number;     // Timeout para requests em ms (padrão: 5000)
  version?: string;     // Versão do script
}

Exemplo Completo

const recovery = new UpselyRecovery({
  apiEndpoint: 'https://api.exemplo.com/pixel/public/event',
  apiKey: 'sua-chave-secreta',
  debug: true,
  timeout: 10000
});

// O sistema já está monitorando todos os formulários na página!
// Quando o usuário preencher campos e fechar a página, os dados serão enviados automaticamente.

📊 Como Funciona

1. Detecção de Interação

O sistema monitora automaticamente:

Eventos focus em campos de formulário
Eventos change e input em campos
Qualquer interação com input, textarea ou select

2. Detecção de Abandono

O sistema detecta abandono quando:

Usuário tenta fechar a página (beforeunload)
Aba fica oculta (visibilitychange)
Página está sendo descarregada (pagehide)

3. Captura de Dados

Quando o abandono é detectado, o sistema:

Coleta todos os campos preenchidos de todos os formulários
Trata diferentes tipos de campos (text, email, checkbox, radio, select)
Ignora campos vazios
Prepara payload com metadados completos

4. Envio de Dados

Os dados são enviados com:

sendBeacon (prioridade) - mais confiável para eventos de saída
fetch com keepalive (fallback) - garante envio mesmo se sendBeacon falhar
Retry automático em caso de falha

📤 Estrutura dos Dados Enviados

{
  event_type: 'form_abandonment',
  forms: [
    {
      form_id: 'contactForm',
      form_index: 0,
      fields: {
        nome: 'João Silva',
        email: '[email protected]',
        mensagem: 'Olá, gostaria de mais informações...'
      },
      field_count: 3
    }
  ],
  total_forms: 1,
  timestamp: 1234567890123
}

Payload Completo do Evento

{
  data: {
    event_type: 'form_abandonment',
    forms: [...],
    total_forms: 1,
    timestamp: 1234567890123
  },
  sessionId: 'session_1234567890_abc123',
  timestamp: 1234567890123,
  fingerprint: 'hash256_do_dispositivo',
  user_agent: 'Mozilla/5.0...',
  page: {
    url: 'https://exemplo.com/contato',
    title: 'Página de Contato',
    referrer: 'https://google.com',
    path: '/contato',
    hostname: 'exemplo.com'
  },
  device: {
    id: 'uuid-do-dispositivo',
    type: 'desktop' | 'mobile' | 'tablet',
    os: {
      name: 'Windows' | 'Mac OS' | 'Linux' | 'iOS' | 'Android',
      version: '10.0'
    },
    browser: {
      name: 'Chrome' | 'Firefox' | 'Safari' | 'Edge',
      version: '120.0'
    },
    engine: {
      name: 'Blink',
      version: '120.0'
    },
    language: 'pt-BR',
    screen: {
      width: 1920,
      height: 1080,
      pixel_ratio: 1
    }
  },
  meta: {
    version: '0.0.2',
    recovery_source: 'upsely',
    environment: 'production',
    script_url: 'https://unpkg.com/@agenus-io/recovery@latest/dist/index.global.js'
  },
  query_params: {
    utm_source: 'google',
    utm_medium: 'cpc'
  }
}

🎯 API

Métodos Principais

`getSessionId(): string`

Retorna o ID da sessão atual.

const sessionId = recovery.getSessionId();
console.log(sessionId); // 'session_1234567890_abc123'

`getSessionData(): ISessionData`

Retorna dados completos da sessão.

const sessionData = recovery.getSessionData();
console.log(sessionData);
// {
//   sessionId: 'session_1234567890_abc123',
//   lastActivity: 1234567890123,
//   createdAt: 1234567890000,
//   visitCount: 5,
//   firstVisit: 1234567890000
// }

`isSessionActive(): boolean`

Verifica se a sessão está ativa (não expirada).

if (recovery.isSessionActive()) {
  console.log('Sessão ativa!');
}

`updateSessionActivity(): void`

Atualiza a última atividade da sessão.

recovery.updateSessionActivity();

`renewSession(): void`

Renova a sessão (cria nova se expirada).

recovery.renewSession();

`clearSession(): void`

Limpa todos os dados da sessão.

recovery.clearSession();

`getConfig(): UpselyRecoveryConfig`

Retorna a configuração atual.

const config = recovery.getConfig();
console.log(config);

`updateConfig(newConfig: Partial<UpselyRecoveryConfig>): void`

Atualiza a configuração.

recovery.updateConfig({
  debug: false,
  timeout: 10000
});

`destroyFormAbandonment(): void`

Destrói o sistema de abandono (remove listeners).

recovery.destroyFormAbandonment();

🧪 Exemplos

Exemplo Básico

<!DOCTYPE html>
<html>
<head>
  <title>Formulário de Contato</title>
</head>
<body>
  <form id="contactForm">
    <input type="text" name="nome" placeholder="Nome completo" required />
    <input type="email" name="email" placeholder="Seu email" required />
    <input type="tel" name="telefone" placeholder="Telefone" />
    <textarea name="mensagem" placeholder="Sua mensagem"></textarea>
    <button type="submit">Enviar</button>
  </form>

  <!-- Use versão específica em produção -->
  <script src="https://unpkg.com/@agenus-io/[email protected]/dist/index.global.js"></script>
  <script>
    const recovery = new UpselyRecovery({
      apiEndpoint: 'https://sua-api.com/pixel/public/event',
      apiKey: 'sua-chave-api',
      debug: true
    });

    // O sistema já está monitorando o formulário!
    // Se o usuário preencher e fechar a página, os dados serão capturados.
  </script>
</body>
</html>

Exemplo com Múltiplos Formulários

<!DOCTYPE html>
<html>
<body>
  <!-- Formulário de Newsletter -->
  <form id="newsletterForm">
    <input type="email" name="email" placeholder="Email" />
    <button type="submit">Inscrever-se</button>
  </form>

  <!-- Formulário de Contato -->
  <form id="contactForm">
    <input type="text" name="nome" placeholder="Nome" />
    <input type="email" name="email" placeholder="Email" />
    <textarea name="mensagem" placeholder="Mensagem"></textarea>
    <button type="submit">Enviar</button>
  </form>

  <!-- Use versão específica em produção -->
  <script src="https://unpkg.com/@agenus-io/[email protected]/dist/index.global.js"></script>
  <script>
    new UpselyRecovery({
      apiEndpoint: 'https://sua-api.com/pixel/public/event',
      apiKey: 'sua-chave-api',
      debug: true
    });
    // Ambos os formulários são monitorados automaticamente!
  </script>
</body>
</html>

Exemplo com TypeScript

import UpselyRecovery from '@agenus-io/recovery';
import type { UpselyRecoveryConfig } from '@agenus-io/recovery';

const config: UpselyRecoveryConfig = {
  apiEndpoint: 'https://sua-api.com/pixel/public/event',
  apiKey: 'sua-chave-api',
  debug: process.env.NODE_ENV === 'development',
  timeout: 10000
};

const recovery = new UpselyRecovery(config);

// Verificar sessão
if (recovery.isSessionActive()) {
  console.log('Sessão ativa:', recovery.getSessionId());
}

// Atualizar configuração em runtime
recovery.updateConfig({
  debug: false
});

🛠️ Desenvolvimento

Pré-requisitos

Node.js >= 18
pnpm >= 8

Instalação

# Clonar repositório
git clone https://github.com/agenus-io/recovery.git
cd recovery

# Instalar dependências
pnpm install

Scripts Disponíveis

# Desenvolvimento com watch
pnpm dev

# Build para produção
pnpm build

# Linting
pnpm lint
pnpm lint:fix

# Formatação de código
pnpm format

# Verificação de tipos
pnpm type-check

# Limpar arquivos gerados
pnpm clean

Estrutura do Projeto

src/
├── index.ts                    # Ponto de entrada principal
├── init.ts                     # Classe principal UpselyRecovery
├── config.ts                   # Configurações globais
├── types.ts                    # Definições de tipos TypeScript
└── utils/                      # Utilitários
    ├── formAbandonment.ts      # Sistema de detecção de abandono
    ├── getFormData.ts          # Captura de dados de formulários
    ├── getSession.ts           # Gerenciamento de sessão
    ├── getFingerprint.ts       # Geração de fingerprint
    ├── getDeviceInfo.ts        # Informações do dispositivo
    ├── sendEvent.tsx           # Envio de eventos
    └── parseConfigFromScriptTag.ts  # Parser de configuração

📦 Build

O projeto usa tsup para gerar múltiplos formatos:

CommonJS (dist/index.cjs.js): Para Node.js e bundlers antigos
ES Modules (dist/index.esm.js): Para bundlers modernos
IIFE (dist/index.global.js): Para uso direto no browser via CDN
TypeScript (dist/index.d.ts): Definições de tipos

🚀 Publicação

Para informações sobre como publicar novas versões no NPM, consulte o README-RELEASE.md.

Comandos Rápidos

# Criar changeset
pnpm changeset:add

# Preparar release
pnpm run release:full

# Publicar no NPM
pnpm run release:publish

🔒 Privacidade e Segurança

✅ Dados Locais: Sessão armazenada apenas localmente (localStorage + cookies)
✅ Sem Tracking Cross-Site: Não rastreia usuários entre sites
✅ Fingerprint Anônimo: Fingerprint não contém informações pessoais
✅ HTTPS Recomendado: Use sempre HTTPS em produção
✅ Sanitização: Considere sanitizar dados sensíveis no backend

🐛 Troubleshooting

O sistema não está detectando abandono

Verifique se debug: true está ativado
Abra o console do navegador (F12)
Verifique se há logs [FormAbandonment]
Certifique-se de que o usuário interagiu com pelo menos um campo

Dados não estão sendo enviados

Verifique se apiEndpoint está correto
Verifique se a API está acessível (CORS configurado)
Verifique o console para erros
Teste a API manualmente com fetch ou curl

Sessão não persiste

Verifique se localStorage está habilitado
Verifique se cookies estão habilitados
Verifique se não está em modo anônimo/privado
Verifique se o domínio permite cookies

📄 Licença

MIT

🤝 Contribuindo

Contribuições são bem-vindas! Por favor:

Faça fork do projeto: github.com/techionext/upsely-recovery
Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
Commit suas mudanças (git commit -m 'Add some AmazingFeature')
Push para a branch (git push origin feature/AmazingFeature)
Abra um Pull Request no GitHub

Reportar Bugs

Se encontrar algum bug, por favor abra uma issue no GitHub com:

Descrição do problema
Passos para reproduzir
Comportamento esperado vs comportamento atual
Ambiente (navegador, versão, etc.)

📞 Suporte

Para suporte:

Abra uma issue no GitHub
Entre em contato com a equipe Agenus

🔗 Links

Repositório: github.com/techionext/upsely-recovery
NPM Package: npmjs.com/package/@agenus-io/recovery
Changelog: CHANGELOG.md
Guia de Release: README-RELEASE.md

Desenvolvido com ❤️ por Agenus

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@agenus-io/recovery

🚀 Características

📦 Instalação

Via NPM

Via CDN

Opção 1: unpkg (Recomendado)

Opção 2: jsDelivr

Opção 3: esm.sh (ES Modules)

📖 Uso

Inicialização Manual

Auto-inicialização via Script Tag

URLs do CDN Disponíveis

🔧 Configuração

Interface de Configuração

Exemplo Completo

📊 Como Funciona

1. Detecção de Interação

2. Detecção de Abandono

3. Captura de Dados

4. Envio de Dados

📤 Estrutura dos Dados Enviados

Payload Completo do Evento

🎯 API

Métodos Principais

getSessionId(): string

getSessionData(): ISessionData

isSessionActive(): boolean

updateSessionActivity(): void

renewSession(): void

clearSession(): void

getConfig(): UpselyRecoveryConfig

updateConfig(newConfig: Partial<UpselyRecoveryConfig>): void

destroyFormAbandonment(): void

🧪 Exemplos

Exemplo Básico

Exemplo com Múltiplos Formulários

Exemplo com TypeScript

🛠️ Desenvolvimento

Pré-requisitos

Instalação

Scripts Disponíveis

Estrutura do Projeto

📦 Build

🚀 Publicação

Comandos Rápidos

🔒 Privacidade e Segurança

🐛 Troubleshooting

O sistema não está detectando abandono

Dados não estão sendo enviados

Sessão não persiste

📄 Licença

🤝 Contribuindo

Reportar Bugs

📞 Suporte

🔗 Links

`getSessionId(): string`

`getSessionData(): ISessionData`

`isSessionActive(): boolean`

`updateSessionActivity(): void`

`renewSession(): void`

`clearSession(): void`

`getConfig(): UpselyRecoveryConfig`

`updateConfig(newConfig: Partial<UpselyRecoveryConfig>): void`

`destroyFormAbandonment(): void`