UTMTrackJS v0.9.5

Biblioteca JavaScript para rastreamento e persistência automática de parâmetros UTM com funcionalidades avançadas e segurança robusta. Feita para monitorar campanhas de marketing com precisão, armazenando dados no navegador com expiração inteligente e preenchendo dados em campos definidos automaticamente.

Características principais:

Captura automática de parâmetros UTM da URL
Expiração configurável de dados (7 dias por padrão)
Preenchimento automático de formulários HTML
Configuração flexível para diferentes cenários de uso

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
Analytics avançado com controle de expiração

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 e Confiabilidade

Sanitização de entrada: Todos os valores capturados passam por whitelist (letras, números, hífen, underscore, ponto e espaço)
Limites e validações: Tamanho máximo de chave, valor, quantidade de chaves e payload salvo no storage
Metadata de integridade: Timestamp, origin e versão salvos juntamente com os dados
Mitigações básicas: Remoção de caracteres potencialmente perigosos e verificação estrutural contra prototype pollution
Expiração configurável: Controle automático de validade (ou opção de nunca expirar)
Nota: As proteções são camadas defensivas gerais; para segurança completa contra XSS/CSRF em sua aplicação use também cabeçalhos HTTP, CSP e validação server-side.

Sumário

Instalação
- Método 1: Download Direto
- Método 2: CDN
Como Funciona
- Cenário de exemplo
Configurações Básicas
Principais Funcionalidades
Configurações Avançadas
Exemplos de Uso
Dicas de Implementação
Licença

Instalação

Método 1: Download Direto

Baixe o arquivo e inclua no seu HTML:

<!-- No final do body -->
<script src="path/to/utmtrack.min.js" defer></script>

Método 2: CDN

Inclua diretamente no seu HTML:

<!-- Opção 1: Via CDN -->
<script src="https://cdn.jsdelivr.net/gh/gmasson/utmtrackjs@main/utmtrack.min.js"></script>

Como Funciona

Captura: Quando um usuário acessa qualquer página com parâmetros UTM
Armazena: Os dados são salvos no localStorage do navegador com timestamp
Expira: Dados expiram automaticamente em 7 dias (configurável)
Persiste: Dados válidos ficam disponíveis em todas as páginas do site
Preenche: Elementos HTML são preenchidos automaticamente

Cenário de exemplo

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

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

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

Configurações Básicas

Padrão (pré-definida na biblioteca, portanto não precisa incluir)

<script src="utmtrack.js"></script>
<script>
// Configuração padrão já aplicada automaticamente:
// UTMTrackJS.configure({ 
//     updateWithLatest: true,
//     maxDataAge: 7 * 24 * 60 * 60 * 1000 // 7 dias
// });
</script>

Dados Permanentes (Nunca Expiram)

<script src="utmtrack.js"></script>
<script>
UTMTrackJS.configure({
	maxDataAge: false // Dados nunca expiram
});
</script>

Captura apenas as primeiras UTMs acessadas

<script src="utmtrack.js"></script>
<script>
UTMTrackJS.configure({ 
	updateWithLatest: false
});
</script>

Adicionar Parâmetros Personalizados

<script src="utmtrack.js"></script>
<script>
UTMTrackJS.configure({
	updateWithLatest: true,
	customUtmKeys: ['meu_parametro', 'codigo_promocional', 'ref_id']
});
// Agora captura: ?utm_source=exemplo&meu_parametro=teste
</script>

Principais Funcionalidades

`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.getConfig()`

Obtém um subconjunto da configuração atual.

Retorna atualmente:

{
	updateWithLatest: true,        // se recaptura em mudanças de URL
	dataExpirationEnabled: true,   // boolean (não retorna o valor numérico de maxDataAge)
	version: "0.9.5",             // versão
	isInitialized: true,           // se a lib foi inicializada
	loggingEnabled: true           // status de logs
}

Observações:

