Gatilhos e capturas
Numa regra de tag, o gatilho diz "quando" o evento sai e as capturas dizem "com qual valor" cada parâmetro sai. Os nomes abaixo são os que o editor mostra; para o formato JSON exato, veja Regras de tag na API.
Gatilhos
Você escolhe o gatilho de origem no campo "Dispara quando"; a tabela segue a ordem do editor.
| Gatilho | Dispara quando | Você configura | Entrega | type |
|---|---|---|---|---|
| Evento em elemento | um evento do navegador acontece em um elemento que casa com o seletor CSS, inclusive elementos inseridos depois do carregamento | o seletor e o evento (ex. click, submit, change) | elemento e evento | ElementEvent |
| Página carregada | uma vez, quando o DOM fica pronto (na hora, se já estiver pronto) | nada | nada | PageReady |
| Evento na janela | um evento acontece na janela, ex. scroll, resize | o evento | evento | WindowEvent |
| Temporizador | a cada intervalo; navegadores estrangulam timers em abas de fundo | o intervalo, de 1 segundo a 1 hora (1000 a 3600000 ms) | nada | Timer |
| Profundidade de rolagem | a página é rolada até cada porcentagem, uma vez por porcentagem por carregamento; o evento carrega detail.threshold_pct | 1 a 10 porcentagens, cada uma de 1 a 100 | evento | ScrollDepth |
| Tempo de atenção | o visitante acumula cada duração, uma vez por duração por carregamento; o evento carrega detail.threshold_s e detail.engaged_ms | 1 a 10 durações em segundos, de 1 a 3600 | evento | TimeEngaged |
| Elemento visível | o elemento entra na área visível em pelo menos a fração configurada, uma vez por elemento por carregamento | o seletor e a fração visível, maior que 0 e até 1 (padrão 0,5) | elemento | ElementVisible |
Tempo de atenção conta só os segundos com a página visível (aba em segundo plano não conta); o Temporizador conta o relógio.
As listas de Profundidade de rolagem e Tempo de atenção precisam ser estritamente crescentes: um valor repetido ou fora de ordem é recusado ao salvar.
Envelopes
Um envelope não dispara sozinho: ele envolve outro gatilho e muda quando ele dispara.
| Envelope | O que faz | Você configura | type |
|---|---|---|---|
| Uma vez por | reduz o gatilho interno ao primeiro disparo dentro de um escopo | o escopo | Once |
| Só nas páginas que casam | deixa o gatilho interno disparar só quando a URL (location.href) casa com o padrão; reavaliado quando o site troca de página sem recarregar (SPA) | o padrão | OnPage |
| Filtro em JavaScript | roda um trecho de JavaScript (corpo de (element, event) => ...) a cada disparo do gatilho interno, antes de capturar e enviar; devolver false veta aquele disparo | o código | SideEffect |
Escopos de Uma vez por:
| Escopo | Primeiro disparo por | Onde é lembrado |
|---|---|---|
| página | carregamento | em memória; recarregar zera |
| elemento | elemento casado | em memória; exige gatilho interno que entregue elemento (Evento em elemento ou Elemento visível), senão o servidor recusa a regra |
| sessão | sessão da aba | na aba; fechar a aba zera |
| usuário | navegador | no navegador; persiste entre visitas |
Os escopos sessão e usuário são lembrados pelo nome da regra: renomear a regra zera a contagem dela.
Aviso
A ordem dos envelopes muda o resultado. De fora para dentro: Uma vez por, Só nas páginas que casam, Filtro em JavaScript e, por último, o gatilho de origem.
Certo: Uma vez por (sessão) > Só nas páginas que casam (/checkout) > Evento em elemento. A regra espera um clique no checkout e então gasta o disparo único.
Trocado: Só nas páginas que casam > Uma vez por > Evento em elemento. O disparo único é gasto no primeiro clique em qualquer página do site, antes de a página ser checada; com escopo sessão ou usuário, a regra pode nunca enviar nada naquele navegador. Da mesma forma, Uma vez por dentro de Filtro em JavaScript faz um disparo vetado pelo filtro consumir a cota.
A API aceita qualquer ordem. O editor detecta a ordem errada, mostra o aviso "A ordem importa aqui" com a consequência e oferece o botão "Corrigir ordem", que só muda a regra se você pedir. O bloco "Saúde" do painel da regra também aponta o caso.
Receitas comuns
| O que você quer medir | Como montar |
|---|---|
| Clique no botão de compra, uma vez por sessão, só no checkout | Uma vez por (sessão) > Só nas páginas que casam (/checkout) > Evento em elemento (button.comprar, click) |
| Envio de um formulário de contato | Evento em elemento (form#contato, submit) |
| Leitura de um artigo | Tempo de atenção (30, 60, 180 s) |
| Download de arquivo | Evento em elemento (a[href$=".pdf"], click) |
| Visualização de um bloco de preços | Elemento visível (#planos) |
| Rolagem da página | Profundidade de rolagem (25, 50, 75, 100) |
Capturas
Cada parâmetro do evento tem a sua captura: um passo ou uma cadeia de passos, da esquerda para a direita, em que cada passo recebe o que o anterior produziu. O primeiro passo recebe o elemento que o gatilho entregou (ou nada).
A ordem que evita estouro:
- Comece no elemento ou numa fonte da página.
- Ande pelo DOM, se o valor não está no próprio elemento.
- Leia e transforme o valor.
Sem elemento, os passos que leem elemento não produzem valor; sem evento, Propriedade do evento não produz valor. A paleta do editor mostra esses passos desabilitados com o motivo ("Neste ponto a cadeia não carrega um elemento" ou "Este disparador não entrega um evento").
Do elemento
Recebem elemento, devolvem valor.
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Atributo do elemento (Attr) | o valor de um atributo | o atributo (ex. data-preco) | o atributo não existe |
Texto visível (Text) | o texto do elemento, sem espaços nas pontas | nada | o texto está vazio |
Valor do campo (Value) | o valor de um controle de formulário | nada | o elemento não tem valor |
Domínio do link (Hostname) | o domínio de um link; útil para separar link externo | nada | o elemento não é um link |
Campo do formulário (Field) | o valor do campo com esse nome no formulário | o campo (ex. email) | o formulário não tem esse campo |
Da página
Ignoram o que vem antes, devolvem valor.
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Parte da URL (Location) | uma parte da URL da página | a parte | |
Parâmetro da URL (UrlParam) | o valor de um parâmetro da query | o parâmetro (ex. utm_source, sku) | o parâmetro não está na URL |
Dado do documento (DocumentProp) | um dado do documento | o dado | |
Dado da janela (WindowProp) | um dado da janela | o dado | |
Valor fixo (Constant) | o valor que você escreve; útil como último caminho de uma Alternativa | o valor (texto, número ou verdadeiro/falso) |
- Partes da URL: URL completa (
href), caminho (pathname), host com porta (host), domínio (hostname), query string (search), fragmento (hash), origem (origin). - Dado do documento:
title,referrer,readyState,visibilityState,characterSet,contentType. - Dado da janela:
scrollX,scrollY,innerWidth,innerHeight,outerWidth,outerHeight,devicePixelRatio.
Do evento
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Propriedade do evento (EventProp) | um dado do evento do navegador | caminho com pontos (ex. detail.threshold_pct) | o gatilho não entrega evento, ou o caminho não existe |
Navegar no DOM
Recebem elemento, devolvem elemento.
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Sobe até o ancestral (Closest) | o ancestral mais próximo que casa com o seletor | seletor CSS | nenhum ancestral casa |
Desce até o descendente (Find) | o descendente que casa com o seletor | seletor CSS | nenhum descendente casa |
Sobe um nível (Parent) | o elemento pai | nada | o elemento não tem pai |
Condição
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Só se casar com (WhenMatches) | deixa o valor passar se casar | expressão regular | o valor não casa |
Só se for igual a (WhenEquals) | deixa o valor passar se for igual | valor | o valor é diferente (igualdade estrita) |
Transformar
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Remove espaços das pontas (Trim) | o valor sem espaços nas pontas | nada | |
Minúsculas (Lowercase) | o valor em minúsculas | nada | |
Converte para número (ToNumber) | o valor como número | nada | o valor não é numérico |
Recorta com expressão (RegexCapture) | o trecho capturado pela expressão | expressão e grupo (0 a 9, padrão 1) | a expressão não casa ou o grupo não existe |
Corta no tamanho (Truncate) | o valor cortado no tamanho | tamanho, de 1 a 500 | |
Vira slug (Slug) | o valor sem acentos, em minúsculas, com o que não é letra ou número trocado por _ e _ aparado das pontas | nada | o resultado fica vazio |
Decodifica da URL (UrlDecode) | o valor com a codificação de URL desfeita | nada | o escape está malformado |
Vira hash SHA-256 (Hash) | o valor como hash SHA-256, calculado no navegador: o dado pessoal nunca é enviado em claro. Para e-mail, telefone ou CPF, use depois de Remove espaços e Minúsculas, para o mesmo valor dar sempre o mesmo hash. Sem este passo, o parâmetro é gravado como veio | nada |
Combinar
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
Alternativa (Or) | tenta os caminhos em ordem contra o mesmo valor de entrada; vence o primeiro que produzir valor. Ex.: o id do produto vem do atributo do card ou, se não houver, do parâmetro sku da URL | 2 a 8 caminhos | todos os caminhos falham |
Escotilha
| Passo | Devolve / faz | Configura | Não produz valor quando |
|---|---|---|---|
JavaScript (Script) | o resultado do código | corpo de (value, state) => resultado | o código devolve undefined |
Parâmetros que toda regra já envia
A tag acrescenta a todo evento href (URL da página), page_title (título) e page_referrer (só quando há referrer); eles não contam como capturas da regra. Uma captura com o mesmo nome sobrepõe o valor base naquele evento, e o editor avisa no parâmetro: "Sobrepõe o parâmetro que toda regra já envia" (o aviso cobre href e page_title). Se essa captura não produzir valor, o parâmetro sai do evento: o valor base não volta.
Halt, estouro e cadeia que termina em elemento
| O que acontece | Efeito no evento | Exemplo |
|---|---|---|
| Halt: um passo não produz valor e a cadeia para | o parâmetro é omitido; o evento é enviado | produto sem preço na página gera evento sem price |
| Estouro: um passo levanta erro | o evento inteiro é descartado, sem aviso, e não só aquele parâmetro | Parte da URL > Atributo do elemento |
| A cadeia termina em elemento (último passo é de Navegar no DOM) | o evento é enviado com o parâmetro vazio no analytics; o editor avisa no parâmetro e pede para fechar com um passo que produza texto ou número | Sobe até o ancestral sem um passo de leitura depois |
Aviso
O servidor aceita passos incompatíveis. Ele não checa a compatibilidade entre passos, e só três passos estouram ao receber um valor em vez de elemento: Atributo do elemento, Sobe até o ancestral e Desce até o descendente. Os outros passos de elemento (Texto visível, Valor do campo, Domínio do link, Campo do formulário, Sobe um nível) só deixam de produzir valor. No editor visual, a paleta não oferece um passo onde ele estouraria; se a cadeia vier pronta (JSON, API), o parâmetro mostra o problema, mas o salvamento não é bloqueado.
Aviso
JavaScript com erro de sintaxe é aceito ao salvar. Vale para Filtro em JavaScript e para o passo JavaScript: o servidor só limita o tamanho, e no navegador a tag pula aquela regra. JavaScript em regra também exige unsafe-eval na política de segurança de conteúdo (CSP) da página, e o código fica legível por qualquer pessoa, porque a configuração das regras é pública.
A faixa "Confira na página" do editor calcula o valor de cada parâmetro contra a página inspecionada, para você ver onde a cadeia não produz valor antes de publicar.
Seletor inválido
A tag liga as regras no navegador em ordem de criação. Um seletor CSS com sintaxe inválida no gatilho (Evento em elemento, Elemento visível) levanta erro ao ligar a regra e interrompe a instrumentação das regras criadas depois dela; as criadas antes continuam medindo. Na captura (Sobe até o ancestral, Desce até o descendente), o seletor inválido só estoura quando a regra dispara: descarta os eventos daquela regra e não afeta as outras.
Cuidado
O servidor não valida CSS, então um seletor inválido passa pela API. O editor recusa salvar e avisa que o seletor interrompe a instrumentação das regras criadas depois. As regras afetadas entram na contagem de regras que não estão medindo em Rastreamento › Visão geral (card "Subdomínios e regras", coluna "Situação das regras"); a lista de regras não as marca. Pausar a regra culpada e publicar devolve as outras, porque regra pausada não é servida.
Limites
Valores acima destes são recusados ao salvar.
| Limite | Valor |
|---|---|
| Regras por subdomínio | 200 |
| Parâmetros (capturas) por regra | 32 |
| Passos por captura | 32 |
| Profundidade de uma captura | 8 |
| Profundidade do gatilho | 8 níveis, contando o gatilho de origem |
| Caminhos numa Alternativa | 2 a 8 |
| Tamanho de uma regra | 16 KiB |
| Seletor CSS | 512 bytes |
| Padrão (expressão regular) | 256 bytes |
| Código JavaScript | 8 KiB |
Os padrões de Só nas páginas que casam, Só se casar com e Recorta com expressão são compilados no servidor com sintaxe mais restrita que a do navegador: sem lookaround e sem backreference. Um padrão que funciona no console do navegador pode ser recusado ao salvar.
Veja também
- Introdução a Regras de tag: o conceito e como a tag executa as regras
- Regras de tag na API: o formato JSON exato
- Solução de Problemas: quando o evento não chega