wizz-method 2.2.0 → 2.3.1

package/src/modules/lowticket/skills/wizz-lowticket-metodologia/knowledge/17-rastreamento.md

@@ -1,127 +1,127 @@
-## 17. Rastreamento: GA4, GTM, pixel e container de servidor
+## 17. Tracking: GA4, GTM, pixel, and server container
 
-> Shard da metodologia desta base. Índice: [`INDEX.md`](INDEX.md) · Sempre carregado junto: [`guardrails.md`](guardrails.md)
-> Onde a skill genérica contradisser este shard, **o shard vence**, e isso deve ser dito na resposta.
-> ⚠️ **Este shard conflita com 6.3-6.4.** A régua de connect rate manda pixel direto no `<head>`, sem GTM. Este shard põe o pixel dentro do GTM. Ver [ponto em aberto 38](pontos-em-aberto.md).
+> Shard of this base's methodology. Index: [`INDEX.md`](INDEX.md) · Always loaded alongside: [`guardrails.md`](guardrails.md)
+> Where the generic skill contradicts this shard, **the shard wins**, and that must be stated in the response.
+> ⚠️ **This shard conflicts with 6.3-6.4.** The connect-rate ruler requires the pixel directly in `<head>`, with no GTM. This shard puts the pixel inside GTM. See [open point 38](pontos-em-aberto.md).
 
-### 17.1 O que a stack faz
+### 17.1 What the stack does
 
-Três destinos para o mesmo evento, e os três precisam disparar no mesmo instante:
+Three destinations for the same event, and all three need to fire at the same instant:
 
-1. **GA4**, para leitura de funil.
-2. **Meta pelo navegador** (pixel), que o bloqueador de anúncio derruba.
-3. **Meta pelo servidor** (API de Conversões), que o bloqueador não alcança.
+1. **GA4**, for reading the funnel.
+2. **Meta via the browser** (pixel), which an ad blocker takes down.
+3. **Meta via the server** (Conversions API), which an ad blocker can't reach.
 
-O container **web** do GTM faz cerca de 90% do trabalho. O container do **servidor** é um repassador: recebe o que a web mandou e entrega à Meta. Quem desenha errado tenta configurar no servidor o que pertence à web.
+The GTM **web** container does about 90% of the work. The **server** container is a relay: it receives what the web sent and hands it to Meta. Whoever designs this wrong tries to configure on the server what belongs on the web.
 
-### 17.2 GA4: criar a propriedade
+### 17.2 GA4: creating the property
 
-- Fuso **São Paulo**, moeda **Real**. Nome do fluxo = o site sem o `www.`.
-- **Métrica otimizada (Enhanced Measurement): desativar tudo.** Quem dispara evento é o GTM. Deixar ligado gera evento duplicado, e evento duplicado é diagnóstico errado (princípio 1).
-- Ativar **Coleta de dados** e confirmar a **coleta de dados dos usuários**.
-- **Retenção de dados de eventos: trocar de 2 para 14 meses.** O padrão de 2 meses inviabiliza qualquer leitura histórica, e ninguém percebe até precisar.
+- Time zone **São Paulo**, currency **Real**. Stream name = the site without `www.`.
+- **Enhanced Measurement: turn everything off.** GTM is what fires events. Leaving it on generates duplicate events, and a duplicate event is a wrong diagnosis (principle 1).
+- Enable **data collection** and confirm **user data collection**.
+- **Event data retention: change from 2 to 14 months.** The default 2 months makes any historical read impossible, and nobody notices until they need it.
 
-### 17.3 Nomenclatura: a regra que decide se o container fica legível
+### 17.3 Naming: the rule that decides whether the container stays readable
 
-Prefixo numérico em tudo, porque o GTM ordena alfabeticamente e o container cresce rápido:
+Numeric prefix on everything, because GTM sorts alphabetically and the container grows fast:
 
-| Objeto | Padrão | Exemplo |
+| Object | Pattern | Example |
 |---|---|---|
-| variável constante | `00 - <plataforma> - <o que é>` | `00 - GA4 - ID da Métrica` |
-| tag mãe | `000 - Tag do Google` | dispara antes de todas |
-| evento | `NN.<plataforma>.<evento>` | `01.GA4.page_view`, `05.FB.Purchase` |
+| constant variable | `00 - <platform> - <what it is>` | `00 - GA4 - Measurement ID` |
+| parent tag | `000 - Tag do Google` | fires before all others |
+| event | `NN.<platform>.<event>` | `01.GA4.page_view`, `05.FB.Purchase` |
 