O valor exato de maxDataAge e a lista ativa de chaves personalizadas NÃO são expostos por getConfig().
Para obter as chaves ativas use getDebugInfo().supportedKeys.
Se precisar conhecer maxDataAge, guarde-o na sua própria configuração ou abra um issue solicitando exposição futura.

Exemplo:

const config = UTMTrackJS.getConfig();
console.log('Config (subset):', config);

`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 salvas

`UTMTrackJS.cleanExpiredData()`

Remove dados expirados do localStorage.

const cleaned = UTMTrackJS.cleanExpiredData();
console.log('Dados limpos:', cleaned);

// Nota: se a expiração estiver desabilitada (maxDataAge: false), esta função não fará nada

`UTMTrackJS.getDebugInfo()`

Retorna informações detalhadas para debug.

const debugInfo = UTMTrackJS.getDebugInfo();
console.log('Informações de debug:', debugInfo);

`UTMTrackJS.purge()`

Remove todos os dados UTM armazenados.

UTMTrackJS.purge(); // Remove todos os dados do localStorage
console.log('Todos os dados UTM foram removidos');

`UTMTrackJS.refresh()`

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

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

`UTMTrackJS.supportedKeys`

Lista as chaves UTM PADRÃO embarcadas na biblioteca (não inclui chaves personalizadas adicionadas em runtime).

Para listar TODAS as chaves ativas (padrão + personalizadas) use:

console.log(UTMTrackJS.getDebugInfo().supportedKeys); // inclui personalizadas

Exemplo (padrão):

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

`UTMTrackJS.version`

Versão atual da biblioteca.

console.log(UTMTrackJS.version); // "0.9.5"

Outros Métodos e Recursos (não destacados anteriormente)

`UTMTrackJS.disableUrlMonitoring()`

Desativa o monitoramento de mudanças de URL (History API / popstate). Útil em SPAs que já fazem controle próprio.

UTMTrackJS.disableUrlMonitoring();

`UTMTrackJS.getStorageStats()`

Mostra estatísticas do uso de storage (tamanho, % do limite interno da lib, etc.).

console.log(UTMTrackJS.getStorageStats());

`UTMTrackJS.refresh()`

Reaplica o preenchimento em elementos com data-utmtrackjs (alias já mencionado; listado aqui para completar o agrupamento de utilitários).

`UTMTrackJS.customEvents`

Retorna um objeto com os nomes dos eventos customizados disparados pela biblioteca.

console.log(UTMTrackJS.customEvents);
// { UTM_CAPTURED: 'utmtrackjs:captured', UTM_UPDATED: 'utmtrackjs:updated', ... }

`loggingEnabled` (configuração)

Pode ser desativado para reduzir ruído em produção:

UTMTrackJS.configure({ loggingEnabled: false });

Eventos Customizados

A biblioteca dispara eventos no window. Você pode escutar e reagir:

Evento	Disparado quando	Detail (principais campos)
`utmtrackjs:captured`	UTMs capturadas da URL	`capturedUtms`, `allUtms`, `url`
`utmtrackjs:updated`	`setUtm` altera dados	`updatedKeys`, `updatedValues`, `allUtms`
`utmtrackjs:removed`	`removeUtm` remove chave(s)	`removedKey`, `remainingUtms`
`utmtrackjs:configChanged`	`configure` aceita mudanças	`changedOptions`, `newConfig`

Exemplo:

window.addEventListener('utmtrackjs:captured', e => {
	console.log('Novas UTMs capturadas:', e.detail.capturedUtms);
});

Configurações Avançadas

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);
}

Configuração de Expiração de Dados

Por padrão, os dados UTM expiram em 7 dias. Você pode personalizar esse comportamento:

// Verificar configuração atual
const config = UTMTrackJS.getConfig();
console.log(config); // Mostra toda a configuração

// Personalizar para 3 dias
UTMTrackJS.configure({
  maxDataAge: 3 * 24 * 60 * 60 * 1000 // 3 dias em millisegundos
});

// Configurar para 30 dias
UTMTrackJS.configure({
  maxDataAge: 30 * 24 * 60 * 60 * 1000 // 30 dias
});

// Desabilitar expiração completamente
UTMTrackJS.configure({
  maxDataAge: false // Dados nunca expiram
});

// Configurar para 2 horas (útil para campanhas curtas)
UTMTrackJS.configure({
  maxDataAge: 2 * 60 * 60 * 1000 // 2 horas
});

Configuração Personalizada

A biblioteca oferece configuração flexível para diferentes cenários:

// Configuração completa com parâmetros personalizados
UTMTrackJS.configure({
	updateWithLatest: true,
	maxDataAge: 7 * 24 * 60 * 60 * 1000, // 7 dias (padrão)
	customUtmKeys: [
		'utm_source', 'utm_medium', 'utm_campaign',  // UTMs padrão
		'custom_param', 'tracking_id', 'campaign_id' // Seus parâmetros personalizados
	]
});

// Para aplicações corporativas (dados permanentes)
UTMTrackJS.configure({
	updateWithLatest: false,
	maxDataAge: false, // Nunca expira
	customUtmKeys: ['utm_source', 'utm_campaign', 'employee_id']
});

// Para campanhas de curto prazo (6 horas)
UTMTrackJS.configure({
	updateWithLatest: true,
	maxDataAge: 6 * 60 * 60 * 1000, // 6 horas
	customUtmKeys: ['utm_source', 'utm_medium', 'promo_code']
});

Gerenciar Parâmetros Personalizados

// Adicionar novos parâmetros UTM
UTMTrackJS.addUtmKeys(['meu_parametro', 'outro_parametro']);

// Adicionar um único parâmetro
UTMTrackJS.addUtmKeys('parametro_especial');

// Remover parâmetros
UTMTrackJS.removeUtmKeys(['parametro_antigo']);

// Ver parâmetros suportados atualmente
console.log(UTMTrackJS.supportedKeys);

// Ver configuração atual
const config = UTMTrackJS.getConfig();
console.log(config);

Forçar Recaptura

// Útil após mudanças de configuração
UTMTrackJS.recapture();

Exemplos de Uso

Mais Simples Possível

<a href="#" onclick="abrirWhatsApp()">Falar no WhatsApp</a>

<script src="utmtrack.js"></script>
<script>
function abrirWhatsApp() {
	const utms = UTMTrackJS.getAllUtms() || {};
	const msg = `Olá, gostaria de saber mais informações! Vim através de ${utms.utm_source || 'acesso direto'}, no site`;
	window.open(`https://wa.me/5511999999999?text=${encodeURIComponent(msg)}`);
}
</script>

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>

