UTMTrackJS

UTMTrackJS foi criada para ser "plug-and-play": basta adicionar o script à sua página e ela começa a funcionar, salvando a última campanha UTM que o usuário acessou e facilitando o uso desses dados.

Perfeita para:

• Marketeiros que precisam rastrear campanhas
• Empresas que usam múltiplas fontes de tráfego
• Sites com formulários que precisam dos dados de origem

Sem Dependências

• Zero dependências externas: Não requer jQuery, React, Vue ou qualquer framework
• Vanilla JavaScript puro: Compatível com qualquer stack tecnológica
• Performance otimizada: Carregamento assíncrono não bloqueia a página

Segurança

• XSS Protection: Proteção completa contra Cross-Site Scripting
• Code Injection: Prevenção de tentativas de injeção de código
• DoS Protection: Limitação de recursos para prevenir ataques DoS

Instalação e Setup

Método 1: Download Direto

1. Baixe o arquivo utmtrack.js
2. Inclua no seu HTML:

<!-- Opção 1: No final do body (recomendado) -->
<script src="path/to/utmtrack.js"></script>

<!-- Opção 2: No head com defer -->
<script src="path/to/utmtrack.js" defer></script>

<!-- Opção 3: Via CDN (quando disponível) -->
<script src="https://cdn.jsdelivr.net/gh/gmasson/utmtrackjs@main/utmtrack.js"></script>

Guia de Uso Completo

Como Funciona

1. Captura: Quando um usuário acessa qualquer página com parâmetros UTM
2. Armazena: Os dados são salvos no localStorage do navegador
3. Persiste: Os dados ficam disponíveis em todas as páginas do site
4. Preenche: Elementos HTML são preenchidos automaticamente

Exemplo Prático Completo

Cenário: Usuário clica em um anúncio do Google Ads e acessa:

https://seusite.com/landing?utm_source=google&utm_medium=cpc&utm_campaign=black_friday_2025&gclid=abc123

Resultado: Todos esses dados ficam disponíveis em qualquer página do site!

---

Métodos de Uso

Preenchimento Automático no HTML

Adicione o atributo data-utmtrackjs="parametro" em qualquer elemento:

<!-- Formulários completos -->
<form action="/leads" method="POST">
  <input type="text" name="name" placeholder="Seu nome" required>
  <input type="email" name="email" placeholder="Seu email" required>
  
  <!-- Dados de tracking automáticos -->
  <input type="hidden" name="utm_source" data-utmtrackjs="utm_source">
  <input type="hidden" name="utm_medium" data-utmtrackjs="utm_medium">
  <input type="hidden" name="utm_campaign" data-utmtrackjs="utm_campaign">
  <input type="hidden" name="utm_term" data-utmtrackjs="utm_term">
  <input type="hidden" name="utm_content" data-utmtrackjs="utm_content">
  <input type="hidden" name="gclid" data-utmtrackjs="gclid">
  
  <button type="submit">Enviar</button>
</form>

Definir Dados Manualmente

// Definir UTM individual
UTMTrackJS.setUtm('utm_source', 'newsletter');

// Definir múltiplos de uma vez
UTMTrackJS.setUtm({
  utm_source: 'email',
  utm_medium: 'newsletter',
  utm_campaign: 'welcome_series',
  utm_content: 'button_cta'
});

// Útil para SPAs ou quando os UTMs vêm de APIs
async function trackFromAPI() {
  const campaignData = await fetch('/api/campaign-data').then(r => r.json());
  UTMTrackJS.setUtm(campaignData.utms);
}

Principais Métodos

UTMTrackJS.getUtm(key)

Recupera o valor de uma UTM específica.

const source = UTMTrackJS.getUtm('utm_source');     // Ex: "google"
const campaign = UTMTrackJS.getUtm('utm_campaign'); // Ex: "black_friday"
const gclid = UTMTrackJS.getUtm('gclid');           // Ex: "EAIaIQobChMI..."

UTMTrackJS.setUtm(key, value) ou UTMTrackJS.setUtm(object)

Define uma ou múltiplas UTMs.

// UTM individual
UTMTrackJS.setUtm('utm_source', 'newsletter');

// Múltiplas UTMs
UTMTrackJS.setUtm({
  utm_source: 'facebook',
  utm_medium: 'social',
  utm_campaign: 'product_launch'
});

UTMTrackJS.getAllUtms()

Recupera todas as UTMs armazenadas.

const allUtms = UTMTrackJS.getAllUtms();
console.log(allUtms); // { "utm_source": "google", "utm_medium": "cpc", ... }

UTMTrackJS.removeUtm(key) ou UTMTrackJS.removeUtm()

Remove uma UTM específica ou todas.

UTMTrackJS.removeUtm('utm_source');  // Remove apenas utm_source
UTMTrackJS.removeUtm();              // Remove todas as UTMs

UTMTrackJS.refresh()

Re-popula elementos da página (útil para SPAs).

// Após mudanças no DOM ou novas UTMs
UTMTrackJS.setUtm('utm_source', 'new_source');
UTMTrackJS.refresh(); // Atualiza todos os elementos da página

UTMTrackJS.storageKey

Chave usada no localStorage.

console.log(UTMTrackJS.storageKey); // "utmtrackjs_last_params"

UTMTrackJS.supportedKeys

Lista todos os parâmetros suportados.

console.log(UTMTrackJS.supportedKeys); 
// ["utm_source", "utm_medium", "utm_campaign", "gclid", "fbclid", ...]

Parâmetros Suportados

A biblioteca captura automaticamente todos estes parâmetros da URL:

UTMs Padrão:

• utm_source, utm_medium, utm_campaign, utm_term, utm_content

UTMs Estendidos:

• utm_id, utm_source_platform, utm_creative_format, utm_marketing_tactic

Click IDs:

• gclid (Google), fbclid (Facebook), msclkid (Microsoft)
• ttclid (TikTok), twclid (Twitter), li_fat_id (LinkedIn)

Outros Sistemas:

• Snapchat: sc_campaign, sc_channel, sc_content, sc_medium, sc_outcome
• Mailchimp: mc_cid, mc_eid
• Piwik/Matomo: pk_campaign, pk_kwd, pk_medium, pk_source

Licença

Este projeto está licenciado sob a Licença MIT - veja o arquivo LICENSE para detalhes.