@funnel10x/tracking 1.4.0 → 2.1.0

package/README.md

@@ -5,22 +5,29 @@ atribuição](https://github.com/funnel10x/f10x-admin/blob/main/docs/plano-atrib
 do admin. Vive em `packages/tracking/` do `funnel10x/f10x-admin`, e publica-se
 no npm como pacote público, pela versão.
 
-O que faz numa página:
-
-- **o PostHog** (o posthog-js, embutido: o snippet **é** o PostHog, e numa
-  página que já tenha outro não arranca, ver o checklist), com os ids de
-  anúncio como parâmetros de campanha, e **cada evento limpo antes de sair**: o URL fica com o host, o
-  caminho e só os parâmetros de campanha da allow-list (`src/clean.js`), no
-  evento, no perfil (`$set`, `$set_once`), no cookie do PostHog, nos heatmaps
-  e na gravação de sessão (onde os pedidos de rede se gravam sem o corpo). O
-  email, o nome, o telefone e as respostas de um quiz que um funil
-  passe na query string ficam no browser;
-- **o FingerprintJS v5** (MIT), sem o pedido de monitorização que ele faz por
-  omissão a um servidor deles; o `visitorId` vai em cada evento (`fingerprint`);
-- **os ids e os parâmetros do anúncio nos forms**: nos campos escondidos de
-  cada form de lead da página (os que já existem com o nome, e os que faltam,
+**Desde a 2.0.0 (Fase A2b, 2026-10-14) o snippet é o PostHog oficial com os
+nossos extras por cima**: o mesmo `array.js` que a tag oficial carrega, do mesmo
+CDN, no canal 1.x, e o SDK não vem neste ficheiro. O que faz numa página:
+
+- **o PostHog oficial**, por um loader: o stub (o `window.posthog` com o
+  `__SV`, como o do snippet oficial) posto antes de tudo, e o `array.js` do CDN
+  do PostHog no canal 1.x (`/static/1/array.js`, pelo host dos assets do
+  `apiHost`, ou pelo `/_t` de um repo `direct`). As funcionalidades ficam como
+  na instalação oficial (feature flags, surveys, conversations, product tours;
+  os web experiments desligados, como lá), e um site desliga uma pelas
+  `posthog` das opções. **O PostHog recebe tudo**: o snippet não limpa nada, e o
+  URL chega inteiro, com o que a query string traga (o email, as respostas de
+  um quiz, um `token`). Quem apara é o admin, na ingestão (abaixo);
+- **o FingerprintJS v5** (MIT, embutido), sem o pedido de monitorização que ele
+  faz por omissão a um servidor deles. O primeiro `$pageview` espera por ele
+  até 1 s, contado com o carregamento dele, e cada evento leva o `fingerprint`
+  e o `fingerprint_ms` (o tempo que levou, ou o tecto, 1000);
+- **a lista de atribuição nos forms, no CRM e no checkout, e só ela**: os ids
+  e os 22 parâmetros do anúncio (`src/params.js`) nos campos escondidos de cada
+  form de lead da página (os que já existem com o nome, e os que faltam,
   acrescentados), no URL do iframe de um form, inquérito ou calendário do GHL,
-  e nos links do checkout;
+  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 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;
@@ -28,7 +35,7 @@ O que faz numa página:
   (`email`, `phone`, `phoneNumber`, `phone_number`, `tel`, `telefone`), e dos
   campos de email e de telefone do form que ela envia (o `submit` de um
   `<form>`, ou o botão de enviar do form nativo do GHL). O de um form que ela
-  não enviou não sai do browser. O telefone
+  não enviou não vai. O telefone
   ganha o indicativo do seletor de país (o intl-tel-input), que é o que um
   seletor costuma esconder. Vão num evento `contact_captured` (com
   `contact_source`: `url` ou `form`), cada valor uma vez por página, e
@@ -38,30 +45,114 @@ 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 o `tracking_version`, a `page_version`, o `ab_test`
-e o `fingerprint` de cada evento, e o email e o telefone do `contact_captured`
-só em hash. O histórico de um funil, que chegou ao PostHog antes deste snippet
-com o URL inteiro, é aparado lá pela mesma allow-list do `src/clean.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).
-
-O posthog-js e o FingerprintJS vão dentro do ficheiro, pela versão que este
-pacote fixa, e não se resolvem no site. O que fica de fora são as extensões que
-o posthog-js carrega quando o projeto as liga (o gravador de sessão, os dead
-clicks, os web vitals), que vêm do PostHog pela mesma versão do posthog-js
-(`/static/<versão>/…`, pelo proxy num repo `direct`): esse código não passa
-pelo `integrity` da tag.
+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; 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 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 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
+  `window.f10xTracking.mode` fica `conflict`;
+- **a oficial depois deste**: o stub deste é o `window.posthog`, e o `init`
+  dela entra na fila dele, sem efeito (o stub nunca insere um script, por isso
+  não há outro `array.js`); avisa na consola, e cada evento leva
+  `tracking_conflict: true`, que é o sinal nos dados. A
+  `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 de sempre dispara
+só nos hosts que a escolheram, por uma **condição de inclusão** por hostname (a
+lista desses hosts, e não uma excepção, para um host novo entrar sem disparar
+nada), e 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 é
+`2026-08-30`; uma tag oficial no mesmo domínio passa a ela.
+
+### O que se actualiza sozinho, e o que não
+
+| camada | quem a dá | actualiza-se |
+| --- | --- | --- |
+| o SDK (`array.js`) | o CDN do PostHog, no canal 1.x | **sozinho**, como na tag oficial: o canal tem 4 horas de cache, e uma versão nova chega a todos os sites nesse prazo |
+| as extensões (o gravador, os surveys) | o mesmo CDN | seguem a versão do `array.js` (`strict_script_versioning: true`) |
+| o comportamento por omissão do SDK | a data dos `defaults`, fixa neste pacote | só com uma versão nova do pacote |
+| os extras (este ficheiro) | o jsDelivr pela versão, com o `integrity`, numa tag; o `package.json`, num `direct` | **nunca sozinhos**: decidem o que vai para os forms, o CRM e o checkout, e uma mudança não anunciada chegaria a todos os sites ao mesmo tempo. Num `direct`, uma versão nova do pacote é uma release da base |
+
+Os testes A/B de um site `direct` correm sobre um SDK externo: uma versão nova
+chega a todas as versões de um teste ao mesmo tempo, e a comparação entre elas
+continua válida. O admin guarda a versão do SDK e a data dos `defaults` de cada
+toque, para uma análise se poder partir por elas.
+
+**O `sdkVersion`, numa emergência.** Uma versão exacta do posthog-js
+(`'1.438.9'`) fixa o caminho exacto do `array.js`, que é imutável no CDN: numa
+tag, na configuração dela; num repo `direct`, pela variável de ambiente da
+Vercel (`VITE_POSTHOG_SDK_VERSION` num `static`, `NEXT_PUBLIC_POSTHOG_SDK_VERSION`
+num `nextjs`), que muda com um redeploy, sem PR. É a resposta a uma versão do
+SDK que parta um site, até uma versão nova do pacote; o workflow diário
+`tracking-sdk.yml` do admin corre os testes contra o `array.js` que o CDN serve
+nesse dia, e abre uma issue quando falham.
+
+### O que muda por o PostHog receber tudo
+
+O que a 1.x limpava no browser vai inteiro ao PostHog (decisão 2 da A2b), e
+isso tem três consequências que se sabem:
+
+- **o cookie do PostHog leva o URL de entrada em bruto** (o
+  `$initial_person_info`), e o cookie é partilhado por todos os subdomínios do
+  domínio registável;
+- **as gravações seguem as definições do projeto**, com os corpos dos pedidos
+  de rede se o projeto os ligar (um form de lead manda o email);
+- **o `Referer` de um pedido ao `/_t`** (do mesmo domínio) leva o URL inteiro,
+  e o site volta à política do browser (`strict-origin-when-cross-origin`): o
+  `strict-origin` existia por isso, e a razão caiu.
+
+**Um site com CSP** tem de deixar passar o host dos assets do PostHog no
+`script-src` (o `us-assets.i.posthog.com`, ou o proxy da account): o SDK deixou
+de vir no ficheiro. É uma das razões de a 2.0.0 ser major.
 
 ## Num repo `direct`: embutido no build
 
 O `package.json` do repo pina a versão exacta (sem `^`), e o build embute-o:
 
 ```json
-{ "dependencies": { "@funnel10x/tracking": "1.0.0" } }
+{ "dependencies": { "@funnel10x/tracking": "2.1.0" } }
 ```
 
 ```js
@@ -70,7 +161,9 @@ import { init } from '@funnel10x/tracking'
 init({
   key: import.meta.env.VITE_POSTHOG_KEY,
   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',
 })
@@ -79,9 +172,10 @@ init({
 - `key`: a chave do projeto PostHog da account (`phc_…`), pela variável de
   ambiente da Vercel (`VITE_POSTHOG_KEY` num `static`, `NEXT_PUBLIC_POSTHOG_KEY`
   num `nextjs`). É pública: vai no HTML de qualquer maneira.
-- `apiHost: '/_t'`: os eventos vão pelo **proxy no domínio do site**, que livra
-  os envios das listas de bloqueio (a EasyPrivacy bloqueia o `posthog.com`). O
-  `vercel.json` do repo leva os três rewrites, por esta ordem:
+- `apiHost: '/_t'`: o SDK e os eventos vão pelo **proxy no domínio do site**,
+  que os livra das listas de bloqueio (a EasyPrivacy bloqueia o `posthog.com`):
+  o `array.js` pede-se a `/_t/static/1/array.js`. O `vercel.json` do repo leva
+  os três rewrites, por esta ordem:
 
   ```json
   {
@@ -96,16 +190,27 @@ init({
   O padrão é `:path(.*)` e não `:path*`, que não apanha a barra final dos
   envios (`/e/`) e lhes responde 404 (medido em produção). O `_` à frente
   garante que não colide com um funil (a base não deixa um nome
-  de funil começar por `_`). **E o site leva `Referrer-Policy: strict-origin`**
-  (nos `headers` do `vercel.json`): o proxy é do mesmo domínio, e com a política
-  por omissão o browser manda-lhe o URL inteiro da página no `Referer`, com o
-  que a query string traga, e o rewrite reencaminha-o para o PostHog.
+  de funil começar por `_`). Até à 1.x o site levava `Referrer-Policy:
+  strict-origin`, para o `Referer` de um pedido ao proxy não levar o URL
+  inteiro; desde a 2.0.0 o PostHog recebe-o de qualquer maneira, e a base volta
+  à política do browser.
+- `sdkVersion`: vazio, o canal 1.x do CDN; uma versão exacta só numa
+  emergência (acima), pela variável de ambiente da Vercel
+  (`VITE_POSTHOG_SDK_VERSION` num `static`, `NEXT_PUBLIC_POSTHOG_SDK_VERSION` num
+  `nextjs`), que o `_scripts/tracking.mjs` e o `Tracking.tsx` da base lêem.
 - `consent`: o do `site.json`. Com `true`, o snippet não mede nem guarda nada
   até à escolha: os forms levam só os parâmetros do anúncio tirados do URL, e o
   banner do site chama `window.f10xTracking.grant()` no sim e `.deny()` no não
-  (ou para retirar o sim, que pára o PostHog e apaga o que ele guardou). A
-  escolha guarda-se em `localStorage` (`f10x_consent`), e a página seguinte
-  arranca sozinha. Com `false`, mede logo.
+  (ou para retirar o sim, que pára o PostHog e apaga o que ele guardou). **Antes
+  do sim nada se pede, nem o `array.js`**: o padrão que o PostHog recomenda,
+  carregar com a recolha desligada, pede a configuração remota antes da
+  escolha. Um não antes de o SDK chegar cancela o arranque (o `init` sai da
+  fila, e o `array.js` não se pede). A escolha guarda-se em `localStorage`
+  (`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.
 
@@ -114,26 +219,72 @@ de uma versão) não mede nada nem mexe nos forms.
 
 ## Num site que não é repo nosso: a tag do GTM
 
-Num funil do GHL 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), **pela versão fixa**
-no URL do jsDelivr e com o hash do ficheiro no `integrity`. A tag de cada versão
+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, 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`. 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) e
-os hosts do checkout.
+só se trocam a chave, o `apiHost` (se a account tiver o proxy gerido, abaixo),
+os hosts do checkout, os domínios ligados (*O cross-domain*, abaixo; vazio,
+desligado) e, numa emergência, o `sdkVersion`.
 
 ```html
 <script>
   window.f10xTracking = {
     key: '{{PostHog project key}}',
     apiHost: '',
-    checkoutHosts: []
+    sdkVersion: '',
+    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.1.0/dist/tag.js'
+    script.integrity = 'sha384-…'
+    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@1.4.0/dist/tag.js" integrity="sha384-…" crossorigin="anonymous"></script>
 ```
 
-Uma versão nova é uma tag nova, nunca `@1` nem `@latest`: o GTM de cada site
-diz que versão corre, e o `tracking_version` de cada evento confirma-o.
+**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
+confirma-o. O SDK, esse, actualiza-se sozinho, pelo CDN do PostHog.
 
 **O proxy gerido do PostHog, opcional.** Sem build não há o `/_t`, e com o
 `apiHost` vazio os envios vão para o `us.i.posthog.com`: funciona, mas a
@@ -141,7 +292,8 @@ EasyPrivacy bloqueia-o, e a visita de quem tem um bloqueador não chega ao
 PostHog. O PostHog tem um proxy
 gerido, um subdomínio da account (um CNAME para o PostHog, nas definições da
 organização, *Managed reverse proxy*) que recebe os envios e os passa ao
-PostHog. Com ele, o `apiHost` da tag é esse subdomínio: na IR,
+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;
 o uBlock Origin no Firefox, que lê o CNAME, apanha na mesma, e quanto se
@@ -174,6 +326,77 @@ 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 que leva:
+
+- **o snippet oficial do PostHog**, copiado das definições do projeto (o stub
+  com o `__SV`), com o `posthog.init` de baixo no lugar do dele;
+- **a mesma chave e o mesmo `api_host`** da tag do snippet: o proxy gerido da
+  account se ela o tiver (o `apiHost` da tag), senão `https://us.i.posthog.com`;
+- **a data de `defaults` do pacote** (`2026-08-30`, a mesma em todas as
+  instalações do domínio registável) e `person_profiles: 'identified_only'`;
+- **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.
+
+```html
+<script>
+  /* aqui o stub do snippet oficial do PostHog, copiado das definições do projeto, sem o posthog.init dele */
+  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>
+```
+
+O `custom_campaign_params` é o do pacote, para os ids de anúncio irem como
+propriedades nas duas instalações. **O trigger é um evento personalizado**, com
+o nome `f10x_tracking_failed`, e **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 de sempre, em All Pages, sem `before_send`, com a condição de inclusão por
+hostname só nos hosts que escolhem a oficial (o `app.piko.com`); 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` no `app.piko.com`, que não é
+reserva nenhuma. A tag do snippet leva a excepção para os hosts `direct` (onde
+o snippet vai no build) e para os que escolhem a 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:
@@ -208,19 +431,97 @@ O que os forms, o iframe e os links do checkout levam:
   checkout.
 - **Num checkout criado no servidor** (uma sessão do Stripe em código),
   `window.f10xTracking.fields()` dá os mesmos valores, para a metadata.
+  Os `ph_distinct_id`, `ph_session_id`, `ph_anon_id` e `contact_id` chegam ao
+  admin pela A4, com forma de id. A `sale_checkout_keys` expõe-os, e a
+  `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.
 
 ## A API
 
 `init(options)` (ou a tag) devolve, e põe em `window.f10xTracking`:
 
 - `mode`: `tag` ou `direct`; `frame` num iframe, `preview` numa
-  pré-visualização, e `conflict` quando a página já tem outro PostHog;
+  pré-visualização, e `conflict` quando a página já tinha outro PostHog antes
+  deste (um que chegue depois não muda o `mode`: deixa `tracking_conflict` nos
+  eventos);
 - `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;
-- `posthog`: a instância, para o que não está aqui.
+- `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.
 
 ## Os modelos de parâmetros de URL
 
@@ -256,24 +557,34 @@ os ids `a_` já os dizem.
 **Meta**, nos *URL parameters* de cada anúncio:
 
 ```
-utm_source=meta&utm_medium=paid_social&utm_campaign=acq_f1_webinar_cold&utm_content={{ad.name}}&utm_placement={{placement}}&a_campaign_id={{campaign.id}}&a_adset_id={{adset.id}}&a_ad_id={{ad.id}}
+utm_source=meta&utm_medium=paid_social&utm_campaign=acq_f1_webinar_cold&utm_term={{campaign.name}} >> {{adset.name}}&utm_content={{ad.name}}&utm_placement={{placement}}&a_campaign_id={{campaign.id}}&a_adset_id={{adset.id}}&a_ad_id={{ad.id}}
 ```
 
 O nome do anúncio acaba no código do asset (decisão 10 do plano), e é por isso
-que vai no `utm_content`. O `utm_source` é `meta`, como na Traffic Sources e nos
+que vai no `utm_content`; o `utm_term` leva a campanha e o ad set, separados por
+` >> ` (Fase M60 do plano da Marketing), só para se ler no PostHog: nenhum
+código o lê, e quem liga o clique ao anúncio são os ids `a_`. O `utm_source` é `meta`, como na Traffic Sources e nos
 anúncios das três accounts (45.819 pageviews com `fbclid` em 90 dias, medidos a
 2026-10-08); até à 1.2.0 este modelo dizia `facebook`, que nenhum usava.
 
 **Google**, no *Final URL suffix* da campanha (ou do ad group, ou do anúncio:
 o `utm_campaign` é o do funil e do stage, e por isso não vai ao nível da conta),
-com o auto-tagging ligado (o `gclid`) e um parâmetro personalizado, `asset`, em
-cada anúncio (o código do asset, que num anúncio de pesquisa, num responsive
-display ou na Performance Max não chega pelo nome):
+com o auto-tagging ligado (o `gclid`). A Google não tem macro para nomes, só
+para ids, e por isso os nomes vão por três parâmetros personalizados, escritos à
+mão, com o nome só de letras e dígitos e a referência com o `_` à frente:
+`campaign` (`{_campaign}`) na campanha, `adgroup` (`{_adgroup}`) em cada ad
+group e `ad` (`{_ad}`) em cada anúncio (o nome dele, que acaba no código do
+asset; num anúncio de pesquisa, que não tem campo de nome, é o único nome que
+leva). Sem eles chegam os ids `a_`, que
+são a garantia. Numa campanha de pesquisa o `utm_term` leva a keyword no fim, e
+o ` >> ` vai codificado:
 
 ```
-utm_source=google&utm_medium=cpc&utm_campaign=acq_f1_webinar&utm_term={keyword}&utm_content={_asset}&a_campaign_id={campaignid}&a_adset_id={adgroupid}&a_ad_id={creative}
+utm_source=google&utm_medium=cpc&utm_campaign=acq_f1_webinar&utm_term={_campaign}%20%3E%3E%20{_adgroup}%20%3E%3E%20{keyword}&utm_content={_ad}&a_campaign_id={campaignid}&a_adset_id={adgroupid}&a_ad_id={creative}
 ```
 
+Fora da pesquisa, o mesmo sem o `%20%3E%3E%20{keyword}`.
+
 ## Os links orgânicos
 
 Um link que não é anúncio (a bio do Instagram, a descrição de um vídeo, um
@@ -291,17 +602,20 @@ cada link com o sítio onde foi posto.
 Antes de ligar o tráfego:
 
 1. **O snippet carrega pela versão**: num repo `direct`, a versão exacta no
-   `package.json`, a chave na variável de ambiente e os rewrites 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`.
-2. **Nenhum outro PostHog na página**: 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. Este
-   snippet já é o PostHog, e com outro na página não arranca (avisa na
-   consola, e o `window.f10xTracking.mode` fica `conflict`). Com a mesma chave
-   não se perde nada: quem volta mantém o id anónimo, e o URL inicial que o
-   outro deixou no cookie reescreve-se limpo. **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.
+   `package.json` (a da base), a chave na variável de ambiente e os rewrites
+   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. **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
+   todas as instalações do domínio registável** (a deste pacote).
 3. **O consentimento**: o `consent` do `site.json` escrito, e o banner a chamar
    `grant()` e `deny()`; num site de fora, a tag no GTM com a condição do
    consentimento se o site tiver banner, e no head só se não tiver.
@@ -315,9 +629,19 @@ Antes de ligar o tráfego:
    checkout em código os `fields()` na metadata.
 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**: um pageview aberto com `?email=teste@example.com&utm_source=teste`
-   chega ao PostHog (Activity, no projeto da account) com a `utm_source` e sem
-   o `email`, no evento e no perfil, e com o `tracking_version` da versão.
+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
 
@@ -328,8 +652,11 @@ npm run build
 
 O `dist/` commita-se, como o build das apps do admin, e a CI refaz-o e falha se
 não der os mesmos bytes: o que se publica é o que se testou. Os testes estão no
-admin, em `tests/api/tracking.test.mjs` (a limpeza, sem browser) e
-`tests/tracking.spec.mjs` (o snippet numa página, contra o `dist/`).
+admin, em `tests/api/tracking.test.mjs` (as listas e o pacote, sem browser) e
+`tests/tracking.spec.mjs` (o snippet numa página, contra o `dist/`, com o
+`array.js` da devDependency servido sem rede). O workflow `tracking-sdk.yml`
+corre o mesmo spec uma vez por dia contra o `array.js` que o CDN do PostHog
+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 é
@@ -348,7 +675,9 @@ dono**: a conta do npm (`funnel10x-org`) tem 2FA, e o `npm publish` pede uma
 autenticação no browser (*EOTP: This operation requires a one-time
 password*) mesmo com a sessão iniciada (medido a 2026-10-08, na 1.3.0). Um
 agente prepara a pasta na `main` e corre o primeiro, e o dono corre o segundo
-no terminal dele.
+no terminal dele. A alternativa sem OTP é o *trusted publishing* do npm (a
+publicação pela CI do GitHub, sem token), que é configuração do dono no
+npmjs.com.
 
 Depois de publicar, o npm avisa que a versão *may take a few minutes to become
 available*: espera-se, e só então se confirma. O `npm view` lê de uma cache e