Landing Page com formulário

<!DOCTYPE html>
<html>
<head>
	<title>Exemplo Formulário de Lead</title>
</head>
<body>
	<form action="enviar-lead.php" method="POST">
		<h2>Entre em contato conosco</h2>
		
		<!-- Campos visíveis -->
		<input type="text" name="nome" placeholder="Seu nome" required>
		<input type="email" name="email" placeholder="Seu email" required>
		<textarea name="mensagem" placeholder="Sua mensagem"></textarea>
		
		<!-- Campos ocultos preenchidos automaticamente -->
		<input type="hidden" data-utmtrackjs="utm_source" name="utm_source">
		<input type="hidden" data-utmtrackjs="utm_medium" name="utm_medium">
		<input type="hidden" data-utmtrackjs="utm_campaign" name="utm_campaign">
		<input type="hidden" data-utmtrackjs="utm_term" name="utm_term">
		<input type="hidden" data-utmtrackjs="utm_content" name="utm_content">
		<input type="hidden" data-utmtrackjs="gclid" name="gclid">
		<input type="hidden" data-utmtrackjs="fbclid" name="fbclid">
		
		<button type="submit">Enviar</button>
	</form>

	<!-- Inclui a biblioteca -->
	<script src="utmtrack.js"></script>
	
	<!-- Configura após carregar -->
	<script>
		// Configura após carregar a biblioteca
		document.addEventListener('DOMContentLoaded', function() {
			// Configura para capturar parâmetros personalizados
			UTMTrackJS.configure({
				updateWithLatest: true, // Sempre salva os últimos dados
				maxDataAge: 14 * 24 * 60 * 60 * 1000 // Expira em 14 dias
			});
			
			console.log('UTMTrackJS configurado!');
			
			// Verificar configuração atual
			const config = UTMTrackJS.getConfig();
			console.log('Configuração atual:', config);
		});
	</script>
