@funnel10x/tracking 1.3.0 → 1.4.0

package/README.md

@@ -40,6 +40,15 @@ O que faz numa página:
   **interruptor de consentimento** do `site.json`, e a guarda das
   pré-visualizações.
 
+**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
@@ -63,7 +72,7 @@ init({
   apiHost: '/_t',
   consent: site.consent,
   pageVersion: 3,
-  test: '/pt/f1/lp#2',
+  test: '/pt/acq_f1/webinar/lp#2',
 })
 ```
 
@@ -120,15 +129,16 @@ os hosts do checkout.
     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@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.
 
-**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,
@@ -178,6 +188,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ó
@@ -234,10 +245,18 @@ 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_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
@@ -245,13 +264,14 @@ que vai no `utm_content`. O `utm_source` é `meta`, como na Traffic Sources e no
 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`) 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):
 
 ```
-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={keyword}&utm_content={_asset}&a_campaign_id={campaignid}&a_adset_id={adgroupid}&a_ad_id={creative}
 ```
 
 ## Os links orgânicos
@@ -262,7 +282,9 @@ 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
 
@@ -277,7 +299,9 @@ Antes de ligar o tráfego:
    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.
+   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.
 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,8 +313,8 @@ 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.
+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.
@@ -309,10 +333,42 @@ admin, em `tests/api/tracking.test.mjs` (a limpeza, sem browser) e
 
 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.
+
+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.

package/dist/gtm.html

@@ -1,4 +1,4 @@
-<!-- @funnel10x/tracking@1.3.0: a tag do GTM (Custom HTML, em All Pages). Só se mudam a chave e, se a account tiver o proxy gerido do PostHog, o apiHost; uma versão nova é um ficheiro novo. -->
+<!-- @funnel10x/tracking@1.4.0: a tag do GTM (Custom HTML, em All Pages). Só se mudam a chave e, se a account tiver o proxy gerido do PostHog, o apiHost; uma versão nova é um ficheiro novo. -->
 <script>
   window.f10xTracking = {
     key: '{{PostHog project key}}',
@@ -6,4 +6,4 @@
     checkoutHosts: []
   }
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.3.0/dist/tag.js" integrity="sha384-BFUxhoktzA6AWF2yGaTdVq+krqyK0WqpmJfPAP3ga7hqHXxJu+WXr2lLbx6CH6G0" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.4.0/dist/tag.js" integrity="sha384-UTBEFP06SUs6EqWR2bkYb7Rq6QEj2SWvMGpf1/3g4uhyNGYMzyucjjeHtYYoW/xD" crossorigin="anonymous"></script>