@funnel10x/tracking 1.1.0 → 1.3.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
@@ -22,13 +23,15 @@ O que faz numa página:
   e nos links do checkout;
 - **o identify pelo id do contacto** num link de email ou de SMS
   (`?contact_id={{contact.id}}`);
-- **o email e o telefone da pessoa, quando ela os dá** (a 1.1.0, como a
-  HYROS): do URL, quando o funil os passa à página seguinte (`email`, `phone`,
-  `phoneNumber`, `phone_number`, `tel`, `telefone`), e dos campos de email e de
-  telefone de qualquer form da página, à saída do campo e no envio. O telefone
+- **o email e o telefone que a pessoa envia** (desde a 1.1.0, como a HYROS;
+  só no envio desde a 1.2.0): do URL, quando o funil os passa à página seguinte
+  (`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
   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`, `field` ou `form`), cada valor uma vez por página, e
+  `contact_source`: `url` ou `form`), cada valor uma vez por página, e
   só com o PostHog a medir. Não vão ao perfil (`$set`), que passaria o browser
   a pessoa identificada, o escalão mais caro do PostHog: o perfil recebe-os do
   identify do servidor, uma vez por contacto;
@@ -106,26 +109,54 @@ 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.3.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.** 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
+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`): o snippet escreve nos campos cujo query key é um
-dos valores, e o GHL envia-os. **Um form do GHL embebido noutro site corre num
+com o query key em `data-q`), e **um campo escondido só se enche pelo URL com
+que a página carrega**: o GHL lê o query key quando a app arranca, e envia o
+estado dele, a que o campo não está ligado (medido a 2026-10-07: um valor
+escrito no campo depois, mesmo com o evento `input`, não chega ao envio, e a tag
+do *Head tracking code* corre já depois do arranque). Por isso, num funil do
+GHL, a ponte entre o dispositivo e o contacto é o email que a pessoa envia (o
+`contact_captured`), que o admin liga ao contacto criado nesse momento; o campo
+`ph_anon_id` só se enche quando o id já vem no URL. **Um form do GHL embebido noutro site corre num
 iframe** de outro domínio, onde o script da página
 não chega. O snippet passa ao iframe, pelo URL dele, os ids e os parâmetros do
 anúncio, e os campos escondidos do form lêem-nos de lá (cada campo com o
@@ -137,24 +168,28 @@ 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 |
 
 - **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
@@ -167,6 +202,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;
@@ -176,14 +213,37 @@ 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).
+
 **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={{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}}
 ```
 
 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
@@ -191,9 +251,19 @@ dela) e `asset` em cada anúncio (o código do asset, que num anúncio de pesqui
 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={_campaign}&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, que os monta a partir dela, está no plano da Marketing (Fase M48).
+
 ## O checklist de um funil
 
 Antes de ligar o tráfego:
@@ -201,18 +271,27 @@ 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.
+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**: 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.
 

package/dist/gtm.html

@@ -1,8 +1,9 @@
-<!-- @funnel10x/tracking@1.1.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.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. -->
 <script>
   window.f10xTracking = {
     key: '{{PostHog project key}}',
+    apiHost: '',
     checkoutHosts: []
   }
 </script>
-<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.1.0/dist/tag.js" integrity="sha384-2ACrLX/l5RYZ+55HKpvkNM5uzAhAqQPoGWoGqj3w4mKUcSAMKYV8glWCJBbSDDD+" crossorigin="anonymous"></script>
+<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.3.0/dist/tag.js" integrity="sha384-BFUxhoktzA6AWF2yGaTdVq+krqyK0WqpmJfPAP3ga7hqHXxJu+WXr2lLbx6CH6G0" 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