@funnel10x/tracking 1.2.0 → 1.4.0

package/README.md

@@ -7,8 +7,9 @@ no npm como pacote público, pela versão.
 
 O que faz numa página:
 
-- **o PostHog** (o posthog-js, embutido), 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
+- **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
@@ -39,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
@@ -62,7 +72,7 @@ init({
   apiHost: '/_t',
   consent: site.consent,
   pageVersion: 3,
-  test: '/pt/f1/lp#2',
+  test: '/pt/acq_f1/webinar/lp#2',
 })
 ```
 
@@ -108,22 +118,45 @@ 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 e os hosts do checkout.
+só se trocam a chave, o `apiHost` (se a account tiver o proxy gerido, abaixo) e
+os hosts do checkout.
 
 ```html
 <script>
   window.f10xTracking = {
     key: '{{PostHog project key}}',
+    apiHost: '',
     checkoutHosts: []
   }
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.0.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>
 ```
 
-Sem `site.json` não há interruptor: o snippet corre como a tag o deixar (as
-condições de consentimento da tag no GTM, se o site tiver um banner). 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 `@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, 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,
+`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
+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
+origem no `Referer`, e não o URL com a query string.
+
+**O consentimento.** Sem `site.json` o snippet não tem interruptor, e quem
+decide se ele corre é o sítio onde a tag está. No GTM, corre como as condições
+de consentimento da tag deixarem (o banner ligado ao GTM); no *Head tracking
+code* do GHL, ou no campo de código de outra plataforma, corre sempre, também
+para quem recusou. Por isso, **num site com banner, a tag fica no GTM, com a
+condição do consentimento de analytics; num site sem banner, pode ir para o
+head**, o que a livra de um GTM bloqueado (a EasyPrivacy bloqueia o
+`googletagmanager.com`). É uma regra de onde se põe a tag, e não código.
 
 **Numa página de um funil do GHL, o form é nativo** (sem `<form>`, cada campo
 com o query key em `data-q`), e **um campo escondido só se enche pelo URL com
@@ -145,24 +178,29 @@ ao form o que veio no URL dele.
 
 O que os forms, o iframe e os links do checkout levam:
 
-| campo | o que é | sem consentimento |
-| --- | --- | --- |
-| `ph_anon_id` | o id do dispositivo no PostHog (o anónimo de origem) | não |
-| `ph_distinct_id` | o distinct id agora (o id do contacto, depois do identify) | não |
-| `ph_session_id` | a sessão do PostHog | não |
-| `contact_id` | o id do contacto que veio num link desta sessão | não |
-| as UTMs | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `utm_id`, `utm_placement` | sim, do URL |
-| os click ids | `fbclid`, `gclid`, `gbraid`, `wbraid`, `gad_source`, `gad_campaignid`, `msclkid`, `ctwa_clid` | sim, do URL |
-| os ids de anúncio | `ad_id`, `adset_id`, `campaign_id`, `adgroup_id`, e os da HYROS `h_ad_id`, `fbc_id` | sim, do URL |
-| `lp` | a página de entrada que o URL declara | sim, do URL |
+| campo | o que é | sem consentimento | campo custom no GHL |
+| --- | --- | --- | --- |
+| `ph_anon_id` | o id do dispositivo no PostHog (o anónimo de origem) | não | opcional: só se enche quando o id chega no URL |
+| `ph_distinct_id` | o distinct id agora (o id do contacto, depois do identify) | não | não |
+| `ph_session_id` | a sessão do PostHog | não | não |
+| `contact_id` | o id do contacto que veio num link desta sessão | não | não |
+| as UTMs | `utm_source`, `utm_medium`, `utm_campaign`, `utm_content`, `utm_term`, `utm_id`, `utm_placement` | sim, do URL | só `utm_source`, `utm_medium` e `utm_campaign`, nas locations de um site `direct` com consentimento |
+| 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ó
   num form de lead (com um campo de email ou de telefone) e nunca num com
   `data-f10x-skip`. Voltam a preencher-se no envio, com os valores desse
   momento.
-- **Num form do GHL**, os campos custom do contacto com estes nomes, que a A5
-  lê.
+- **Num form do GHL** não há campos a pôr: a ponte para o contacto é o email
+  que a pessoa envia (o `contact_captured`), e o click id do contacto é a
+  atribuição nativa do GHL, que a A5 lê. Os quatro campos de atribuição da
+  tabela só existem nas locations que recebam leads de um site `direct` com
+  `consent: true`: quem recusa não tem PostHog, e um contacto criado pelo
+  webhook não tem atribuição nativa (plano, A2 revista a 2026-10-07).
 - **Nos links do checkout** (os do Stripe e os hosts em `checkoutHosts`), os ids
   sobrepõem-se ao que o link traga, e os parâmetros do anúncio só entram se o
   link não tiver os seus. Num Payment Link do Stripe vai também o
@@ -175,6 +213,8 @@ O que os forms, o iframe e os links do checkout levam:
 
 `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;
 - `fields()`: os valores de cima, agora;
 - `grant()`, `deny()`, `consent()`: o interruptor de um site `direct`;
 - `onReady(fn)`: quando o PostHog estiver a medir;