</body>
</html>

Salvando eventos no Google Analytics e Pixel

Salva eventos como clicar no botão e envio do formulário com dados UTM

<!DOCTYPE html>
<html>
<head>
	<title>Exemplo Loja Online</title>
</head>
<body>
	<!-- Página do produto -->
	<div class="produto">
		<h1>Produto Incrível</h1>
		<p class="preco">R$ 99,90</p>
		<button onclick="adicionarCarrinho()">Adicionar ao Carrinho</button>
	</div>
	
	<!-- Carrinho de compras -->
	<div id="carrinho" style="display: none;">
		<h2>Finalizar Compra</h2>
		<form id="form-checkout">
			<input type="text" name="nome" placeholder="Nome completo" required>
			<input type="email" name="email" placeholder="E-mail" required>
			
			<!-- Dados de rastreamento ocultos -->
			<input type="hidden" data-utmtrackjs="utm_source" name="utm_source">
			<input type="hidden" data-utmtrackjs="utm_medium" name="utm_medium">
			<input type="hidden" data-utmtrackjs="utm_campaign" name="utm_campaign">
			<input type="hidden" data-utmtrackjs="gclid" name="gclid">
			<input type="hidden" data-utmtrackjs="fbclid" name="fbclid">
			
			<button type="submit">Finalizar Compra</button>
		</form>
	</div>

	<script src="utmtrack.js"></script>
	<script>
		// Configura para rastrear campanhas
		UTMTrackJS.configure({
			updateWithLatest: true,
			maxDataAge: 14 * 24 * 60 * 60 * 1000 // 14 dias
		});
		
		function enviarEventoTracking(evento) {
			const utms = UTMTrackJS.getAllUtms() || {};
			
			// Google Analytics 4
			if (typeof gtag !== 'undefined') {
				gtag('event', evento, {
					utm_source: utms.utm_source,
					utm_medium: utms.utm_medium,
					utm_campaign: utms.utm_campaign,
					gclid: utms.gclid
				});
			}
			
			// Facebook Pixel
			if (typeof fbq !== 'undefined') {
				fbq('track', 'AddToCart', {
					utm_source: utms.utm_source,
					utm_campaign: utms.utm_campaign
				});
			}
			
			console.log(`Evento ${evento} enviado com UTMs:`, utms);
		}
		
		function adicionarCarrinho() {
			document.getElementById('carrinho').style.display = 'block';
			enviarEventoTracking('add_to_cart');
		}
		
		// Processa o checkout
		document.getElementById('form-checkout').addEventListener('submit', function(e) {
			e.preventDefault();
			enviarEventoTracking('purchase');
			alert('Compra finalizada com sucesso! UTMs foram registradas para análise.');
		});
	</script>
</body>
</html>

Dicas de Implementação

Timing da Configuração

// CORRETO: A biblioteca se inicializa automaticamente
// Você pode configurar a qualquer momento após o carregamento

// Opção 1: Configuração imediata
UTMTrackJS.configure({
	updateWithLatest: true,
	maxDataAge: 14 * 24 * 60 * 60 * 1000 // 14 dias
});

// Opção 2: Aguardar DOM estar pronto (se necessário)
document.addEventListener('DOMContentLoaded', function() {
	UTMTrackJS.configure({
		updateWithLatest: true,
		customUtmKeys: ['param_personalizado']
	});
});