-**Nada de ID colado direto na tag.** ID de métrica, número do pixel e token da API viram **variável constante** (no servidor, "variável permanente"). Trocar o pixel depois vira um campo, não uma caçada.
+**No ID pasted directly into a tag.** Measurement ID, pixel number, and API token become a **constant variable** (on the server, a "permanent variable"). Changing the pixel later becomes a field edit, not a hunt.
 
-### 17.4 Ordem de disparo no container web
+### 17.4 Firing order in the web container
 
-1. **Tag do Google**, acionador **Initialization · Todas as páginas**. É a tag mãe: ativa o container para as demais. No seletor de tipos ela é "Tag do Google", **não** "Google Ads".
-2. **`page_view` do GA4**, acionador **DOM Ready** (dispara com código, imagens e vídeos já carregados).
-3. **`PageView` da Meta**, no **mesmo** DOM Ready.
-4. **Lead**, acionador **Envio de formulário**, nas duas plataformas.
+1. **Google Tag**, trigger **Initialization · All pages**. This is the parent tag: it activates the container for the rest. In the tag-type selector it's "Google Tag," **not** "Google Ads."
+2. **GA4's `page_view`**, trigger **DOM Ready** (fires once code, images, and videos have already loaded).
+3. **Meta's `PageView`**, on the **same** DOM Ready.
+4. **Lead**, trigger **Form Submission**, on both platforms.
 
-**A regra:** GA4, pixel e API do mesmo evento sempre no mesmo acionador. Acionador diferente entre plataformas produz números que não fecham, e a discrepância aparece semanas depois como "a Meta está mentindo".
+**The rule:** GA4, pixel, and API for the same event always on the same trigger. A different trigger between platforms produces numbers that don't reconcile, and the discrepancy shows up weeks later as "Meta is lying."
 
-### 17.5 Nome do evento muda por plataforma
+### 17.5 The event name changes per platform
 
-Confirmar na documentação oficial antes de nomear. GA4 usa minúsculo com underline; Meta usa maiúsculas coladas.
+Confirm against official documentation before naming. GA4 uses lowercase with underscores; Meta uses concatenated uppercase.
 
-| Momento | GA4 | Meta |
+| Moment | GA4 | Meta |
 |---|---|---|
-| carregou a página | `page_view` | `PageView` |
-| enviou o formulário | `generate_lead` | `Lead` |
-| comprou | `purchase` | `Purchase` |
-| clicou no WhatsApp | evento personalizado | evento personalizado |
+| page loaded | `page_view` | `PageView` |
+| form submitted | `generate_lead` | `Lead` |
+| purchased | `purchase` | `Purchase` |
+| clicked WhatsApp | custom event | custom event |
 
-Para evento que não é padrão em nenhuma das duas (WhatsApp é o caso típico), **usar o mesmo nome nos dois lados**. É o que permite cruzar as plataformas depois.
+For an event that's not standard on either side (WhatsApp is the typical case), **use the same name on both sides**. That's what lets you cross-reference the platforms later.
 
-A Meta não é plataforma nativa do GTM: o modelo de tag **Facebook Pixel** precisa ser instalado pela galeria de modelos antes de aparecer no seletor.
+Meta isn't a native GTM platform: the **Facebook Pixel** tag template needs to be installed from the template gallery before it shows up in the selector.
 
-### 17.6 Container do servidor
+### 17.6 Server container
 
-**Variáveis permanentes:** pixel e token de acesso da API de Conversões. Conferir que o pixel é o mesmo da web.
+**Permanent variables:** pixel and Conversions API access token. Confirm the pixel matches the web one.
 
-**Acionador personalizado**, com duas condições juntas:
+**Custom trigger**, with two conditions together:
 
-- `Event name` **corresponde a regex**, com os eventos separados por `|`: `page_view|generate_lead|whatsapp`.
-- `Client Name` **contém** `GA4`.
+- `Event name` **matches regex**, with events separated by `|`: `page_view|generate_lead|whatsapp`.
+- `Client Name` **contains** `GA4`.
 
