@funnel10x/tracking 1.3.0 → 2.0.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
@@ -40,19 +47,89 @@ O que faz numa página:
   **interruptor de consentimento** do `site.json`, e a guarda das
   pré-visualizações.
 
-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.
+**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**
+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
+
+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:
+
+- **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 dispara só nos
+hosts que a escolheram (uma excepção por hostname no trigger). **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.0.0" } }
 ```
 
 ```js
@@ -61,18 +138,20 @@ 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,
   pageVersion: 3,
-  test: '/pt/f1/lp#2',
+  test: '/pt/acq_f1/webinar/lp#2',
 })
 ```
 
 - `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
   {
@@ -87,16 +166,25 @@ 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.
 - `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.
 
@@ -105,33 +193,39 @@ 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
-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.
+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@1.3.0/dist/tag.js" integrity="sha384-…" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@2.0.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.
+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.** Sem build não há o `/_t`, e com o `apiHost`
-vazio os envios vão para o `us.i.posthog.com`, que a EasyPrivacy bloqueia: a
-visita de quem tem um bloqueador não chega ao PostHog. O PostHog tem um proxy
+**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
+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
@@ -178,6 +272,7 @@ O que os forms, o iframe e os links do checkout levam:
 | os click ids | `fbclid`, `gclid`, `gbraid`, `wbraid`, `gad_source`, `gad_campaignid`, `msclkid`, `ctwa_clid` | sim, do URL | não |
 | os ids de anúncio | `a_campaign_id`, `a_adset_id`, `a_ad_id` (a convenção, abaixo), e os da HYROS `h_ad_id`, `fbc_id` | sim, do URL | só `a_ad_id`, como as UTMs |
 | `lp` | a página de entrada que o URL declara | sim, do URL | não |
+| `narrative` | o slug da narrativa declarado pela página (desde a 1.4.0) | sim, do URL | `narrative`, com o query key igual ao nome, se a location o tiver |
 
 - **Num form da página**, um campo que já existe com o nome recebe o valor se
   for escondido ou estiver vazio; os que faltam acrescentam-se escondidos, só
@@ -197,19 +292,27 @@ 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.
 
 ## 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
 
@@ -234,26 +337,45 @@ nomes sem prefixo da 1.0.0 à 1.2.0 (`ad_id`, `adset_id`, `campaign_id`,
 `adgroup_id`) saíram: nenhum anúncio os usou. Nenhum URL das três accounts
 trazia já um parâmetro `a_` (medido no mesmo dia).
 
+**O texto de cada anúncio sai do gerador de links** da Marketing Ops (o módulo
+URL Parameters, Fase M48 do plano da Marketing), que o compõe a partir da regra
+da fonte na Traffic Sources, do funil e do stage: é aí que se gera, e os dois
+modelos de baixo são a forma do que ele dá. O `utm_campaign` deixou de ser o nome
+da campanha (que chega pelo `a_campaign_id`) e é o funil e o stage,
+`<funil>_<stage>[_<temperatura>]`; o nome do ad set e o `utm_id` saíram, porque
+os ids `a_` já os dizem.
+
 **Meta**, nos *URL parameters* de cada anúncio:
 
 ```
-utm_source=meta&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_term={{adset.name}}&utm_content={{ad.name}}&utm_id={{campaign.id}}&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 conta, com o auto-tagging ligado (o
-`gclid`) e dois parâmetros personalizados: `campaign` em cada campanha (o nome
-dela) e `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):
+**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`). 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={_campaign}&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
@@ -262,22 +384,27 @@ tabela **Traffic Sources** do admin, que é nomenclatura partilhada por todas as
 accounts. Sem elas a visita chega sem origem, e o referrer de um browser in-app
 ou de um cliente de email vem quase sempre vazio, o que a conta como *direct*.
 Este README não copia a tabela, que é a fonte; o gerador de links da Marketing
-Ops, que os monta a partir dela, está no plano da Marketing (Fase M48).
+Ops (o módulo URL Parameters, Fase M48 do plano da Marketing) monta-os a partir
+dela, junta-os a um URL que já tenha parâmetros sem duplicar nenhum, e guarda
+cada link com o sítio onde foi posto.
 
 ## O checklist de um funil
 
 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.
+   `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. **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
+   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.
@@ -289,11 +416,14 @@ Antes de ligar o tráfego:
 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.
-7. **Os anúncios**: os parâmetros de cima na Meta e na Google, e os links
-   orgânicos 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.
+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`.
 
 ## Desenvolver e publicar
 
@@ -304,15 +434,52 @@ 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 é
-major), `npm run build`, PR, e depois do merge, da `main`:
+major), `npm run build`, PR, e depois do merge, da `main`, nesta pasta:
+
+```bash
+npm publish --dry-run
+```
 
 ```bash
 npm publish
 ```
 
+O primeiro confere a versão e os ficheiros sem publicar nada. **O segundo é do
+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. 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
+mostrou a versão anterior durante esses minutos; o registo, lido directamente,
+diz a verdade:
+
+```bash
+curl -s https://registry.npmjs.org/@funnel10x%2ftracking | node -e "process.stdin.on('data',d=>b+=d);let b='';process.stdin.on('end',()=>console.log(JSON.parse(b)['dist-tags']))"
+```
+
+E o `tag.js` que o jsDelivr serve tem de ter o hash do `integrity` da tag do
+GTM, senão a tag não carrega em site nenhum. As duas linhas têm de dar o mesmo
+`sha384-…`:
+
+```bash
+echo "sha384-$(curl -sL "https://cdn.jsdelivr.net/npm/@funnel10x/tracking@$(node -p "require('./package.json').version")/dist/tag.js" | openssl dgst -sha384 -binary | openssl base64 -A)"
+```
+
+```bash
+grep -o 'sha384-[^"]*' dist/gtm.html
+```
+
 O `dist/THIRD_PARTY_LICENSES.txt` leva as licenças do que vai embutido.