@funnel10x/tracking 2.0.0 → 2.2.0

package/README.md

@@ -28,6 +28,9 @@ CDN, no canal 1.x, e o SDK não vem neste ficheiro. O que faz numa página:
   acrescentados), no URL do iframe de um form, inquérito ou calendário do GHL,
   e nos links do checkout. O email, o `token` e o resto do URL não seguem: iam
   para o URL do Stripe e para os campos do GHL, que é entregá-los a terceiros;
+- **o `checkout` no clique num link do checkout** (desde a 2.2.0, Fase A41),
+  uma vez por link e por página: o início do checkout, do contrato dos
+  eventos (abaixo);
 - **o identify pelo id do contacto** num link de email ou de SMS
   (`?contact_id={{contact.id}}`);
 - **o email e o telefone que a pessoa envia** (desde a 1.1.0, como a HYROS;
@@ -45,26 +48,47 @@ CDN, no canal 1.x, e o SDK não vem neste ficheiro. O que faz numa página:
 - **a versão do snippet em cada evento** (`tracking_version`), e, num site
   `direct`, **a versão da página e o teste** (`page_version`, `ab_test`), o
   **interruptor de consentimento** do `site.json`, e a guarda das
-  pré-visualizações.
+  pré-visualizações;
+- **os extras isolados do arranque do SDK** (desde a 2.1.0, Fase A2c): os
+  forms, o iframe e o checkout (`dom`), o email e o telefone (`contact`), o
+  FingerprintJS (`fingerprint`) e o cross-domain (`linker`) correm cada um no
+  seu `try`. Um que lance deixa na consola *the dom extra failed* (com o nome
+  dele) e, em cada evento, o `tracking_degraded` com a lista dos que falharam
+  (`['dom']`), e o PostHog mede na mesma, com o `tracking_version`. No 2.0.0 um
+  erro em qualquer deles impedia o SDK de carregar. Um erro no próprio arranque
+  (o núcleo: o stub, o consentimento, o carregamento do `array.js`, o
+  `before_send`, a API) deixa a página como estava: o stub sai, o
+  `window.f10xTracking` fica sem `version`, e numa tag do GTM arranca a tag
+  oficial de reserva (*A reserva*, abaixo);
+- **o cross-domain entre domínios ligados, opcional** (`linkedDomains`, desde a
+  2.1.0): os links e os forms para o outro domínio levam a pessoa e a sessão do
+  PostHog num parâmetro que expira em 2 minutos, como o `_gl` do GA (*O
+  cross-domain*, abaixo).
 
 **Quem lê isto do lado do admin** (Fase A3 do plano da atribuição): a fonte
 PostHog da ingestão guarda de cada toque o `tracking_version`, a
 `page_version`, o `ab_test`, o `fingerprint`, e desde a A2b a versão do SDK e a
 data dos `defaults` (`$lib_version` e `$config_defaults`), e o email e o
-telefone do `contact_captured` só em hash. **Apara cada URL pela mesma lista**
+telefone do `contact_captured` só em hash; desde a A2c, o `tracking_fallback`
+que a tag de reserva carimba e o `linked_distinct_id` do cross-domain (em hash
+quando é um email, como o `distinct_id`). O `tracking_degraded` fica só no
+PostHog, como o `fingerprint_ms`. **Apara cada URL pela mesma lista**
 de `src/params.js`: um parâmetro que entre na `ALLOWED_PARAMS` entra também na
 entrada `posthog` da `ingest/pii.json` e na `supabase/verify/atr3.sql` do
 admin, no mesmo PR (um teste do admin prova que as três listas são a mesma).
 
-### Uma de duas instalações por site
+### Uma instalação activa por página: o snippet, e a oficial como reserva
 
-Cada site, de qualquer account, escolhe **uma** de duas instalações, e nunca as
-duas na mesma página (decisão 1 da A2b): a **oficial do PostHog** (a tag no
-GTM, o snippet oficial no código do site, ou o posthog-js no código de uma app)
-ou **este snippet** (embutido num repo `direct`, ou pela tag do
-`dist/gtm.html` em qualquer outro site). Quem escolhe este não perde nada da
-oficial: é o mesmo SDK, com os extras. Com as duas, a segunda ou toma o
-arranque da primeira ou duplica cada evento:
+Cada site, de qualquer account, escolhe **uma** de duas instalações, e nunca há
+duas activas na mesma página (decisão 1 da A2b, revista pela decisão 1 da A2c):
+a **oficial do PostHog** (a tag no GTM, o snippet oficial no código do site, ou
+o posthog-js no código de uma app) ou **este snippet** (embutido num repo
+`direct`, ou pela tag do `dist/gtm.html` em qualquer outro site). Num site com
+a tag do GTM, a oficial pode lá estar **só como reserva**: outra tag, que
+arranca quando o snippet não carregou, e nunca ao lado dele (*A reserva*,
+abaixo). Quem escolhe este não perde nada da oficial: é o mesmo SDK, com os
+extras. Com duas activas, a segunda ou toma o arranque da primeira ou duplica
+cada evento:
 
 - **a oficial antes deste**: o primeiro `init` da fila manda, e este não
   arranca; avisa na consola (*another PostHog is already on this page*) e o
@@ -76,8 +100,13 @@ arranque da primeira ou duplica cada evento:
   `supabase/verify/atr2b.sql` do admin guarda o resto: num host com este
   snippet, nenhum `$pageview` de outra instalação no mesmo minuto.
 
-Num contentor GTM partilhado por vários sites, a tag oficial dispara só nos
-hosts que a escolheram (uma excepção por hostname no trigger). **Dentro de um
+Num contentor GTM partilhado por vários sites, a tag oficial dispara nos hosts
+que ainda não passaram ao snippet: em All Pages, com o acionador *Snippet hosts*
+(o da tag do snippet) como **excepção**, e o *Direct hosts* (os sites `direct`,
+com o snippet no build) como outra (Fase A2d do admin, que revê a lista de
+inclusão da A2c: passar um host é uma edição da RegEx, e um host que ninguém
+listou fica medido pela oficial, em vez de calado). A reserva é outra tag.
+**Dentro de um
 domínio registável, todas as instalações levam a mesma data de `defaults`**: o
 cookie do PostHog é partilhado pelos subdomínios, e a data muda a regra entre o
 cookie e o `localStorage` (`cookieWinsOnConflict`). A deste pacote é
@@ -129,7 +158,7 @@ de vir no ficheiro. É uma das razões de a 2.0.0 ser major.
 O `package.json` do repo pina a versão exacta (sem `^`), e o build embute-o:
 
 ```json
-{ "dependencies": { "@funnel10x/tracking": "2.0.0" } }
+{ "dependencies": { "@funnel10x/tracking": "2.2.0" } }
 ```
 
 ```js
@@ -140,6 +169,7 @@ init({
   apiHost: '/_t',
   sdkVersion: import.meta.env.VITE_POSTHOG_SDK_VERSION || undefined,
   consent: site.consent,
+  linkedDomains: site.linkedDomains,
   pageVersion: 3,
   test: '/pt/acq_f1/webinar/lp#2',
 })
@@ -185,34 +215,82 @@ init({
   (`f10x_consent`), e a página seguinte arranca sozinha. Com `false`, mede
   logo. **O GTM do site arranca depois do stub do snippet**, para uma tag que
   use o `window.posthog` o encontrar.
+- `linkedDomains`: o do `site.json`, opcional, uma lista de hosts (*O
+  cross-domain*, abaixo). Sem ele, ou vazio, o cross-domain está desligado.
 - `pageVersion` e `test`: o `version` da página principal no `tests.json` (ou o
   `N` de uma variante) e o nome do teste activo, que o build entrega.
 
 Uma página cujo caminho acaba em `_` seguido de algarismos (a pré-visualização
 de uma versão) não mede nada nem mexe nos forms.
 
+## Num site com build próprio que não é da base, ou só com o header
+
+O cartão PostHog do Account Settings dá as três maneiras, pela ordem do que é
+melhor, já com a chave do projeto:
+
+- **No build do site** (um Next.js ou um Vite na Vercel que não nasceu da
+  base `direct`): o `dist/direct-init.js` (o `init` com o `apiHost: '/_t'`) e
+  o `dist/direct-rewrites.json` (os três rewrites de cima, para o
+  `vercel.json`), que o build do pacote escreve e o
+  `tests/api/gtm-tags.test.mjs` compara com o bloco da secção de cima. O
+  `/_t` é o proxy no domínio do site, e por isso não leva o proxy gerido.
+- **Colado no header** (um funil do GHL, um Webflow): a tag do snippet, o
+  `dist/gtm.html`, tal como está. Não depende do GTM, que a EasyPrivacy
+  bloqueia inteiro (`||googletagmanager.com^`), mas só passa pelas listas com o
+  proxy gerido no `apiHost`: sem ele, vai para o `i.posthog.com`, que a mesma
+  lista bloqueia (o `array.js` e o `/i/`). A reserva só corre pelo GTM (o
+  `f10x_tracking_failed` é um evento do `dataLayer`), e por isso um site sem
+  contentor não mede a visita em que o snippet falha.
+- **Pelo GTM**: só a tag do snippet em All Pages, que é a mais simples (sem
+  a reserva, a visita em que o `tag.js` não carrega não se mede), ou as três
+  tags, abaixo.
+
+Um host das duas primeiras num contentor com a oficial do PostHog entra no
+acionador *Direct hosts*, que é a excepção dela, no dia em que passa.
+
 ## Num site que não é repo nosso: a tag do GTM
 
 Num funil do GHL, num site institucional ou num site em Webflow, onde não há
-build, o mesmo pacote carrega-se por uma tag Custom HTML do GTM (em All Pages),
-**em vez da tag oficial do PostHog, e nunca ao lado dela** (*Uma de duas
-instalações por site*, acima), **pela versão fixa** no URL do jsDelivr e com o
-hash do ficheiro no `integrity`. A tag de cada versão publicada está no próprio
-pacote, em `dist/gtm.html`, e cola-se tal como está: só se trocam a chave, o
-`apiHost` (se a account tiver o proxy gerido, abaixo), os hosts do checkout e,
-numa emergência, o `sdkVersion`.
-
-```html
-<script>
-  window.f10xTracking = {
-    key: '{{PostHog project key}}',
-    apiHost: '',
-    sdkVersion: '',
-    checkoutHosts: []
-  }
-</script>
-<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@2.0.0/dist/tag.js" integrity="sha384-…" crossorigin="anonymous"></script>
-```
+build, o mesmo pacote carrega-se por uma tag Custom HTML do GTM, **em vez da tag
+oficial do PostHog, que fica só como reserva** (*Uma instalação activa por
+página*, acima, e *A reserva*, abaixo), **pela versão fixa** no URL do jsDelivr
+e com o hash do ficheiro no `integrity`. **As três tags de um contentor geram-se
+no admin**, já com a chave do projeto e o proxy gerido da account: em Account
+Settings › Integrations, no cartão PostHog, *Install the tracking on a site*
+(Fase A2d do plano da atribuição), com os acionadores e os passos de
+instalar, de passar um host e de ligar o proxy. O que o cartão gera são os
+ficheiros do `dist/` sem o comentário de cabeça, com os marcadores trocados, e
+mais nada:
+
+| ficheiro | a tag | dispara |
+| --- | --- | --- |
+| `dist/gtm.html` | o snippet, desta versão | no acionador *Snippet hosts* (Page View, *Page Hostname* corresponde à RegEx) |
+| `dist/gtm-fallback.html` | a oficial do PostHog como reserva, com o `tracking_fallback` | só no evento personalizado `f10x_tracking_failed` |
+| `dist/gtm-official.html` | a oficial do PostHog, para os hosts que ainda não passaram | em All Pages, com o *Snippet hosts* e o *Direct hosts* como excepção |
+
+As três levam a condição de consentimento de analytics do site, quando ele tem
+banner. Só se trocam a chave, o host (o `apiHost` no snippet, o `api_host` nas
+oficiais: o proxy gerido da account, abaixo, ou o PostHog directo), os hosts do
+checkout, os domínios ligados (*O cross-domain*, abaixo; vazio, desligado) e,
+numa emergência, o `sdkVersion`. Uma oficial que já exista no contentor
+substitui-se pela gerada, que traz a data dos `defaults` do pacote.
+
+**Desde a 2.1.0 a tag diz quando o snippet não arrancou**: empurra para o
+`dataLayer` o evento `f10x_tracking_failed`, uma vez por página, quando o
+`tag.js` não chega (o `onerror`: o jsDelivr em baixo ou bloqueado, um
+`integrity` que não bate, uma CSP que o recusa; ou nenhum dos dois ao fim de
+10 s, um pedido pendurado) ou chega e não deixa a `version` no
+`window.f10xTracking` (o `onload`: um erro nosso no arranque). É o evento em
+que a reserva dispara. Um `tag.js` que chegue depois dos 10 s encontra a
+oficial e fica inerte (o `conflict`), e continua a haver uma só instalação
+activa; e uma tag que dispare outra vez com o snippet já a correr não empurra
+nada, mesmo que a rede lhe falhe. **O evento vai para o `window.dataLayer`**:
+num GTM com a data layer renomeada (o `l=` do snippet do GTM) a reserva não
+dispara, e a prova do ponto 8 do checklist apanha-o. O `<script>` do jsDelivr cria-se por código, e não como
+um `<script src>` no HTML: o GTM recria cada `<script>` de um Custom HTML
+copiando-lhe os atributos, e um `onload` escrito como atributo é um handler
+inline, que uma CSP com nonce não deixa correr; posto como propriedade, de
+dentro do script da tag, corre sempre.
 
 Uma versão nova é uma tag nova, nunca `@2` nem `@latest`: o GTM de cada site
 diz que versão dos extras corre, e o `tracking_version` de cada evento
@@ -227,7 +305,9 @@ organização, *Managed reverse proxy*) que recebe os envios e os passa ao
 PostHog, e serve também o `array.js`. Com ele, o `apiHost` da tag é esse
 subdomínio: na IR,
 `https://p.infinityresponse.com`, e na IMO Circle, `https://p.imocircle.com`
-(os dois válidos, lidos no PostHog a 2026-10-08; o Piko ainda não tem). As listas que bloqueiam pelo nome do domínio deixam de o apanhar;
+(os dois válidos, lidos no PostHog a 2026-10-08; o Piko ainda não tem). O
+admin guarda o de cada projeto (o *Managed proxy* do mesmo cartão, que só grava
+um host que sirva o SDK do PostHog), e gera as três tags com ele. As listas que bloqueiam pelo nome do domínio deixam de o apanhar;
 o uBlock Origin no Firefox, que lê o CNAME, apanha na mesma, e quanto se
 recupera não se mede, porque o que é bloqueado não chega para se contar. O
 subdomínio é de outra origem que a página, e por isso o browser só lhe manda a
@@ -258,6 +338,55 @@ anúncio, e os campos escondidos do form lêem-nos de lá (cada campo com o
 código do form: dentro de um iframe o snippet não arranca o PostHog, só passa
 ao form o que veio no URL dele.
 
+### A reserva: a tag oficial quando o snippet não carrega
+
+Num site com a tag do snippet, a tag oficial do PostHog passa a reserva
+(decisão 1 da A2c): uma tag Custom HTML (o template da galeria não tem onde pôr
+uma função) com o snippet oficial do PostHog, que dispara **só no evento
+personalizado `f10x_tracking_failed`**, e por isso só quando o snippet tentou e
+não conseguiu, nunca antes dele. É o `dist/gtm-fallback.html`, que o build
+escreve e o Account Settings gera já preenchido: o stub do snippet oficial (a
+forma que as definições do projeto dão hoje, a do `snippetFunctions` do
+PostHog, que insere o `array.js` uma vez só e deixa repetir depois de uma
+falha, com a lista de métodos do posthog-js da devDependency), a mesma chave e o mesmo `api_host` da tag do snippet, a data de
+`defaults` e o `custom_campaign_params` do pacote (para os ids de anúncio irem
+como propriedades nas duas instalações), `person_profiles: 'identified_only'`,
+e um **`before_send` que carimba `tracking_fallback: true` em cada evento**, que
+é o que distingue uma visita pela reserva nos dados (o admin guarda-o). Pelo
+`before_send` e não pelo `register`, que persistia e marcava os `$pageview` do
+snippet nas páginas seguintes.
+
+**O trigger é um evento personalizado**, com a mesma condição de consentimento
+da tag do snippet. Nunca All Pages nem *Window Loaded*: em All Pages a oficial
+dispara antes de o `tag.js` chegar e toma o arranque (o `conflict`), e num site
+com banner o `load` chega antes do sim, a reserva media sem ele, e quando o sim
+fizesse correr a tag do snippet ela dava `conflict`. Pelo evento, a reserva já
+é segura contra duplicados: com o snippet carregado o evento não sai, e se
+saísse o `init` dela era um no-op no stub do snippet.
+
+**Num contentor partilhado** (o `GTM-PM4T6FGX` do Piko) são duas tags oficiais:
+a dos hosts que ainda não passaram (o `dist/gtm-official.html`), em All Pages,
+sem `before_send`, com o *Snippet hosts* e o *Direct hosts* como excepção; e a
+reserva, outra tag, só no `f10x_tracking_failed`, com o `before_send`. Uma tag
+só a fazer as duas coisas disparava em All Pages antes do `tag.js` nos hosts do
+snippet (o `conflict`) e carimbava `tracking_fallback` nos hosts da oficial, que
+não é reserva nenhuma. A tag do snippet dispara só no *Snippet hosts*, e por
+isso nunca nos hosts `direct` (onde o snippet vai no build) nem nos que ainda
+estão na oficial.
+
+**O que a reserva cobre**: o jsDelivr em baixo ou bloqueado, um `integrity` que
+não bata, e um erro nosso no arranque. **O que não cobre**: uma versão do SDK
+que parta (a oficial carrega o mesmo `array.js`, e a resposta é o
+`sdkVersion`), e os bloqueadores de anúncios (bloqueiam as duas). Num site
+`direct` não há reserva: o snippet vai no build, a tag do snippet não dispara
+nesses hosts, e o que o protege são os extras isolados.
+
+**O que uma visita pela reserva perde**: a visita conta, com o URL inteiro e os
+parâmetros dele no PostHog, e perde-se o que é dos extras: os ids nos campos
+dos forms, no URL do iframe do GHL e nos links do checkout (os `ph_*` e o
+`client_reference_id`), o `contact_captured` (o email e o telefone), o
+fingerprint, o `_f10x` do cross-domain, e o `tracking_version`.
+
 ## Os campos
 
 O que os forms, o iframe e os links do checkout levam:
@@ -297,6 +426,101 @@ O que os forms, o iframe e os links do checkout levam:
   `sale_posthog_links` liga a venda pelo `cs_…` observado no PostHog primeiro,
   senão pelo primeiro id da metadata que o projeto da account tenha visto.
 
+## O cross-domain: `linkedDomains`
+
+**Desligado por omissão**, e só para um funil que atravesse dois domínios
+registáveis nossos (decisão 3 da A2c). Entre subdomínios do mesmo domínio o
+cookie do PostHog já segue a pessoa, também em sufixos de duas partes
+(`.com.br`, `.co.uk`), e o que hoje atravessa domínios são terceiros (o Stripe,
+o redirect dos links do GHL), que têm os seus caminhos. O posthog-js não tem
+linker; este desenha-se como o `_gl` do GA.
+
+**A opção** é uma lista de hosts (`go.marca.pt`) ou de domínios registáveis
+(`marca.pt`, que apanha os subdomínios), sem esquema nem caminho, ou uma string
+com eles separados por vírgulas ou espaços; uma entrada sem forma de hostname
+(um `*.marca.pt`) sai, com um aviso na consola. Vai no
+`window.f10xTracking` da tag, ou no `init` de um repo `direct` (o `linkedDomains`
+do `site.json`, que a base passa). Os dois sites levam o outro na lista: um
+`_f10x` que chegue só se lê numa página com a lista preenchida.
+
+**À saída**, os links (`a[href]`) e os forms (`form[action]`) para um host da
+lista ganham, no clique (o esquerdo, e o do meio, que abre noutro separador;
+o direito não, porque o menu dele tem *Copiar endereço do link*, e uma marca
+fresca no instante da cópia é o instante da partilha; e o direito tira o
+`_f10x` que um clique anterior tenha deixado no link) ou no envio, o parâmetro
+`_f10x=<marca de tempo, em base 36>.<i ou a>.<distinct id>.<session id>`,
+codificado para o URL. Só com o PostHog a medir (com `consent: true`, depois do
+sim). Ficam de fora os hosts do checkout, que têm a decoração deles, e um
+destino que partilha com a página um domínio da lista (o cookie já o segue). O
+`i` diz que a origem está identificada (o `distinct_id` já não é o
+`$device_id`: um `contact_id` de um link de email, um identify), e o `a` que é
+anónima. **O `distinct_id` vai sempre, mesmo quando é um email** (o dono,
+2026-10-14): com o sinal `i` o destino arranca identificado no PostHog, e os
+eventos caem logo na pessoa do contacto. Num form GET o browser troca a query
+string do `action` pelos campos, e o `_f10x` vai num campo escondido; num POST
+vai no `action`.
+
+**À chegada**, um `_f10x` cuja marca está a **menos de 2 minutos** do
+carregamento da página (contados até ao carregamento, e não até ao sim do
+banner; nos dois sentidos, para um relógio adiantado na origem não deixar um
+link válido mais do que isso):
+
+- **sem identidade do PostHog na página** (nada no cookie, no `localStorage` nem
+  no `sessionStorage` com o nome dele, `ph_<chave>_posthog`): o snippet passa
+  ao posthog-js o `bootstrap` com o `distinctID` e o `sessionID` da origem, e
+  `isIdentifiedID` quando o sinal é `i`. O primeiro `$pageview` sai com o
+  `distinct_id` e o `$session_id` da origem; de uma origem identificada, com um
+  `$device_id` novo (o `ph_anon_id` dos forms nunca é o id do contacto) e o
+  estado `identified`. O `bootstrap` junta-se ao que o site passe em
+  `posthog.bootstrap`, sem o perder;
+- **com identidade** (anónima ou identificada, guardada ou dada pelo site): o
+  browser não a troca, porque o `bootstrap` sobrepunha-a sem evento nenhum, e
+  cada evento desta página leva o `linked_distinct_id` (o id que veio no link).
+  O admin guarda-o e liga os dois `distinct_id` como factos de ligação;
+- **fora da janela**: nada. A pessoa fica com um id novo, e o admin liga-a por
+  outro caminho.
+
+**Com `consent: true`** nada acontece antes do sim: o `_f10x` fica em memória,
+o sim aplica-o (a janela conta desde o carregamento), e um não deita-o fora.
+
+O que se sabe e se aceitou:
+
+- **o `_f10x` fica no URL da página de destino**, onde qualquer tag de
+  terceiros o lê, e com o sinal `i` pode levar um email. O PostHog recebe o URL
+  inteiro, e a ingestão do admin apara-o como aos `ph_*`;
+- **um link reencaminhado dentro dos 2 minutos junta duas pessoas**: é o preço
+  da janela, e 2 minutos é a do `_gl` (apanham 94% dos saltos medidos entre
+  hosts do Piko);
+- **um redirect no destino que apague a query string parte o salto**, como no
+  GA: a aceitação de um site com a opção prova cada link;
+- **um relógio adiantado no browser de origem perde a sessão, e não a
+  pessoa**: o posthog-js ignora um `sessionID` com mais de 1 minuto no futuro.
+
+## O contrato dos eventos
+
+Um funil manda três eventos custom, e só estes (Fase A41 do plano da
+atribuição, 2026-10-16):
+
+| evento | quando | quem o manda |
+| --- | --- | --- |
+| `contact_captured` | o email ou o telefone sai num form, ou chega no URL (`contact_source`: `form` ou `url`), cada valor uma vez por página | o snippet |
+| `checkout` | o **início** do checkout: o clique num link para um host do Stripe ou do `checkoutHosts`, uma vez por link e por página, com o `checkout_host` | o snippet, desde a 2.2.0; um checkout aberto por código (um botão com redirect, um checkout embebido) chama `f10xTracking.capture('checkout')` |
+| `purchase` | o pagamento confirmado, com o `session_id` (o `cs_…` da sessão de checkout do Stripe), o `currency`, o `amount_total` e o `product` | o código do funil, na página de obrigado |
+
+- O `contact_captured` é a ponte para o contacto, e **não uma etapa do funil**:
+  dispara também num form de checkout, e um opt-in, uma marcação e uma compra
+  dão o mesmo. O lead é o contacto no CRM.
+- O `checkout` vai já, e não na fila (o `send_instantly` do posthog-js), porque
+  a página sai a seguir. Um site cujo código já mande o seu `checkout` tira-o
+  quando passar ao snippet, senão conta dois.
+- O `purchase` liga a venda pelo `cs_…`, por isso tem de disparar em todas as
+  compras: no Piko, a 2026-10-16, o `purchase` ligava 78% das vendas e o
+  `checkout_completed` todas.
+- Não há evento de marcação: o calendário do GHL vem num iframe, onde o
+  PostHog não arranca, e a marcação, a presença e o no-show vêm do GHL.
+- O `lead` e o `checkout_completed` deixaram de ser contrato; o admin continua
+  a aceitá-los, pelo histórico e pelos funis que ainda os mandam.
+
 ## A API
 
 `init(options)` (ou a tag) devolve, e põe em `window.f10xTracking`:
@@ -308,8 +532,9 @@ O que os forms, o iframe e os links do checkout levam:
 - `fields()`: os valores de cima, agora;
 - `grant()`, `deny()`, `consent()`: o interruptor de um site `direct`;
 - `onReady(fn)`: quando o PostHog estiver a medir;
-- `capture(event, properties)`: um evento pelo mesmo PostHog (o `lead` de um
-  form em código), que sem consentimento não faz nada;
+- `capture(event, properties)`: um evento pelo mesmo PostHog (o `purchase` da
+  página de obrigado, o `checkout` de um checkout aberto por código), que sem
+  consentimento não faz nada;
 - `posthog`: a instância do PostHog depois de o SDK arrancar, e o stub até lá
   (o que se lhe chamar fica na fila, como no stub oficial). O
   `window.posthog` é o mesmo, e é por ele que as tags do GTM o usam.
@@ -397,10 +622,12 @@ Antes de ligar o tráfego:
    do `/_t` no `vercel.json`; num site de fora, a tag do `dist/gtm.html` da
    versão, com a chave da account e, se ela tiver o proxy gerido, o `apiHost`.
    O `sdkVersion` fica vazio.
-2. **Uma só instalação na página**: este snippet ou a oficial do PostHog,
-   nunca as duas. Ao escolher este, a tag ou o snippet do PostHog que o site já
-   tenha (no GTM, no head, no código do site) sai quando este entra, e num
-   contentor partilhado a tag oficial ganha a excepção do hostname. Com a mesma
+2. **O snippet, e a oficial como reserva**: este snippet é a única instalação
+   activa na página. Ao escolher este, o snippet do PostHog que o site já tenha
+   no head ou no código sai quando este entra, e no GTM a tag oficial passa a
+   reserva (*A reserva*, acima: só no `f10x_tracking_failed`, com o
+   `before_send`); num contentor partilhado, a oficial de sempre fica com a
+   condição de inclusão por hostname, e a reserva é outra tag. Com a mesma
    chave não se perde nada: quem volta mantém o id anónimo. **O `apiHost` da
    tag nova é o `api_host` que a antiga tinha** (o proxy, se ela o usava):
    vazio, perdia quem hoje chega por ele. **A data dos `defaults` é a mesma em
@@ -415,15 +642,25 @@ Antes de ligar o tráfego:
    campos de atribuição da tabela, com o *query key* igual ao nome.
 5. **Os links de email e de SMS** levam `contact_id={{contact.id}}`.
 6. **O checkout**: o host em `checkoutHosts` (o Stripe já lá está), e num
-   checkout em código os `fields()` na metadata.
+   checkout em código os `fields()` na metadata e o `capture('checkout')` no
+   clique. Um clique de teste num link do checkout deixa um `checkout` no
+   PostHog, e a página de obrigado manda o `purchase` com o `cs_…` em todas as
+   compras (*O contrato dos eventos*, acima); nenhum outro evento custom.
 7. **Os anúncios**: o texto do gerador de links nos anúncios da Meta e da
    Google, e os links orgânicos gerados por ele, com as UTMs da Traffic Sources.
-8. **A prova**: na consola, `window.f10xTracking.mode` não é `conflict`; um
-   pageview aberto com `?email=teste@example.com&utm_source=teste` chega ao
-   PostHog (Activity, no projeto da account) uma vez só, inteiro, com o
-   `tracking_version` da versão, o `$lib_version` que o CDN serve e nenhum
-   `tracking_conflict`; e os campos do form e o link do checkout levam a
-   `utm_source` e não o `email`.
+8. **A prova**: na consola, com a reserva instalada,
+   `window.f10xTracking.mode` não é `conflict`; um pageview aberto com
+   `?email=teste@example.com&utm_source=teste` chega ao PostHog (Activity, no
+   projeto da account) uma vez só, inteiro, com o `tracking_version` da versão,
+   o `$lib_version` que o CDN serve e nenhum `tracking_conflict` nem
+   `tracking_fallback`; os campos do form e o link do checkout levam a
+   `utm_source` e não o `email`; e com o jsDelivr bloqueado no browser (nas
+   DevTools, *Network request blocking*, `cdn.jsdelivr.net`) chega um só
+   `$pageview`, com `tracking_fallback: true` e sem `tracking_version` (sem ele,
+   a reserva não disparou: o trigger, a condição de consentimento, ou um GTM com
+   a data layer renomeada, onde o evento não chega). Num site
+   com `linkedDomains`, cada link para o outro domínio abre com o `_f10x`, e o
+   destino, num browser limpo, com o `distinct_id` da origem.
 
 ## Desenvolver e publicar
 
@@ -442,7 +679,10 @@ serve nesse dia, e abre uma issue quando falha.
 
 Uma versão nova: subir a `version` no `package.json` (semver: uma mudança no
 que os forms ou os eventos levam é minor, uma que parte uma integração é
-major), `npm run build`, PR, e depois do merge, da `main`, nesta pasta:
+major), `npm run build`, e no mesmo PR, em `apps-src/account-settings`, o
+`npm install` e o `npm run install-build` (o Account Settings importa as três
+tags do `dist/` pelo nome do pacote, e a CI falha se o bundle não for o que
+elas dão); depois do merge, da `main`, nesta pasta:
 
 ```bash
 npm publish --dry-run

package/dist/direct-init.js

@@ -0,0 +1,13 @@
+/*
+  @funnel10x/tracking@2.2.0: o arranque num site com build próprio, uma vez por carregamento da página, no browser (num Next.js, um
+  componente 'use client' no layout de raiz, como o Tracking.tsx da base direct). Só se muda a chave; o consent, os checkoutHosts e os
+  linkedDomains são do site (o README do pacote). O /_t só existe com os rewrites do dist/direct-rewrites.json no vercel.json do site.
+*/
+import { init } from '@funnel10x/tracking'
+
+init({
+  key: '{{PostHog project key}}',
+  apiHost: '/_t',
+  checkoutHosts: [],
+  linkedDomains: []
+})

package/dist/direct-rewrites.json

@@ -0,0 +1,7 @@
+{
+  "rewrites": [
+    { "source": "/_t/static/:path(.*)", "destination": "https://us-assets.i.posthog.com/static/:path" },
+    { "source": "/_t/array/:path(.*)", "destination": "https://us-assets.i.posthog.com/array/:path" },
+    { "source": "/_t/:path(.*)", "destination": "https://us.i.posthog.com/:path" }
+  ]
+}

package/dist/gtm-fallback.html

@@ -0,0 +1,24 @@
+<!--
+  @funnel10x/tracking@2.2.0: a tag de reserva do GTM (Custom HTML), num site com a tag do gtm.html (decisão 1 da A2c).
+  Dispara só no evento personalizado f10x_tracking_failed, com a mesma condição de consentimento da tag do snippet; nunca em All Pages
+  nem em Window Loaded. O before_send carimba tracking_fallback em cada evento, que é o que distingue uma visita pela reserva nos dados.
+  Só se mudam a chave e o api_host (o proxy gerido da account, se o tiver, e senão o PostHog directo), os mesmos da tag do gtm.html.
+  O Account Settings do admin (Integrations, no cartão PostHog) gera-a já preenchida, com a do snippet e os acionadores.
+-->
+<script>
+  !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="addExceptionStep alias calculateEventProperties canRenderSurvey canRenderSurveyAsync cancelPendingSurvey capture captureException captureLog captureTraceFeedback captureTraceMetric clearIdentity clear_opt_in_out_capturing createPersonProfile debug displaySurvey getActiveMatchingSurveys getAllFeatureFlags getEarlyAccessFeatures getExtension getFeatureFlag getFeatureFlagPayload getFeatureFlagResult getGroups getPageViewId getSessionProperty getSurveys get_distinct_id get_explicit_consent_status get_property get_session_id get_session_replay_url group has_opted_in_capturing has_opted_out_capturing identify init isFeatureEnabled is_capturing loadToolbar on onActiveMatchingSurveysChanged onFeatureFlags onSessionId onSurveysLoaded opt_in_capturing opt_out_capturing register register_for_session register_once reloadFeatureFlags renderSurvey reset resetGroupPropertiesForFlags resetGroups resetPersonPropertiesForFlags sessionRecordingStarted setGroupPropertiesForFlags setIdentity setInternalOrTestUser setPersonProperties setPersonPropertiesForFlags set_config shutdown startExceptionAutocapture startSessionRecording stopExceptionAutocapture stopSessionRecording unregister unregister_for_session unsetPersonProperties updateEarlyAccessFeatureEnrollment updateFlags".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+  posthog.init('{{PostHog project key}}', {
+    api_host: 'https://us.i.posthog.com',
+    ui_host: 'https://us.posthog.com',
+    defaults: '2026-08-30',
+    person_profiles: 'identified_only',
+    custom_campaign_params: ['a_campaign_id', 'a_adset_id', 'a_ad_id', 'h_ad_id', 'fbc_id', 'utm_id', 'utm_placement', 'lp', 'narrative'],
+    before_send: function (event) {
+      if (event && event.event !== '$snapshot') {
+        event.properties = event.properties || {}
+        event.properties.tracking_fallback = true
+      }
+      return event
+    }
+  })
+</script>

package/dist/gtm-official.html

@@ -0,0 +1,17 @@
+<!--
+  @funnel10x/tracking@2.2.0: a tag oficial do PostHog (Custom HTML) para os hosts que ainda não passaram ao snippet, num contentor com a tag do gtm.html.
+  Dispara em All Pages, com o acionador Snippet hosts (os hosts da tag do snippet) como excepção, e o Direct hosts (os sites direct, com o
+  snippet no build) como outra. Passar um host ao snippet é acrescentá-lo à RegEx do Snippet hosts, numa só publicação.
+  Só se mudam a chave e o api_host (o proxy gerido da account, se o tiver, e senão o PostHog directo), os mesmos da tag do gtm.html.
+  O Account Settings do admin (Integrations, no cartão PostHog) gera-a já preenchida, com a do snippet e os acionadores.
+-->
+<script>
+  !function(t,e){var o,n,p,r;e.__SV||(window.posthog && window.posthog.__loaded)||(window.posthog=e,e._i=[],e.init=function(i,s,a){function g(t,e){var o=e.split(".");2==o.length&&(t=t[o[0]],e=o[1]),t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}}p||((p=t.createElement("script")).type="text/javascript",p.crossOrigin="anonymous",p.async=!0,p.src=s.api_host.replace(".i.posthog.com","-assets.i.posthog.com")+"/static/array.js",p.onerror=function(){p=null},(r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r));var u=e;for(void 0!==a?u=e[a]=[]:a="posthog",u.people=u.people||[],Object.defineProperty(u,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(t){var e="posthog";return"posthog"!==a&&(e+="."+a),t||(e+=" (stub)"),e}}),Object.defineProperty(u.people,"toString",{configurable:!0,enumerable:!0,writable:!0,value:function(){return u.toString(1)+".people (stub)"}}),o="addExceptionStep alias calculateEventProperties canRenderSurvey canRenderSurveyAsync cancelPendingSurvey capture captureException captureLog captureTraceFeedback captureTraceMetric clearIdentity clear_opt_in_out_capturing createPersonProfile debug displaySurvey getActiveMatchingSurveys getAllFeatureFlags getEarlyAccessFeatures getExtension getFeatureFlag getFeatureFlagPayload getFeatureFlagResult getGroups getPageViewId getSessionProperty getSurveys get_distinct_id get_explicit_consent_status get_property get_session_id get_session_replay_url group has_opted_in_capturing has_opted_out_capturing identify init isFeatureEnabled is_capturing loadToolbar on onActiveMatchingSurveysChanged onFeatureFlags onSessionId onSurveysLoaded opt_in_capturing opt_out_capturing register register_for_session register_once reloadFeatureFlags renderSurvey reset resetGroupPropertiesForFlags resetGroups resetPersonPropertiesForFlags sessionRecordingStarted setGroupPropertiesForFlags setIdentity setInternalOrTestUser setPersonProperties setPersonPropertiesForFlags set_config shutdown startExceptionAutocapture startSessionRecording stopExceptionAutocapture stopSessionRecording unregister unregister_for_session unsetPersonProperties updateEarlyAccessFeatureEnrollment updateFlags".split(" "),n=0;n<o.length;n++)g(u,o[n]);e._i.push([i,s,a])},e.__SV=1)}(document,window.posthog||[]);
+  posthog.init('{{PostHog project key}}', {
+    api_host: 'https://us.i.posthog.com',
+    ui_host: 'https://us.posthog.com',
+    defaults: '2026-08-30',
+    person_profiles: 'identified_only',
+    custom_campaign_params: ['a_campaign_id', 'a_adset_id', 'a_ad_id', 'h_ad_id', 'fbc_id', 'utm_id', 'utm_placement', 'lp', 'narrative']
+  })
+</script>

package/dist/gtm.html

@@ -1,10 +1,45 @@
-<!-- @funnel10x/tracking@2.0.0: a tag do GTM (Custom HTML, em All Pages), em vez da tag oficial do PostHog e nunca ao lado dela. Só se mudam a chave, o apiHost (o proxy gerido da account, se o tiver) e, numa emergência, o sdkVersion (uma versão exacta do posthog-js); uma versão nova do pacote é um ficheiro novo. -->
+<!--
+  @funnel10x/tracking@2.2.0: a tag do GTM (Custom HTML, em All Pages, com a condição de consentimento do site, se ele tiver banner).
+  Num site com esta tag, a tag oficial do PostHog só existe como reserva (decisão 1 da A2c): outra tag Custom HTML, com a mesma chave, que dispara
+  só no evento personalizado f10x_tracking_failed, que esta empurra para o dataLayer, uma vez, quando o tag.js não carrega (o jsDelivr em baixo ou
+  bloqueado, um integrity que não bate) ou carrega e não arranca (o window.f10xTracking sem version). A reserva é o dist/gtm-fallback.html, ao lado.
+  Só se mudam a chave, o apiHost (o proxy gerido da account, se o tiver), os checkoutHosts, os linkedDomains (o cross-domain, desligado com a
+  lista vazia) e, numa emergência, o sdkVersion (uma versão exacta do posthog-js); uma versão nova do pacote é um ficheiro novo.
+  O script do jsDelivr cria-se por código, com o onload e o onerror como propriedades: um atributo onload no HTML é um handler inline, que o GTM
+  copia ao recriar o script e que uma CSP com nonce não deixa correr. Um pedido pendurado conta como falhado ao fim de 10 s.
+  O evento vai para o window.dataLayer: num GTM com a data layer renomeada (o l= do snippet do GTM) a reserva não dispara, e o ponto 8 do
+  checklist do README apanha-o.
+-->
 <script>
   window.f10xTracking = {
     key: '{{PostHog project key}}',
     apiHost: '',
     sdkVersion: '',
-    checkoutHosts: []
+    checkoutHosts: [],
+    linkedDomains: []
   }
+  ;(function () {
+    var timer
+    function failed() {
+      clearTimeout(timer)
+      if (window.__f10xTracking && window.__f10xTracking.version) {
+        window.f10xTracking = window.__f10xTracking
+        return
+      }
+      if (window.__f10xTrackingFailed) return
+      window.__f10xTrackingFailed = true
+      ;(window.dataLayer = window.dataLayer || []).push({ event: 'f10x_tracking_failed' })
+    }
+    var script = document.createElement('script')
+    script.src = 'https://cdn.jsdelivr.net/npm/@funnel10x/tracking@2.2.0/dist/tag.js'
+    script.integrity = 'sha384-2j0oWs30fSU+6UtXb4WcrJ0Gi3Ezss5xWEwZ+jFI+8tqVvyJa3zwOPP5n+l99Ksn'
+    script.crossOrigin = 'anonymous'
+    script.onload = function () {
+      clearTimeout(timer)
+      if (!(window.f10xTracking && window.f10xTracking.version)) failed()
+    }
+    script.onerror = failed
+    timer = setTimeout(failed, 10000)
+    document.head.appendChild(script)
+  })()
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@2.0.0/dist/tag.js" integrity="sha384-vl05BcvhQ0/QtZcEpJZuNM5QB/vPrQB7HVeN58LFs+oG43IoUfgu6Oi6SntNrjyH" crossorigin="anonymous"></script>

package/dist/index.d.ts

@@ -17,6 +17,14 @@ export interface TrackingOptions {
   checkoutHosts?: string[]
   /** Add the missing hidden fields to lead forms (default true). */
   addFields?: boolean
+  /**
+   * Linked domains for cross-domain tracking (off by default): hosts, or registrable domains that also cover their
+   * subdomains, as a list or a string separated by commas or spaces (an entry that is not a hostname, like
+   * `*.example.com`, is ignored with a console warning). Links and forms to them carry `_f10x` on click or submit, and
+   * an `_f10x` that arrives within 2 minutes links the visitor: the origin's person and session when the page has no
+   * PostHog identity yet, or `linked_distinct_id` on every event when it has one.
+   */
+  linkedDomains?: string[] | string
   /** posthog-js options on top of this package's (turning a feature off on one site, tests). */
   posthog?: Record<string, unknown>
 }