-Os nomes na regex são os do **GA4**, não os da Meta, porque é a tag de GA4 que faz a ponte navegador → servidor. A condição de Client Name existe para o acionador não disparar com evento de outra origem.
+The names in the regex are the **GA4** ones, not Meta's, because it's the GA4 tag that bridges browser → server. The Client Name condition exists so the trigger doesn't fire on an event from another source.
 
-**Uma tag só para tudo:** modelo do Facebook na versão **Stape** (não a "incubator"), com `Event Name` em **Inherit from Client**. Assim ela herda qualquer evento que chegar. Aceita múltiplos pixels em pares pixel + token, até 20.
+**One single tag for everything:** the Facebook template in the **Stape** version (not the "incubator" one), with `Event Name` set to **Inherit from Client**. This way it inherits whatever event comes in. It accepts multiple pixels in pixel + token pairs, up to 20.
 
-**Validação pelo código HTTP:** `200` disparou, `400` falhou. Erro 400 quase sempre é acionador mal configurado, URL errada ou um caractere digitado errado no parâmetro. Conferir letra por letra contra a documentação, porque a tag não avisa qual campo quebrou.
+**Validation via HTTP code:** `200` fired successfully, `400` failed. A 400 error is almost always a misconfigured trigger, a wrong URL, or a mistyped character in a parameter. Check letter by letter against the documentation, because the tag doesn't tell you which field broke.
 
 ### 17.7 Purchase
 
-**Acionador:** Exibição de página, `Page URL` **contém** a slug da página de obrigado, escrita **sem `https` e sem `www`**.
+**Trigger:** Page View, `Page URL` **contains** the thank-you page's slug, written **without `https` and without `www`**.
 
-**Parâmetros obrigatórios:**
+**Required parameters:**
 
-| Plataforma | Parâmetros |
+| Platform | Parameters |
 |---|---|
-| Meta (Object Properties) | `value`, `currency` (ambos minúsculos) |
-| GA4 (Parâmetros do evento) | `currency`, `value`, `transaction_id`, `items` |
-| API (servidor) | os 4 do GA4 + `Transport URL` + `Event ID` |
+| Meta (Object Properties) | `value`, `currency` (both lowercase) |
+| GA4 (Event parameters) | `currency`, `value`, `transaction_id`, `items` |
+| API (server) | the 4 from GA4 + `Transport URL` + `Event ID` |
 
-- `value`: o valor numérico do produto, sem símbolo de moeda e sem separador de milhar.
-- `transaction_id`: **sem webhook**, uma variável JavaScript personalizada gera o número; **com webhook**, vem pronto da plataforma de vendas.
-- **`Event ID` também na tag da Meta.** É ele que deduplica o evento que chegou pelo navegador contra o que chegou pelo servidor. É o campo que mais se esquece, e sem ele a compra conta duas vezes.
+- `value`: the product's numeric value, with no currency symbol and no thousands separator.
+- `transaction_id`: **without a webhook**, a custom JavaScript variable generates the number; **with a webhook**, it comes ready-made from the sales platform.
+- **`Event ID` also on the Meta tag.** This is what deduplicates the event that arrived via the browser against the one that arrived via the server. It's the field most often forgotten, and without it the purchase counts twice.
 
-**Os dois tetos da estrutura sem webhook:**
+**The two ceilings of a webhook-less setup:**
 
-- **Moeda fixa.** `currency` cravado em `BRL` só serve para mercado único. Vender para mais de um país obriga a migrar para webhook.
-- **Um produto por tag.** Cada produto precisa da sua página de obrigado e da sua tag de Purchase. Com webhook, uma tag cobre o catálogo inteiro.
+- **Fixed currency.** `currency` hardcoded as `BRL` only works for a single market. Selling to more than one country forces a migration to a webhook.
+- **One product per tag.** Each product needs its own thank-you page and its own Purchase tag. With a webhook, one tag covers the whole catalog.
 
-Ou seja: catálogo com mais de um produto, ou mais de uma moeda, já nasce pedindo webhook. Montar sem ele é dívida técnica com data marcada.
+In other words: a catalog with more than one product, or more than one currency, is already asking for a webhook. Building without one is technical debt with a set date.
 
-### 17.8 Proxy do container web
+### 17.8 Web container proxy
 
