Regras de tag

Uma regra de tag faz uma interação no site virar um evento. Ela vive sob /track, pertence a um servidor de rastreamento identificado pelo Host da requisição e é gerenciada com um token de conta que tenha a feature WebTracking; envelope e códigos seguem convenções e erros.

Uma regra tem um trigger, que diz quando ela dispara, e extractors, que dizem quais parâmetros o evento leva. O trigger é uma árvore de nós.

Endpoints

A feature WebTracking não vem por padrão (uma conta nova recebe só Chat). Sem ela, mesmo com token válido, as quatro rotas de /track/rules respondem 403 em texto puro com o corpo Feature disabled: WebTracking; níveis e features em autenticação.

PUT é a forma de alterar uma regra. Não existe PATCH: o corpo do PUT é a definição completa e substitui a anterior.

As quatro rotas de /track/rules editam um rascunho. O site só recebe as regras depois de um POST /track/versions; ver Rascunho e publicação.

Identificação do servidor

O servidor alvo sai do Host/TLS da requisição; não existe parâmetro de servidor.

• A chamada vai ao domínio do próprio servidor de rastreamento, resolvido do Host da requisição e do nome do servidor TLS (SNI). A URL base destas rotas é https://<server_name>, por exemplo https://track.exemplo.com.br/track/rules, e não a base do resto da API. Chamar /track/rules num domínio que não é servidor da conta dá 404.
• Se Host e nome do servidor TLS vierem e divergirem, a resposta é 400 em texto puro, corpo literal Host header does not match TLS server name.
• Nas rotas de /track/rules, o servidor ainda precisa pertencer à conta do token; sem servidor para aquele Host e conta, 404 (Error 404: server not found). O público GET /track/tag resolve o servidor só pelo Host, sem cláusula de conta, com o mesmo 404 quando não há servidor.

Corpo de uma regra

No PUT, o corpo não tem rule_name: o nome vem do caminho {rule_name} e passa pela mesma validação. No PUT e no DELETE, um nome com espaço ou acento vai percent-encoded nesse segmento da URL. A substituição é completa: enabled e conversion omitidos voltam aos padrões, extractors omitido vira vazio, e nada do corpo anterior é preservado.

O tag do navegador acrescenta a todo evento três parâmetros base: href, page_title e page_referrer (este só quando document.referrer não é vazio). Uma chave de mesmo nome em extractors sobrescreve o valor base naquele evento.

trigger

Cada nó do trigger tem um campo type; campos desconhecidos são recusados. Sete tipos são fontes: disparam sozinhos e ficam nas folhas da árvore.

Três tipos são envelopes: cada um carrega um inner, que é outro trigger.

O per de Once é um de:

• Page: por carregamento de página, em memória.
• Element: por elemento casado. Exige um inner que entregue elemento (que termine em ElementEvent ou ElementVisible); caso contrário, o servidor recusa com 400.
• Session: por sessão de aba, em sessionStorage, com chave no nome da regra.
• User: por perfil do navegador, em localStorage, com chave no nome da regra.

Exemplo: o clique no botão de compra, só no checkout, uma vez por sessão.

{
  "type": "Once",
  "per": "Session",
  "inner": {
    "type": "OnPage",
    "regex": "/checkout(/|$)",
    "inner": {
      "type": "ElementEvent",
      "selector": "button.buy",
      "event": "click"
    }
  }
}

extractors

extractors é um objeto: a chave é o nome do parâmetro do evento, o valor é uma expressão. Uma expressão é uma de duas coisas:

• um nó, um objeto com type;
• uma cadeia, um array de expressões avaliadas da esquerda para a direita, cada passo consumindo a saída do anterior.

Qualquer passo pode haltar, ou seja, parar sem produzir valor. A cadeia para e o parâmetro é omitido do evento. É o comportamento normal: um atributo ausente não é erro.

Os nós, por família:

Leem o elemento:

Leem o contexto:

Andam pelo DOM:

Filtram:

Transformam:

Combinam:

Exemplo: o id do produto, com um caminho alternativo, e o preço convertido para número.

{
  "product_id": {
    "type": "Or",
    "branches": [
      [
        { "type": "Closest", "selector": "[data-product]" },
        { "type": "Attr", "name": "data-product" }
      ],
      { "type": "UrlParam", "name": "sku" }
    ]
  },
  "price": [
    { "type": "Find", "selector": ".price" },
    { "type": "Text" },
    { "type": "ToNumber" }
  ]
}

Limites

Validados na escrita; estourar é 400 no envelope.

O teto de 200 é checado excluindo a própria regra: um PUT sobre uma regra que já existe passa mesmo com o servidor no teto.

Os regex de OnPage, WhenMatches e RegexCapture seguem um dialeto que é subconjunto estrito do JavaScript: sem lookaround e sem backreference. Um padrão que funciona no navegador pode ser recusado aqui.

O servidor não interpreta CSS: um seletor sintaticamente inválido passa pela API e só falha no navegador.

Rascunho e publicação

POST, PUT e DELETE em /track/rules mudam o rascunho do servidor. O GET /track/tag entrega ao navegador a publicação em vigor, que só muda com uma publicação nova.

GET /track/rules devolve o rascunho e o compara com o que está no ar:

