🔙 BackRedirect

Sistema de redirecionamento de volta (Back Redirect) que intercepta a navegação do usuário e redireciona para uma URL específica quando ele tenta voltar na página.

✅ Funcionalidades

• ✅ Inicialização Imediata: Ativa automaticamente ao carregar a página, sem esperar interação do usuário
• ✅ Entrada Falsa Automática: Cria automaticamente uma entrada falsa no histórico para habilitar o botão voltar
• ✅ Intercepta navegação de volta (botão voltar do navegador)
• ✅ Redireciona automaticamente para URL configurada
• ✅ Preserva parâmetros de busca (opcional)
• ✅ Sistema de tracking e logs
• ✅ Callbacks antes e depois do redirecionamento
• ✅ Suporte a delay configurável
• ✅ Modo debug para desenvolvimento
• ✅ Bloqueio global anti-duplicação
• ✅ Suporte a múltiplos formatos (CJS, ESM, IIFE)

✅ Instalação

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

✅ Uso Básico (TypeScript / ESM)

import { init } from "@agenus-io/backredirect";

const tracker = init({
  url: "https://example.com",
  preserveSearchParams: true,
  enabled: true,
  debug: true,
});

✅ Uso via Script Tag (AutoInit)

O script pode ser inicializado automaticamente usando atributos data-*:

<script 
  src="https://cdn.jsdelivr.net/npm/@agenus-io/backredirect/dist/index.global.js"
  data-backredirect
  data-url="https://example.com"
  data-preserve-search-params="true"
  data-enabled="true"
  data-debug="true"
  data-delay="0"
  data-force-redirect="false">
</script>

Atributos do Script Tag

| Atributo | Tipo | Padrão | Descrição | |---|---|---|---| | data-backredirect | boolean | - | Obrigatório - Ativa a inicialização automática | | data-url | string | "/" | URL de destino para redirecionamento | | data-preserve-search-params | boolean | false | Preserva parâmetros de busca da URL atual | | data-enabled | boolean | true | Ativa/desativa o tracker | | data-delay | number | 0 | Delay em milissegundos antes do redirecionamento | | data-force-redirect | boolean | false | Força redirecionamento imediato ao carregar | | data-debug | boolean | false | Habilita logs no console |

✅ Configuração (InitProps)

| Propriedade | Tipo | Padrão | Descrição | |---|---|---|---| | url | string | - | Obrigatório - URL de destino para redirecionamento | | preserveSearchParams | boolean | false | Mantém os query params da URL atual | | enabled | boolean | true | Ativa/desativa o tracker | | delay | number | 0 | Delay em milissegundos antes do redirecionamento | | forceRedirect | boolean | false | Força redirecionamento imediato ao inicializar | | onBeforeRedirect | Function | () => {} | Callback executado antes do redirecionamento | | onAfterRedirect | Function | () => {} | Callback executado após o redirecionamento | | debug | boolean | false | Habilita logs detalhados no console |

✅ Comportamento Imediato

O BackRedirect foi projetado para funcionar imediatamente ao carregar a página:

1. Entrada Falsa Automática: Assim que o script carrega, uma entrada falsa é criada no histórico do navegador, habilitando o botão "voltar"
2. Interceptador Ativo: O interceptador de navegação de volta é ativado imediatamente, sem esperar interação do usuário
3. Pronto para Uso: O sistema está completamente funcional desde o carregamento da página

Como Funciona

Página carrega
    ↓
Script inicializa
    ↓
