Introdução - Regras de tag

Uma regra de tag transforma uma interação no site (um clique, o envio de um formulário, uma rolagem) em um evento que o TagServer mede e encaminha. Todo subdomínio já nasce com regras padrão habilitadas, como page_view e form_submit, então a tag mede o básico desde o primeiro dia. As regras que você cria descrevem as interações do seu negócio: o clique no botão de compra, o lead que preencheu o formulário certo. Um subdomínio sem nenhuma regra habilitada não tem o que instrumentar.

Regra e destino são metades diferentes

A regra e o destino fazem trabalhos distintos, em lugares distintos:

Medir uma conversão de ponta a ponta precisa das duas. Uma regra sem destino captura eventos que não chegam a nenhuma plataforma; um destino sem regra fica esperando um evento que ninguém dispara.

Onde as regras vivem

Uma regra pertence a um subdomínio. Cada subdomínio guarda e serve as próprias regras, então dois sites diferentes na mesma conta não compartilham regras. O nome de uma regra é único dentro do subdomínio.

A tag instalada na página busca a configuração em <subdomínio>/tag e envia os eventos em <subdomínio>/collect: é o mesmo endereço nos dois sentidos.

No app, as regras ficam em Rastreamento › Regras. O item só aparece para contas com o recurso WebTracking, que não vem por padrão numa conta nova; sem ele, o item fica oculto. A tela começa pela escolha do subdomínio e mostra as regras dele.

O que você muda no painel vai para um rascunho: criar, editar, pausar, reativar e excluir não mexem no site até você clicar em Publicar. A publicação leva o rascunho inteiro de uma vez, e o site passa a usá-lo no próximo carregamento de página. O passo a passo está em Criar e publicar regras.

Além do painel, você gerencia as regras pela API HTTP ou pedindo a um assistente de IA conectado ao MCP do TagServer, que tem as ferramentas list_tag_rules, create_tag_rule, upsert_tag_rule e delete_tag_rule.

O que uma regra tem

Pense numa regra em três partes, nesta ordem:

1. Um gatilho: quando a regra dispara. Pode ser simples ("todo clique em .cta") ou composto ("todo clique em .cta, só nas páginas de checkout, uma vez por sessão"). Os envelopes restringem o gatilho a certas páginas, a uma vez por sessão e assim por diante.
2. Um nome de evento: como a interação se chama, em snake_case minúsculo, com até 40 caracteres, no padrão do GA4: begin_checkout, generate_lead, file_download.
3. As capturas: quais parâmetros o evento leva junto. Cada captura é uma pequena receita que colhe um valor da página: o texto de um elemento, um atributo, um parâmetro da URL, um valor convertido para número.

Opcionalmente, você marca a regra como conversão ("Conta como conversão"), e o evento dela entra em Conversões nos relatórios do site. A marca vem desligada.

Todo evento já sai com três parâmetros base sem você pedir: href, page_title e page_referrer (este último só quando a página tem referrer). Uma captura com um desses nomes substitui o valor base naquele evento.

Os detalhes de cada gatilho e de cada captura estão em Gatilhos e capturas.

Como a tag executa as regras

Ao carregar a página, a tag busca as regras habilitadas da publicação em vigor do subdomínio e liga uma por uma, na ordem em que foram criadas. Uma regra pausada continua salva, mas não é entregue à tag; por isso pausar é diferente de excluir, e serve para interromper a medição sem perder a configuração. No painel, a ação é "Pausar" (e "Reativar" para voltar), e ela também só vale no site depois de publicada.

Se o navegador do visitante envia o sinal Global Privacy Control (GPC), a tag não busca as regras, não liga nenhuma e não envia eventos. Esse visitante não é medido, por decisão de projeto.

A ordem de criação e a forma como as capturas rodam decidem o que falha, e até onde a falha se espalha:

Os motivos que fazem a tag pular uma regra sozinha são tipo desconhecido, campo faltando, regex que não compila e JavaScript com erro de sintaxe; cada regra pulada deixa um aviso no console do navegador (tgsr: skipping rule "<nome>": ...). Um seletor inválido dentro de uma captura também fica restrito à própria regra: o erro só acontece quando ela dispara, e cai no segundo aviso, porque descarta o evento dela.

O painel de cada regra tem um bloco "Saúde" com os achados daquela regra (seletor inválido, captura que não fecha, ordem dos envelopes); sem achado, ele mostra "Nada a apontar". A visão por subdomínio fica em Rastreamento › Visão geral: no card "Subdomínios e regras", a coluna "Situação das regras" mostra quantas regras estão medindo e quantas não estão, incluindo as "apagadas" pelo seletor inválido de uma regra anterior. As pausadas não entram em nenhuma das duas contas, e a conta é feita sobre o rascunho, então uma correção ainda não publicada já aparece ali. Pausar a regra causadora e publicar religa as seguintes, porque regra pausada não é entregue à tag. Esse diagnóstico analisa a definição das regras (se cada uma funcionaria), e não um registro de disparos reais: não existe hoje uma consulta de "essa regra disparou".

A configuração é servida com cache de um minuto, então uma publicação nova pode levar até 60 segundos para chegar aos navegadores que já carregaram a configuração anterior.

Falha da tag nunca quebra a página

Por decisão de projeto, uma falha ao buscar ou ler a configuração (erro de rede, resposta malformada) é silenciosa: a tag desiste e não interrompe nada no site. Uma regra pulada deixa só o aviso no console do navegador. O visitante não vê erro, e por isso um problema de medição aparece para você como dado que não chega.

Veja também

• Criar e publicar regras: o painel passo a passo, do modelo à publicação
• Gatilhos e capturas: os gatilhos, as capturas e como combiná-los
• Regras de tag na API: o contrato HTTP dos endpoints, para automação
• Claude via MCP: gerenciar regras pedindo a um assistente de IA
• Introdução a Pixels: a outra metade, para onde o evento capturado é enviado