Contrato Front ↔ Backend — Eventos comportamentais

Esta página é a spec do que o backend precisa implementar para fechar o sistema de remarketing/analytics. O front faz só o que dá pra observar do lado dele; tudo que depende de webhook, cron, ou agregação de banco vem do BFF.

Princípio

Front mapeia o que o front observa. Cliques, navegação, modais abertos/fechados, submits de form, polling de confirmação que ele mesmo dispara, valores que recebeu da API.

Backend mapeia o que só o backend sabe. Webhooks de PSP, eventos do iframe de jogo, agregações temporais (último login, depósito médio mensal), sinais de provedor externo (KYC aprovado, e-mail clicado, push aceito).

Front e back trabalham em paralelo. Esta doc é o contrato entre os dois.

Fonte do front

O front mantém em repos/front-web-base/app/analytics/destinations.ts uma matriz declarativa indicando, pra cada evento, se ele deve forward external_id (do cookie rmkvera/rmk7k/etc) pro BFF. Quando bff_capi: { ... } está non-null, o front anexa external_id no payload do BFF correspondente (signup, deposit). Quando o BFF estiver pronto, basta a brand setar featuresConfig.remarketingId.sendToBff: true e a forward acontece automaticamente.

Eventos com bff_capi non-null hoje:

• sign_up (signup → Meta CAPI Lead)
• first_deposit (FTD → Meta CAPI Purchase, Google Enhanced Purchase, TikTok Events Purchase)

Eventos que o backend tem que disparar (organizados por origem)

1. Webhooks de PSP (pagamentos)

deposit_paid_webhook (FTD ou rebill)

Atributo	Valor
Trigger	Webhook de confirmação do PSP (Pagseguro, Stripe, Mercado Pago, Astropay, Worldline, etc)
Latência alvo	< 30s do clique do user no PSP até dispatch CAPI
Plataformas	Meta CAPI (Purchase), Google Enhanced (conversion), TikTok Events API (Purchase), AppsFlyer S2S (dep/rebill)
Payload	{ external_id, transaction_id, value, currency, is_first_deposit, hashed_email, hashed_phone, ... }
Notas	Front também dispara Purchase client-side via Pixel quando o polling do /api/payments/check retorna OK. Backend usa event_id = transaction_id pra deduplicar com pixel client-side.

withdraw_completed

Atributo	Valor
Trigger	Webhook do PSP confirmando saque pago
Plataformas	Internal BI / dashboards (não vai pra ad platform — saque não é conversão de ads)
Notas	Front já dispara withdraw (event name saque) no submit. Confirmação é só backend.

2. Webhooks de provedor de jogo

wagered_session (apostas reais)

Atributo	Valor
Trigger	Webhook do provedor (Pragmatic, Evolution, etc) por aposta paga
Plataformas	Audience push (Meta Custom Audience, Google Ads Customer Match)
Notas	Front nunca vê quando user aposta — o iframe é black-box. Back agrega em window (ex: ≥ 1 round dentro de 24h pós-FTD).

provider_affinity_<provider>

Atributo	Valor
Trigger	Agregação: user jogou ≥ X vezes do mesmo provider em janela Y
Plataformas	Pixel granular pra dynamic remarketing ("ama Pragmatic")
Notas	Cardinalidade ~30 providers/brand. Job diário no BI.

tournament_joined

Atributo	Valor
Trigger	Backend de gamification (Smartico ou interno) confirma entrada em torneio
Plataformas	CRM (audience "engajado em torneios")

3. Webhooks de KYC

kyc_pending

Atributo	Valor
Trigger	User registrou mas não enviou documentos
Plataformas	CRM (campanha de finalização KYC)
Notas	Cron diário OU snapshot na transição de sign-up state.

kyc_completed

Atributo	Valor
Trigger	Webhook do provedor KYC (Idwall, Unico, etc) confirma aprovação
Plataformas	Internal BI + audiência "hot lead" pra ad platforms (depósito iminente)

4. Cron jobs / agregação periódica

last_login_<7d>, last_login_<30d>, last_login_<90d>

Atributo	Valor
Trigger	Cron diário lendo users.last_login_at
Plataformas	Audience push com bucket de recência

dormant_with_balance

Atributo	Valor
Trigger	Cron diário: saldo > 0 && sem login há 30d
Plataformas	Audience LTV alto pra campanha "seu saldo te espera"
SLA	Refresh diário

lapsed_depositor

Atributo	Valor
Trigger	Cron: depositou nos últimos 6m && não nos últimos 30d
Plataformas	Win-back (Meta, Google, e-mail)

night_player / morning_player

Atributo	Valor
Trigger	Agregação de timestamps de aposta — janela horária dominante
Plataformas	Day-parting de ads

mobile_only / pwa_user

Atributo	Valor
Trigger	User-agent + cookie de App Mode + agregação no banco
Plataformas	App-install vs web-install campaigns

high_value

Atributo	Valor
Trigger	Depósito médio acima de threshold (configurável por brand)
Plataformas	High-value lookalike seed (Meta, Google)

bonus_dependent

Atributo	Valor
Trigger	User só ativo em sessões com bônus
Plataformas	Audiência específica de oferta (mantém bônus pra reter)

vip_tier_<n>

Atributo	Valor
Trigger	Backend de gamification (nível atual)
Plataformas	Concierge / VIP-only ads

ftd_within_24h

Atributo	Valor
Trigger	Cron / event-driven: FTD aconteceu < 24h após cadastro
Plataformas	High-velocity user → Meta lookalike de ouro

multi_deposit (versão server-side)

Atributo	Valor
Trigger	User com 2+ depósitos confirmados
Plataformas	Bucket de retenção
Notas	Front também marca via multi_deposit audience tag no <rmkBrand>_aud. Back tem ground truth (transações). Reconciliar em BI.