// Opção 3: Verificar se existe antes de usar
if (window.UTMTrackJS) {
	UTMTrackJS.configure({...});
}

Teste e Debug

// Verificar se UTMs foram capturadas
console.log('UTMs salvas:', UTMTrackJS.getAllUtms());

// Ver estatísticas de storage
console.log('Storage stats:', UTMTrackJS.getStorageStats());

// Verificar configuração
console.log('Config atual:', UTMTrackJS.getConfig());

// Ver chaves ativas (inclui personalizadas)
console.log('Chaves ativas:', UTMTrackJS.getDebugInfo().supportedKeys);

// Testar com URLs simuladas
// http://localhost/?utm_source=teste&utm_campaign=debug

Problemas Comuns

UTMs não são capturadas: Verifique se a biblioteca está carregada antes de tentar usá-la
Dados desaparecem: Verifique a configuração de maxDataAge ou se o localStorage está sendo limpo
Parâmetros personalizados não funcionam: Configure com customUtmKeys na configuração inicial ou use addUtmKeys() após inicialização
SPA não funciona: A biblioteca monitora mudanças de URL automaticamente, mas você pode forçar recaptura com UTMTrackJS.recapture()
Elementos não são preenchidos: Verifique se o atributo data-utmtrackjs está correto e se o valor corresponde a um parâmetro válido

Licença

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

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
LICENSE		LICENSE
README.md		README.md
utmtrack.js		utmtrack.js
utmtrack.min.js		utmtrack.min.js

License

gmasson/utmtrackjs

Folders and files

Latest commit

History

Repository files navigation

UTMTrackJS v0.9.5

Sem Dependências

Segurança e Confiabilidade

Sumário

Instalação

Método 1: Download Direto

Método 2: CDN

Como Funciona

Cenário de exemplo

Configurações Básicas

Padrão (pré-definida na biblioteca, portanto não precisa incluir)

Dados Permanentes (Nunca Expiram)

Captura apenas as primeiras UTMs acessadas

Adicionar Parâmetros Personalizados

Principais Funcionalidades

UTMTrackJS.getUtm(key)

UTMTrackJS.getConfig()

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

UTMTrackJS.getAllUtms()

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

UTMTrackJS.cleanExpiredData()

UTMTrackJS.getDebugInfo()

UTMTrackJS.purge()

UTMTrackJS.refresh()

UTMTrackJS.supportedKeys

UTMTrackJS.version

Outros Métodos e Recursos (não destacados anteriormente)

UTMTrackJS.disableUrlMonitoring()

UTMTrackJS.getStorageStats()

UTMTrackJS.refresh()

UTMTrackJS.customEvents

loggingEnabled (configuração)

Eventos Customizados

Configurações Avançadas

Definir Dados Manualmente

Configuração de Expiração de Dados

Configuração Personalizada

Gerenciar Parâmetros Personalizados

Forçar Recaptura

Exemplos de Uso

Mais Simples Possível

Preenchimento Automático no HTML

Landing Page com formulário

Salvando eventos no Google Analytics e Pixel

Dicas de Implementação

Timing da Configuração

Teste e Debug

Problemas Comuns

Licença

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Languages

`UTMTrackJS.getUtm(key)`

`UTMTrackJS.getConfig()`

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

`UTMTrackJS.getAllUtms()`

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

`UTMTrackJS.cleanExpiredData()`

`UTMTrackJS.getDebugInfo()`

`UTMTrackJS.purge()`

`UTMTrackJS.refresh()`

`UTMTrackJS.supportedKeys`

`UTMTrackJS.version`

`UTMTrackJS.disableUrlMonitoring()`

`UTMTrackJS.getStorageStats()`

`UTMTrackJS.refresh()`

`UTMTrackJS.customEvents`

`loggingEnabled` (configuração)