Pixels e eventos de sites

O pixel do MailLeader registra visitas, cliques e eventos personalizados em sites que você administra. Ele só inicia a coleta depois do consentimento de rastreamento no navegador.

1. Cadastre um site

Na API autenticada, use POST /api/v1/marketing/sites:

{
  "name": "Site institucional",
  "active": true,
  "origins": ["https://www.empresa.com.br"],
  "eventNames": ["demo.requested", "pricing.selected"],
  "attributionKeys": ["utm_source", "utm_campaign", "gclid"],
  "retentionDays": 90
}

As origens são exatas: protocolo, domínio e porta quando houver. Não inclua caminho, query, fragmento ou curinga. É possível cadastrar até 30 origens. O prazo de retenção pode ser 30, 90, 180 ou 365 dias. eventNames define quais nomes de evento personalizado serão aceitos para aquele site, com até 30 nomes. Cada nome deve corresponder a ^[a-z][a-z0-9_.-]{0,59}$; nomes reservados como page.viewed, link.clicked, visitor.identified, site.custom e lead.created não podem ser cadastrados. Nomes que indiquem pagamento ou dados sensíveis também são recusados: eventos de pagamento devem ser confirmados no servidor, não declarados pelo navegador.

Para editar, use PATCH /api/v1/marketing/sites/{siteId} e inclua a revision atual. Se outra aba tiver salvado antes, a API responde conflito; recarregue o site e reaplique a alteração.

2. Instale o script oficial

Consulte GET /api/v1/marketing/sites/{siteId}/installation para obter o endereço oficial do script e o ID do site. O snippet instalado no site é:

Use o endereço e o UUID apresentados no painel para o seu ambiente. Instale o mesmo snippet nas páginas que deseja medir. O script é carregado do MailLeader; não é necessário copiar o código do SDK para o site.

3. Peça consentimento antes de coletar

O script não inicia sessão nem envia métricas até receber consentimento explícito. Integre o callback da sua plataforma de consentimento:

O evento de consentimento aceito inicia a sessão e registra a página atual. Navegações posteriores em aplicações de página única podem ser notificadas com MailLeaderPixel.page(); o SDK também acompanha mudanças de histórico do navegador.

4. Eventos automáticos e personalizados

Com consentimento ativo, o SDK registra page.viewed e cliques em links HTTP/HTTPS. Para excluir um link, marque-o com data-ml-no-track:

Os eventos de clique guardam somente a origem do destino, como https://wa.me; não guardam caminho, query, fragmento nem texto do link.

Para registrar um evento personalizado, habilite primeiro seu nome na configuração do site e depois chame track:

O payload aceita qualquer JSON válido, incluindo objetos e arrays aninhados, até 2 KB serializados por evento. A API não filtra propriedades pelo nome ou pelo conteúdo. Os dados personalizados são armazenados no histórico do site e podem ser enviados a webhooks; não envie senhas, tokens ou dados que não devam ser registrados.

Os tipos registrados são page.viewed, link.clicked e site.custom. visitor.identified é emitido pelo servidor MailLeader quando um contato é identificado com segurança; não pode ser declarado pelo navegador.

5. Associar atividade a um lead

Se a pessoa enviar um formulário MailLeader incorporado no mesmo site e a sessão de pixel tiver consentimento, o cadastro aceito associa os eventos seguintes ao contato. Eventos anteriores à identificação continuam anônimos. A associação não comprova que a pessoa controla o endereço de e-mail.

Para sites com login próprio, faça a identificação no servidor:

No navegador, obtenha const context = await MailLeaderPixel.context() e envie context.token ao seu servidor autenticado.

Seu servidor verifica a sessão do usuário e consulta POST /api/v1/marketing/sites/{siteId}/identify-token, autenticando-se com a chave de API. Envie { "sessionToken": "TOKEN_DA_SESSAO_DO_PIXEL", "contactId": "UUID_DO_CONTATO" }.

Devolva o token temporário à página e chame await MailLeaderPixel.identify(token).

O token temporário expira em cinco minutos e só pode ser usado uma vez. Nunca exponha a chave de API do MailLeader no navegador.

6. Marcadores de campanha

O site pode coletar utm_source, utm_medium, utm_campaign, utm_term, utm_content, gclid, fbclid e msclkid quando habilitados em attributionKeys (até oito chaves). Marcadores UTM são validados; identificadores de anúncios são armazenados como hash por site. Outros parâmetros de URL não são enviados. Cada valor recebido pode ter até 120 caracteres.

Consultar resultados

Rota autenticada	O que retorna
`GET /api/v1/marketing/sites`	Sites cadastrados na conta.
`GET /api/v1/marketing/sites/{siteId}/analytics`	Totais dos últimos 30 dias, páginas, canais, UTM, eventos recentes e estado da retenção.
`GET /api/v1/marketing/contacts`	Contatos, com busca, tag e pontuação mínima.
`GET /api/v1/marketing/contacts/{contactId}`	Perfil e atividade consolidada do contato.
`GET /api/v1/marketing/contacts/{contactId}/events`	Eventos do contato.

Visitas e cliques são eventos detectados, não prova de atividade humana. Proxies, scanners e bloqueios do navegador podem afetar os números. Aberturas e cliques em e-mails são eventos separados; consulte Webhooks.

Referência do SDK

Método	Para que serve
`consent(true)`	Autoriza a coleta e inicia a sessão.
`consent(false)` ou `reset()`	Revoga a sessão e limpa os identificadores locais.
`page()`	Registra uma página em navegação controlada pelo site.
`track(nome, dados)`	Envia evento personalizado habilitado e JSON de até 2 KB.
`context()`	Obtém o contexto temporário para identificação no servidor.
`identify(token)`	Associa eventos seguintes ao contato usando token de uso único.
`flush()`	Solicita o envio da fila local de eventos.

Pixels e eventos de sites

1. Cadastre um site#

2. Instale o script oficial#

3. Peça consentimento antes de coletar#

4. Eventos automáticos e personalizados#

5. Associar atividade a um lead#

6. Marcadores de campanha#

Consultar resultados#

Referência do SDK#