wagered_session, withdrew_first, cashback_pending

Mesmo modelo: cron lê tabela de transactions/cashbacks/etc e popula audiência.

5. CRM / engagement (sources externos)

email_clicked_recent

Atributo	Valor
Trigger	Webhook do ESP (SendGrid, Mailchimp, etc) — clique em e-mail < 7d
Plataformas	Multi-channel orchestration

push_optin

Atributo	Valor
Trigger	Backend recebe subscription do Service Worker (Web Push)
Plataformas	Audience push-eligible

support_contacted

Atributo	Valor
Trigger	Webhook do helpdesk (Zendesk, Intercom, etc) — user abriu ticket
Plataformas	Audiência delicada — talvez suprimir ads de aquisição

6. Atribuição (origem do user)

Front já captura UTMs e clicked-ids no cookie cookie_tracking e envia no body de signup/deposit. Backend persiste users.acquisition_source, users.affiliate_code, etc no momento do registro. As flags abaixo são derivadas dessa persistência:

acquisition_channel

Atributo	Valor
Trigger	Snapshot de utm_source no momento do registro
Plataformas	Suprimir ads do canal que já trouxe (não pagar de novo)

affiliate_user

Atributo	Valor
Trigger	User tinha affiliation_code no signup
Plataformas	Campanhas exclusivas / supressão de aquisição paga

paid_acquisition

Atributo	Valor
Trigger	Veio com gclid/fbclid/etc no signup
Plataformas	Diferencia de orgânico no remarketing

Server-side conversions roadmap (Meta CAPI / Google Enhanced / TikTok)

Pré-requisitos no BFF

1. Aceitar external_id no body de:
   • POST /bff/register-simplified (signup)
   • POST /wallet/add-credit (deposit)
2. Hashed PII (SHA-256, lowercase, trimmed):
   • email, phone, first_name, last_name, dob
3. Persistir external_id em users.remarketing_id pra usar no webhook depois (FTD via PSP webhook precisa do mesmo external_id que o front passou no signup).

Meta Conversions API (CAPI)

POST https://graph.facebook.com/v18.0/<PIXEL_ID>/events

• Eventos: Lead (signup), Purchase (FTD + rebill)
• Auth: access_token (vault no BFF, por brand)
• event_id: dedupe com pixel client-side (mesmo external_id + transaction_id)
• action_source: website (web) ou app (TWA)
• user_data: { external_id, em (hashed_email), ph (hashed_phone), fn (hashed_first), ln (hashed_last), client_ip_address, client_user_agent }

Google Enhanced Conversions

• API: Google Ads API (gRPC) — conversionUploadService.uploadClickConversions
• Eventos: conversion com gclid ou gbraid/wbraid (clicked-ids capturados pelo front)
• user_identifiers: hashed_email + hashed_phone

TikTok Events API

POST https://business-api.tiktok.com/open_api/v1.3/event/track/

• Eventos: CompleteRegistration, Purchase
• event_id: dedupe com pixel client-side
• user: { external_id, email (hashed), phone (hashed), ttp (cookie do pixel), ttclid (do front) }

Ativação por brand

Quando o BFF tiver os 3 endpoints implementados:

// overrides/<brand>/app/config/features/remarketing.ts
export const remarketingFeaturesConfig: RemarketingFeatureFlags = {
  enabled: true,
  cookieName: "rmk7k",
  cookieDomain: ".7k.bet.br",
  pushToDataLayer: true,
  exposeOnWindow: true,
  sendToBff: true, // ← liga o forward
};

Front passa a anexar external_id em todos os payloads marcados na matriz com bff_capi !== null.

Como o front sinaliza intenção

A matriz DESTINATIONS em app/analytics/destinations.ts declara quais eventos do front deveriam ser forwarded server-side:

sign_up: {
  // ...
  bff_capi: { name: "sign_up" }, // ← intent declarada
},
first_deposit: {
  // ...
  bff_capi: { name: "first_deposit" }, // ← intent declarada
},
viewed_casino: {
  // ...
  bff_capi: null, // ← audience client-only, não forward server-side
},

Backend pode introspectar o registry (via export pra JSON, futuro) ou consumir esta tabela diretamente.

Endpoints a discutir com back

• POST /webhook/payment/<provider> — recepção de webhook PSP (existe ou novo?)
• POST /webhook/game/<provider> — recepção de webhook de aposta
• POST /webhook/kyc/<provider> — recepção KYC
• GET /audience/export?since=<ts>&audience=<key> — pull de audiência pro time de marketing usar manualmente em Google Ads Customer Match / Meta Custom Audience
• POST /audience/push?platform=meta&audience=<key> — push automatizado pra plataforma de ad

Os endpoints não existem ainda. Esta doc é a proposta que serve como ponto de partida pra conversa back ↔ front ↔ marketing.

Resumo executivo pro time de back

• Front entrega hoje: identidade external_id em cookie first-party, audience tags client-side de cliques/navegação/modais, captura de UTMs/clicked-ids, eventos GTM/Pixel client-side.
• Front precisa do back pra fechar: Meta CAPI, Google Enhanced, TikTok Events API, dormant detection, KYC events, provider affinity, audience push.
• Lista priorizada (sugestão):
  1. CAPI Meta + Google Enhanced (maior ROI — duplica conversões reportadas, melhora bidding)
  2. KYC events (libera campanha "termine seu cadastro" pré-FTD)
  3. dormant_with_balance + lapsed_depositor (win-back)
  4. provider_affinity (dynamic remarketing por gênero de jogo)
  5. CRM events (push, e-mail, support)

Histórico

• 2026-05 — Doc inicial. Criada como saída do refactor do registry de eventos no front (ver Catálogo).