Cria entrada falsa no histórico (#fake-entry)
    ↓
Ativa interceptador de popstate
    ↓
Usuário clica em "voltar"
    ↓
Popstate detecta entrada falsa
    ↓
Redireciona para URL configurada

✅ API Pública

Funções Principais

| Função | Descrição | |---|---| | init(config) | Inicializa o tracker com as configurações fornecidas | | BackRedirectInit | Classe principal do tracker (retornada por init()) |

Funções Utilitárias (Exportadas)

| Função | Descrição | |---|---| | forceFakeHistoryEntry(debug?) | Adiciona entrada falsa ao histórico manualmente | | injectBackRedirect(ctx) | Injeta o sistema de interceptação (chamado automaticamente) | | interceptLinkClicks(ctx) | Intercepta cliques em links internos | | interceptBackNavigation(ctx) | Intercepta navegação de volta (popstate) | | buildTargetUrl(config) | Constrói a URL final com parâmetros preservados | | waitForFirstUserInteraction(callback) | Aguarda primeira interação do usuário (não usado mais na inicialização) | | log(options) | Função de logging interna |

✅ Tipos TypeScript

interface RedirectData {
  timestamp: number;
  currentUrl: string;
  targetUrl: string;
  referrer: string;
  sessionId: string;
  userAgent: string;
  screenResolution: string;
  timeOnPage: number;
  redirectType: "back" | "forward" | "external" | "fallback";
  preservedParams?: string;
  metadata?: Record<string, any>;
}

interface InitProps {
  url: string;
  preserveSearchParams: boolean;
  enabled: boolean;
  delay?: number;
  forceRedirect?: boolean;
  onBeforeRedirect?: (data: RedirectData) => void;
  onAfterRedirect?: (data: RedirectData) => void;
  debug?: boolean;
}

interface TrackerContext {
  config: Required<InitProps>;
  sessionId: string;
  startTime: number;
  redirectHistory: RedirectData[];
  isTracking: boolean;
  targetUrl: string;
}

✅ Fluxo Interno

1. Inicialização: Script carrega e detecta atributos data-* ou chamada manual de init()
2. Criação de Entrada Falsa: forceFakeHistoryEntry() cria entrada falsa no histórico imediatamente
3. Ativação do Interceptador: interceptBackNavigation() é ativado imediatamente
4. Interceptação de Links: interceptLinkClicks() monitora cliques em links internos
5. Detecção de Volta: Quando usuário clica em "voltar", popstate é disparado
6. Redirecionamento: Sistema redireciona para URL configurada
7. Callbacks: Executa onBeforeRedirect e onAfterRedirect se configurados

✅ Exemplo Completo

import { init } from "@agenus-io/backredirect";

const tracker = init({
  url: "https://example.com",
  preserveSearchParams: true,
  enabled: true,
  delay: 0,
  debug: true,
  onBeforeRedirect: (data) => {
    console.log("Redirecionando para:", data.targetUrl);
  },
  onAfterRedirect: (data) => {
    console.log("Redirecionamento concluído");
  },
});

// O tracker está ativo imediatamente
// O botão "voltar" do navegador já está habilitado

✅ Desenvolvimento Local

# Instalar dependências
pnpm install

# Compilar o projeto
pnpm build

# Modo desenvolvimento (watch)
pnpm dev

# Verificar tipos
pnpm type-check

# Lint
pnpm lint

✅ Estrutura do Projeto

src/
├── index.ts                      # Exportações principais e auto-init
├── init.ts                       # Função de inicialização
├── types.ts                      # Tipos TypeScript
├── global.d.ts                   # Declarações globais
└── utils/
    ├── backRedirectTracker.ts    # Classe principal BackRedirectInit
    ├── injectBackRedirect.ts     # Injeção do sistema
    ├── forceFakeHistoryEntry.ts  # Criação de entrada falsa no histórico
    ├── interceptBackNavigation.ts # Interceptação de navegação de volta
    ├── interceptLinkClicks.ts  # Interceptação de cliques em links
    ├── buildTargetUrl.ts         # Construção da URL de destino
    ├── generateSessionId.ts     # Geração de ID de sessão
    ├── waitForFirstUserInteraction.ts # Aguarda interação (utilitário)
    └── log.ts                    # Sistema de logging

✅ Formato de Build

O projeto é compilado em três formatos:

• CJS (dist/index.cjs.js): CommonJS para Node.js
• ESM (dist/index.esm.js): ES Modules para bundlers modernos
• IIFE (dist/index.global.js): Formato global para uso direto no browser

✅ Licença

MIT