@@ -184,24 +224,68 @@ O que os forms, o iframe e os links do checkout levam:
 
 ## Os modelos de parâmetros de URL
 
+**Os nomes vão nas UTMs, os ids em três parâmetros nossos**, com o prefixo
+`a_` (de *attribution*), como a HYROS tem o `h_`, e desde a 1.3.0. Um nome é
+editável no gestor de anúncios e um rename não dá erro nenhum; o id nasce com
+o anúncio. Os três querem dizer o mesmo em todas as plataformas, e a plataforma
+diz-se no `utm_source`:
+
+| nível | parâmetro | Meta | Google |
+| --- | --- | --- | --- |
+| a campanha | `a_campaign_id` | `{{campaign.id}}` | `{campaignid}` |
+| o conjunto (o ad set da Meta, o ad group da Google) | `a_adset_id` | `{{adset.id}}` | `{adgroupid}` |
+| o anúncio | `a_ad_id` | `{{ad.id}}` | `{creative}` |
+
+Na HYROS, o `h_ad_id` é o anúncio em todas, mas o nível de cima muda de nome e
+de nível com a plataforma: o `fbc_id` é o ad set na Meta, o `gc_id` é a
+campanha na Google; na Meta a campanha não vai, e na Google o ad group também
+não. O `h_ad_id` e o `fbc_id` continuam aceites, pelos anúncios da IMO Circle
+que ainda os trazem (4.324 pageviews desde abril, medidos a 2026-10-08). Os
+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=facebook&utm_medium=paid_social&utm_campaign={{campaign.name}}&utm_term={{adset.name}}&utm_content={{ad.name}}&utm_id={{campaign.id}}&utm_placement={{placement}}&campaign_id={{campaign.id}}&adset_id={{adset.id}}&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
-que vai no `utm_content`.
+que vai no `utm_content`. 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`) 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}&campaign_id={campaignid}&adgroup_id={adgroupid}&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
+
+Um link que não é anúncio (a bio do Instagram, a descrição de um vídeo, um
+email, o WhatsApp, um parceiro) leva as UTMs da fonte dele, pelas regras da
+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 (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:
@@ -209,18 +293,29 @@ 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, no GTM.
-2. **O consentimento**: o `consent` do `site.json` escrito, e o banner a chamar
-   `grant()` e `deny()`; num site de fora, as condições da tag no GTM.
-3. **Os forms**: cada form do GHL com os campos escondidos da tabela, com o
-   *query key* igual ao nome; o workflow do identify no envio; e um envio de
-   teste com `?utm_source=teste&gclid=teste` deixa os campos preenchidos no
-   contacto.
-4. **Os links de email e de SMS** levam `contact_id={{contact.id}}`.
-5. **O checkout**: o host em `checkoutHosts` (o Stripe já lá está), e num
+   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.
+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.
+4. **Os forms**: um envio de teste, escrito à mão numa página aberta com
+   `?utm_source=teste`, deixa no PostHog um `contact_captured` com o email,
+   no momento do envio, e o contacto no GHL; um email escrito e não enviado não
+   deixa nada. Num site `direct` com consentimento, a location tem os quatro
+   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.
-6. **Os anúncios**: os parâmetros de cima na Meta e na Google.
-7. **A prova**: um pageview aberto com `?email=teste@example.com&utm_source=teste`
+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.
 
@@ -238,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,8 +1,9 @@
-<!-- @funnel10x/tracking@1.2.0: a tag do GTM (Custom HTML, em All Pages). Só se muda a chave; 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}}',
+    apiHost: '',
     checkoutHosts: []
   }
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.2.0/dist/tag.js" integrity="sha384-HBEVk3iHklebWrwCgMWKmqvpecTCfdlKHwUh1ic9eiqkpraFHWtDpGguHg+5mxw/" 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>

package/dist/index.d.ts

@@ -21,7 +21,7 @@ export interface TrackingOptions {
 
 export interface Tracking {
   version: string
-  mode: 'direct' | 'tag' | 'preview' | 'frame'
+  mode: 'direct' | 'tag' | 'preview' | 'frame' | 'conflict'
   consent(): 'granted' | 'denied' | null
   grant(): void
   deny(): void