🏷️ Agenus UTMs Tracker

Sistema de aplicação e persistência de UTMs e parâmetros de campanha. Garante que os parâmetros de URL (utm_source, gclid, fbclid, etc) sejam aplicados corretamente em links e formulários ao longo da navegação, mesmo em páginas dinâmicas.

✅ Funcionalidades

• ✅ Captura e persistência de UTMs
• ✅ Aplicação automática em links e formulários
• ✅ Suporte a páginas dinâmicas (SPA)
• ✅ Retry automático para dom changes
• ✅ AutoInit via Script Tag com data-attributes
• ✅ Bloqueio anti-duplicação
• ✅ Modo debug com logs

✅ Instalação

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

✅ Uso Básico (TypeScript / ESM)

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

init({
  enabled: true,
  debug: true,
  delay: 0,
});

✅ Uso via CommonJS (CJS)

const { init } = require("@agenus-io/utms");

init({
  enabled: true,
  debug: true,
  delay: 0,
});

✅ Uso via Script Tag (AutoInit)

<script
  src="https://cdn.jsdelivr.net/npm/@agenus-io/utms/dist/index.global.js"
  data-params-tracker
  data-enabled="true"
  data-debug="true"
  data-delay="0">
</script>

Ou usando o export específico:

<script
  src="https://cdn.jsdelivr.net/npm/@agenus-io/utms/global"
  data-params-tracker
  data-enabled="true"
  data-debug="true"
  data-delay="0">
</script>

Após carregar, o tracker estará disponível globalmente como utms.

✅ Configuração (InitProps)

| Propriedade | Tipo | Padrão | Descrição | |---|---|---|---| | enabled | boolean | true | Ativa/desativa o tracker | | delay | number | 0 | Delay antes de iniciar | | debug | boolean | false | Ativa logs no console |

✅ API Pública

| Função | Descrição | |---|---| | init(config) | Inicializa o tracker | | UTMSInit | Classe principal | | waitForFirstUserInteraction(callback) | Aguarda interação do usuário | | log() | Logger interno |

✅ Fluxo Interno

1. Captura UTMs da URL
2. Persiste localmente
3. Aplica UTMs automaticamente em todos os links e formulários
4. Observa DOM dinâmico (SPA)
5. Faz retries periódicos para garantir consistência

✅ Formatos de Build

O pacote é distribuído em múltiplos formatos:

• ESM (index.esm.js) - Para uso com import
• CJS (index.cjs.js) - Para uso com require
• IIFE (index.global.js) - Para uso direto no browser via <script>
• TypeScript Definitions (index.d.ts, index.d.mts) - Tipos TypeScript

✅ Desenvolvimento Local

# Instalar dependências
npm install

# Build do projeto
npm run build

# Modo desenvolvimento (watch)
npm run dev

# Verificar tipos
npm run type-check

# Lint
npm run lint

# Lint com auto-fix
npm run lint:fix

✅ Versionamento e Release

Este projeto usa Changesets para gerenciamento de versões.

Criar um changeset

Quando fizer mudanças que precisam ser versionadas:

npm run changeset

Isso irá guiá-lo através de um processo interativo para criar um changeset descrevendo suas mudanças (major, minor ou patch).

Atualizar versões

Antes de publicar, atualize as versões e gere o changelog:

npm run version

Publicar no npm

Para publicar uma nova versão:

npm run release

Isso irá fazer o build e publicar no npm automaticamente.

✅ Estrutura Interna

src/
├── index.ts               # Exportações principais
├── init.ts                # Inicialização
├── types.ts               # Tipos globais
├── global.d.ts            # Declarações globais
└── utils/
    ├── applyUTMs.ts       # Aplicação de UTMs
    ├── domWatcher.ts      # Observador de DOM
    ├── geParams.ts        # Captura de parâmetros
    ├── log.ts             # Sistema de logs
    ├── paramsTracker.ts   # Classe principal do tracker
    ├── retryApply.ts      # Retry automático
    └── waitForFirstUserInteraction.ts  # Aguarda interação

✅ Licença

MIT