• cada regra traz publish_state: new (não está na publicação em vigor), published (igual à publicada) ou modified;
• deleted_rules lista as regras publicadas que o rascunho não tem mais; a próxima publicação as tira do site;
• etag é um hash opaco do conteúdo do rascunho;
• live_publish_id é a publicação em vigor, ou null se o servidor nunca publicou.

POST /track/versions publica o rascunho. Corpo: name (obrigatório, de 1 a 100 caracteres) e description (opcional, até 1000). Mande o etag lido em GET /track/rules no cabeçalho If-Match: assim vai ao ar exatamente o que foi revisado. A resposta é { "publish_id": "<id>", "published": true }; quando o rascunho já é igual à publicação em vigor, nada é criado e a resposta traz published: false com o publish_id em vigor.

• 412: o rascunho mudou depois da leitura (If-Match não confere). Leia e revise de novo.
• 409: outra publicação entrou no ar ao mesmo tempo. Publique de novo.

GET /track/versions responde { "live_publish_id": ..., "publishes": [ ... ] }, da mais nova para a mais antiga (a primeira é a que está no ar). Cada item tem publish_id, name, description, published_at (UTC, ISO 8601 sem fuso), published_by (e-mail de quem publicou; null quando foi o sistema, como na instalação das regras padrão), restored_from (a publicação de origem, numa volta de versão) e rule_count. GET /track/versions/{publish_id} traz os mesmos campos e rules, as regras como foram publicadas, na ordem em que o tag as instrumenta; publicação inexistente dá 404 (Error 404: publish not found).

POST /track/versions/{publish_id}/republish põe no ar de novo uma publicação anterior, com o mesmo corpo name/description. Não usa If-Match e não altera o rascunho.

No painel do app, a publicação fica no botão "Publicar" de Rastreamento › Regras; o histórico e a volta de versão existem só pela API e pelo MCP.

Cache do GET /track/tag

• ETag fraco (W/"<publish_id>") com o id da publicação em vigor (W/"0" quando o servidor nunca publicou).
• Cache-Control: max-age=60.
• Um If-None-Match igual ao ETag responde 304, sem corpo, com ETag e Cache-Control.

Uma publicação nova pode levar até um minuto para chegar aos navegadores que já carregaram a configuração.

GET /track/tag?draft=true entrega as regras habilitadas do rascunho, com Cache-Control: no-store. É o que a aba de inspeção do painel (Visualizar) usa para rodar as regras antes de publicar.

Ordem das regras

GET /track/rules e GET /track/tag devolvem as regras em ordem de criação (/track/tag, na ordem da publicação); /track/tag entrega só as habilitadas. É nessa ordem que o tag do navegador instrumenta as regras.

Regras padrão

Todo servidor de rastreamento nasce com 8 regras:

Elas vêm habilitadas e sem conversion, podem ser editadas ou excluídas como qualquer regra e contam no teto de 200 (GET /track/rules num servidor recém-criado devolve 8 itens). A instalação roda a cada PUT /servers do servidor, mas só quando ele não tem nenhuma regra nem nenhuma publicação, e já publica as 8 regras; um servidor com regras ou com alguma publicação (mesmo vazia) fica como está. Uma falha na instalação não derruba a criação do servidor.

Respostas

Sucesso e erros de validação da própria rota usam o envelope padrão ({"Ok": ...} / {"Err": "..."}, Content-Type: application/json), com o status derivado do prefixo Error NNN: da mensagem; ver convenções e erros. Os corpos abaixo chegam dentro do envelope: no fio, GET /track/rules responde { "Ok": { "rules": [...] } }, o POST { "Ok": { "rule_name": "<nome>" } }, e assim por diante.

Erros no envelope:

• 400: regra que não passa na validação (limite estourado, regex que não compila, seletor vazio, thresholds fora de ordem, Once com per: Element sem elemento). A mensagem nomeia o que falhou, por exemplo Error 400: trigger: ... ou Error 400: extractor '<nome>': ....
• 400: nome inválido, corpo Error 400: invalid rule_name (want 1 to 64 characters, no leading or trailing whitespace, none of / % ? #, no control characters, not only dots).
• 400: teto alcançado, corpo Error 400: rule limit of 200 per server reached.
• 404: Error 404: server not found. Em /track/rules, para o Host e a conta do token; em GET /track/tag, só pelo Host.
• 409: POST /track/rules com rule_name que já existe no servidor, corpo Error 409: rule '<nome>' already exists; PUT /track/rules/<nome> updates it. O POST não sobrescreve.

Erros em texto puro, fora do envelope (produzidos antes de a rota processar a requisição, sem {"Err": ...}). Não faça parse de {"Err": ...} em toda resposta não 2xx:

• 400: Host header does not match TLS server name.
• 401 (Not authorized, Bad format: ...) e 403 (Bad token, Insufficient privilege: ..., Feature disabled: WebTracking), da autenticação.
• Rejeições de parse do corpo: um type desconhecido, um campo a mais, um valor fora das listas fechadas (part, key, per), um campo obrigatório ausente ou um Constant com objeto ou null falham antes da validação. Voltam em texto puro, tipicamente com 422; JSON malformado dá 400, e a falta de Content-Type: application/json dá 415.

Veja também

• Servidores: o servidor de rastreamento dono das regras.
• Destinos de rastreamento: a outra metade da medição, para onde o evento capturado é enviado.
• Autenticação: os níveis Standard e ReadOnly e a feature WebTracking exigidos pelas rotas.