tracking

Endpoints públicos de pixel e redirect para rastreamento de abertura e clique embutidos nos e-mails de campanha enviados.

Caminho de origem: libraries/campaign/src/services/campaign-tracking.service.ts

Arquivo do módulo: campaign.module.ts

Introdução

O submódulo Tracking implementa os dois mecanismos clássicos de analytics de e-mail — rastreamento de abertura e rastreamento de clique — através de tokens assinados e de propósito único armazenados em `campaign_tracking`. Ao montar o HTML de uma mensagem durante o envio, o CampaignEmailWorkerService chama `generateOpenToken` uma vez por mensagem e injeta um GIF transparente de 1×1 (tag `<img>` apontando para `/campaign/track/open/:token`) logo antes da tag `</body>` de fechamento — ou anexado ao final do HTML se nenhum `</body>` for encontrado. Ele varre separadamente cada `<a href="...">` no HTML renderizado (pulando o próprio link de descadastramento, links apenas de âncora e links `mailto:`) e reescreve cada destino através de `generateClickToken`, de modo que cada link de saída em um e-mail de campanha enviado seja individualmente rastreável de volta àquela mensagem e destinatário exatos.

O `GET /campaign/track/open/:token` é o endpoint de pixel: ele registra a abertura (IP, user-agent, timestamp) apenas no primeiro acesso — o `tracked_at` não nulo é a garantia de idempotência contra clientes que fazem prefetch de imagens ou aberturas repetidas contabilizando em dobro — e então sempre retorna o mesmo GIF inline de 1×1 com `Cache-Control: no-store` para que os clientes de e-mail nunca façam cache de um pixel obsoleto. Nesse primeiro acesso, ele também grava um evento de campanha `open` e incrementa o contador `total_opened` da campanha. O `GET /campaign/track/click/:token` segue o mesmo padrão de registro apenas-no-primeiro-acesso para cliques (`total_clicked`, um evento `click` com a URL de destino original em metadata) e então emite um redirect HTTP para o `target_url` original que foi capturado quando o link foi reescrito — recorrendo a `/` se o token for desconhecido, para que um link de rastreamento quebrado ou expirado nunca deixe o destinatário em um beco sem saída.

Ambos os caminhos de registro são envolvidos em seu próprio try/catch com logging interno em vez de lançar exceção, já que esses endpoints são invocados por clientes de e-mail e navegadores sem expectativas de tratamento de erro — uma falha de rastreamento nunca deve quebrar a renderização da imagem ou o redirect.

Endpoints HTTP

2 endpoints

Pixel de rastreamento de abertura. Registra um evento de abertura (apenas no primeiro acesso) e sempre retorna um GIF transparente de 1x1. Embutido como uma tag <img> no HTML do e-mail enviado.

Params: token (string)

Redirect de rastreamento de clique. Registra um evento de clique (apenas no primeiro acesso) e então redireciona para a URL de destino original, ou para "/" se o token for desconhecido.

Params: token (string)