Marketing Tracking
:::tip Movido para Marketing Docs Esta documentação foi reorganizada e expandida em Marketing Docs — uma surface dedicada pra quem opera marketing, tráfego, CRM e BI. Inclui:
- Atribuição (UTMs, clicked-IDs, affiliate)
- Cookies + Headers
- Plataformas (GTM, Meta, Google Ads, Kwai, Taboola, TikTok, etc)
- Catálogo de eventos
- Contract BFF — eventos backend-only
- Remarketing first-party
- Privacidade & LGPD
- Config map por brand
- Operação (testar, debug, anti-patterns) :::
Pra time de dev
Esta página fica como pointer pra Marketing Docs. Time de dev consulta lá pra entender o comportamento que o front implementa.
Pra referência de código (pontos de extensão, entry points, testes), use os links abaixo:
Entry points no front-web-base
| Surface | Arquivo |
|---|---|
| Server-side capture | app/utils/tracking.server.ts (captureTrackingFromRequest) |
| Client-side capture | app/utils/tracking.ts (parse, merge, persist) |
| Client component | app/components/tracking/TrackingCapture.tsx |
| Root loader integration | app/root.tsx |
| Signup payload | app/modules/register/flow.ts (buildRegisterPayload) |
| Deposit payload | @cactus-agents/payments → buildDepositPayload |
| Headers automáticos | @cactus-agents/api-client (X-ORIGIN-*, X-LOG-INFO) |
| Remarketing system | app/utils/remarketing-id.ts + .client.ts + .server.ts |
| Remarketing component | app/components/tracking/RemarketingCapture.tsx |
| Analytics dispatcher | app/utils/metrics/index.ts |
| GTM integration | app/utils/metrics/gtm.ts |
| Cookie consent | app/utils/consent.ts + app/components/consent/CookieConsentBanner.tsx |
| GCM v2 integration | app/utils/metrics/consent.ts |
| Affiliate Clever | app/utils/affiliate-clever.server.ts + app/routes/clever.ts |
Tests
| Suite | Cobre |
|---|---|
app/utils/__tests__/tracking.test.ts | Parser URL, todos aliases, sanitização, merge last-touch |
app/utils/__tests__/tracking.server.test.ts | Captura server-side, Set-Cookie serialization, strip URL |
app/utils/__tests__/remarketing-id.test.ts | UUID v4, parse/serialize, audience tags, validation |
app/utils/__tests__/remarketing-id.server.test.ts | Server-side capture do remarketing ID |
app/modules/register/__tests__/flow.tracking.test.ts | FormData → parse → buildRegisterPayload (e2e signup) |
packages/payments/src/__tests__/transform.test.ts | buildDepositPayload confirma src NÃO sai |
packages/api-client/src/__tests__/client.test.ts | X-LOG-INFO formato + X-ORIGIN-ACCESS enum |
Convenções
- Política de atribuição:
last-touchem todas as superfícies. Mudança requer alinhamento com BI. - Cookie naming:
cookie_*ou nomes brand-aware (rmk<brand>). Nunca contémcactus/bluetec. - Sanitização:
sanitizeTrackingValueaplicado a tudo que entra nocookie_tracking. Exceção:lastclick(Clever) é opaco. - HttpOnly:
cookie_tracking/cookie_referrer/rmkvera/rmkvera_aud/lastclicksão non-HttpOnly (client lê).jwt_tokené HttpOnly. - Server-first: captura sempre server-side primeiro (root loader), client é re-aplicação em SPA navs.
- Brand override: file-replacement (não deep-merge). Adicionar campo novo em config requer propagar em todos overrides ou documentar como opt-in explícito.