@funnel10x/tracking 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Funnel 10X
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,226 @@
-# Temporary Holding Version
+# @funnel10x/tracking
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+O snippet de tracking dos funis da Funnel 10X: a Fase A2 do [plano da
+atribuição](https://github.com/funnel10x/f10x-admin/blob/main/docs/plano-atribuicao.md)
+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), 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,
+  acrescentados), no URL do iframe de um form, inquérito ou calendário do GHL,
+  e nos links do checkout;
+- **o identify pelo id do contacto** num link de email ou de SMS
+  (`?contact_id={{contact.id}}`);
+- **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.
+
+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.
+
+## 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" } }
+```
+
+```js
+import { init } from '@funnel10x/tracking'
+
+init({
+  key: import.meta.env.VITE_POSTHOG_KEY,
+  apiHost: '/_t',
+  consent: site.consent,
+  pageVersion: 3,
+  test: '/pt/f1/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:
+
+  ```json
+  {
+    "rewrites": [
+      { "source": "/_t/static/:path(.*)", "destination": "https://us-assets.i.posthog.com/static/:path" },
+      { "source": "/_t/array/:path(.*)", "destination": "https://us-assets.i.posthog.com/array/:path" },
+      { "source": "/_t/:path(.*)", "destination": "https://us.i.posthog.com/:path" }
+    ]
+  }
+  ```
+
+  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.
+- `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.
+- `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.
+
+Uma página cujo caminho acaba em `_` seguido de algarismos (a pré-visualização
+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 e os hosts do checkout.
+
+```html
+<script>
+  window.f10xTracking = {
+    key: '{{PostHog project key}}',
+    checkoutHosts: []
+  }
+</script>
+<script src="https://cdn.jsdelivr.net/npm/@funnel10x/tracking@1.0.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.
+
+**O form do GHL 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
+*query key* igual ao nome). Se o form não os ler do URL, a mesma tag entra no
+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.
+
+## Os campos
+
+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 |
+
+- **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ê.
+- **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
+  `client_reference_id` com o distinct id, que é o que chega à sessão de
+  checkout.
+- **Num checkout criado no servidor** (uma sessão do Stripe em código),
+  `window.f10xTracking.fields()` dá os mesmos valores, para a metadata.
+
+## A API
+
+`init(options)` (ou a tag) devolve, e põe em `window.f10xTracking`:
+
+- `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.
+
+## Os modelos de parâmetros de URL
+
+**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}}
+```
+
+O nome do anúncio acaba no código do asset (decisão 10 do plano), e é por isso
+que vai no `utm_content`.
+
+**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):
+
+```
+utm_source=google&utm_medium=cpc&utm_campaign={_campaign}&utm_term={keyword}&utm_content={_asset}&campaign_id={campaignid}&adgroup_id={adgroupid}&ad_id={creative}
+```
+
+## 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, 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
+   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`
+   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.
+
+## Desenvolver e publicar
+
+```bash
+npm ci
+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/`).
+
+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`:
+
+```bash
+npm publish
+```
+
+O `dist/THIRD_PARTY_LICENSES.txt` leva as licenças do que vai embutido.