-Serve os scripts do GTM pelo domínio próprio em vez do domínio do Google, que o bloqueador de anúncio reconhece e derruba.
+Serves GTM's scripts through your own domain instead of Google's, which ad blockers recognize and take down.
 
-1. No container do servidor: **Cliente > Novo**, tipo "Gerenciador de tags do Google".
-2. `Adicionar ID do contêiner` = o ID do container **web**.
-3. `Região` = variável integrada **Região do visitante**.
-4. No plugin de GTM do WordPress, aba **Advanced**: marcar `Load GTM container` e pôr o domínio do servidor em `Container domain name`, **sem `https://` e sem barra no final**.
+1. In the server container: **Client > New**, type "Google Tag Manager."
+2. `Add container ID` = the **web** container's ID.
+3. `Region` = the built-in variable **Visitor Region**.
+4. In the WordPress GTM plugin, **Advanced** tab: check `Load GTM container` and put the server's domain into `Container domain name`, **without `https://` and without a trailing slash**.
 
-O passo 4 é onde a configuração costuma falhar em silêncio: com o prefixo ou a barra sobrando, o campo aceita e nada carrega.
+Step 4 is where the setup usually fails silently: with a stray prefix or trailing slash, the field accepts it and nothing loads.
 
-### 17.9 Formulário e checkout pré-populado
+### 17.9 Form and pre-filled checkout
 
-**O formulário leva nome, e-mail e telefone. Só.** E-mail e telefone são os dados que mais sobem a qualidade de correspondência na Meta. Campo a mais derruba a taxa de envio sem devolver sinal.
+**The form takes name, email, and phone. Only.** Email and phone are the fields that boost match quality on Meta the most. One extra field lowers the submission rate without giving anything back in signal.
 
-- Pop-up exige **Elementor Pro**; não existe na versão gratuita. O botão abre o pop-up por campo **dinâmico**, não por URL digitada.
-- O encaminhamento sai de **Action After Submit > Redirect**.
+- The pop-up requires **Elementor Pro**; it doesn't exist in the free version. The button opens the pop-up via a **dynamic** field, not a typed URL.
+- Redirection comes from **Action After Submit > Redirect**.
 
-**Checkout pré-populado:** montar a URL do checkout com os parâmetros que a plataforma aceita (nome, e-mail, CPF, telefone, região) e preencher cada valor com o **short code** do campo correspondente do formulário (aba `Advanced` de cada campo).
+**Pre-filled checkout:** build the checkout URL with the parameters the platform accepts (name, email, CPF, phone, region) and fill each value with the corresponding form field's **short code** (the `Advanced` tab of each field).
 
-- Conferir se o link do checkout **já tem `?`**. Se tiver, os parâmetros seguintes encadeiam com `&`, nunca com uma segunda interrogação. Link da Hotmart costuma já vir com `?`.
-- O nome de cada parâmetro é o que a plataforma de checkout exige, não o que o formulário chama.
+- Check whether the checkout link **already has a `?`**. If it does, the following parameters chain with `&`, never with a second question mark. Hotmart links usually already come with a `?`.
+- Each parameter's name is whatever the checkout platform requires, not whatever the form calls it.
 
-O ganho é duplo e vale citar junto: **menos fricção** (o comprador não redigita nada, o que ataca direto a transição checkout → compra de 2.4) e **mais dado** para o matching da Meta.
+The gain is twofold and worth stating together: **less friction** (the buyer doesn't retype anything, which directly attacks the checkout → purchase transition from section 2.4) and **more data** for Meta's matching.
 
-### 17.10 O que este shard ainda não cobre
+### 17.10 What this shard doesn't cover yet
 
-Nenhum dado pessoal do usuário entra nas tags até aqui. **Advanced Matching** e **geolocalização** são os módulos seguintes, e são eles que ligam os dados do lead às tags. O próximo módulo desta base trata de UTM dentro do GTM e no link do checkout.
+No personal user data enters the tags up to this point. **Advanced Matching** and **geolocation** are the next modules, and they're what links the lead's data to the tags. The next module in this base covers UTMs inside GTM and in the checkout link.
 
-Enquanto isso não estiver feito, a qualidade de correspondência fica no piso, e o número de compras atribuídas vai estar abaixo do real. Não é erro de configuração: é etapa que falta.
+Until that's done, match quality stays at the floor, and the number of attributed purchases will be below the real figure. It's not a configuration error: it's a missing step.