Affiliate

A plataforma suporta dois sistemas paralelos de affiliate — o nativo (cookie cookie_tracking com affiliation_code) e o Clever Advertising (cookie lastclick). Ambos coexistem em produção dependendo da brand e do contrato.

Sistema 1 — Affiliate code nativo

Capturado da URL via uma família de aliases, persistido no cookie_tracking e enviado no payload de signup.

Aliases aceitos

Os 6 nomes mais comuns no mercado:

Alias na URL	Persistido como
affiliation_code	affiliation_code
aff	affiliation_code
ref	affiliation_code
referenceCode	affiliation_code
btag	affiliation_code
b_tag	affiliation_code
btagid	affiliation_code

Qualquer um desses na URL preenche o mesmo campo affiliation_code.

Sub-ID (subid)

Algumas redes (RedTrack, Tonic) passam um sub-ID adicional separado:

Alias na URL	Persistido como
subid	subid
sub_id	subid

subid viaja no payload de signup junto com affiliation_code.

Auto-open de modal em ?ref=

Quando o front detecta uma URL com qualquer alias de affiliation_code, dispara um auto-open de modal 300 ms após o mount (delay herdado do legado Vue):

Estado do user	Modal aberto
Deslogado	RegisterModal (afiliado tá tentando cadastrar)
Logado	DepositModal (afiliado tá promovendo um depósito)

A decisão espera authHydrated === true pra não disparar antes do auth resolver. Detalhes de implementação: ver app/components/tracking/TrackingCapture.tsx.

Comportamento: dispara só na primeira observação do ?ref= na sessão. Navegações SPA subsequentes que ainda carregam o ref na URL não re-abrem o modal.

Onde vai no payload

Signup (POST /api/auth/register):

{
  "email": "...",
  "affiliation_code": "AFIL1",
  "subid": "rt_subid_42"
}

Deposit: affiliation_code e subid NÃO vão no payload (paridade legado). BFF resolve a atribuição do depósito pelo registro do user, não pelo cookie.

Sistema 2 — Clever Advertising (lastclick cookie)

Brands que contratam Clever Advertising usam um sistema paralelo de tracking de affiliate. A integração é minimalista mas opera num modelo cross-site (iframe / popup / pixel chain) que tem regras próprias.

Cookie lastclick

Atributo	Valor
Nome	lastclick
TTL	30 dias
Path	/
SameSite	None (obrigatório — Clever entrega tráfego cross-site)
Secure	sim (consequência de SameSite=None)
HttpOnly	não (Clever scripts client-side leem)

Por que SameSite=None?

Clever entrega tráfego pra /clever?utm_source=... via contexto cross-site (iframe / popup / pixel chain). Browsers modernos (Chrome 80+, Firefox, Safari) rejeitam Set-Cookie em contexto cross-site a menos que seja SameSite=None; Secure.

Histórico: o legado Vue usava SameSite=Lax e funcionava porque escrevia o cookie via document.cookie (regras mais permissivas). A migração pra HTTP Set-Cookie header expôs a regra estrita e silenciosamente quebrou ~99% do tráfego Clever — corrigido em maio/2026.

Endpoint /clever

Clever Advertising redireciona seus afiliados pra https://<brand>/clever?utm_source=<id>&.... A rota:

1. Recebe o request
2. Lê searchParams.utm_source || Object.values(searchParams)[0] (fallback se não tem utm_source mas tem outro param)
3. Escreve Set-Cookie: lastclick=<valor> na response
4. Renderiza página em branco (é landing de pixel — bots de afiliação seguem redirects/pixels, mas não há conteúdo visível)

Valor do cookie é opaco

Diferente de cookie_tracking que sanitiza valores, o lastclick recebe o ID Clever raw, sem sanitização. Clever pode usar formatos contendo strings que o blocklist de analytics mangia (document, appendChild, {macro}, __CLICKID__, etc). Sanitizar mutilaria IDs e quebraria atribuição.

Quando uma key tem múltiplos valores (?utm_source=a&utm_source=b), o último vence (paridade legado: Array.isArray(...) ? .last : .).

Como ativar pra brand nova

Feature flag affiliateClever: true na brand. Sem isso, a rota /clever retorna 404. Hoje habilitado em: vera, 7k, cassino (validar lista atualizada em Por Brand).

Convivência com sistema nativo

Se uma URL tem ambos ?ref=AFIL1&utm_source=clever_id, ambos sistemas funcionam paralelos:

• affiliation_code: "AFIL1" no cookie_tracking (vai no payload de signup)
• lastclick: "clever_id" no cookie próprio (Clever lê client-side)

Não há conflito. Brands podem ter Clever + outras redes ao mesmo tempo.

Diferenças entre os dois sistemas

Aspecto	Sistema nativo	Clever Advertising
Cookie	cookie_tracking (JSON)	lastclick (string raw)
TTL	7 dias (configurável)	30 dias (fixo)
Aliases URL	6 (ref, btag, b_tag, btagid, aff, referenceCode)	qualquer query param (Clever escolhe o utm_source por convenção)
Sanitização	Sim (HTML, scripts, etc)	Não (valor opaco)
Cross-site	Funciona local	Requer SameSite=None; Secure
Vai no payload BFF?	Sim, signup	Não — Clever tem pixel próprio que lê o cookie
Auto-open modal?	Sim (?ref=)	Não (Clever só persiste o cookie, não dispara UI)

Como testar

Sistema nativo

1. http://localhost:5173/?ref=AFIL_TEST&subid=sub_42
2. DevTools → Cookies → cookie_tracking deve ter affiliation_code: "AFIL_TEST", subid: "sub_42"
3. Aguarda 300 ms → modal de Cadastro deve abrir automaticamente (se deslogado)
4. Submete signup → Network → affiliation_code e subid no body

Clever Advertising

1. Acesse http://localhost:5173/clever?utm_source=clever_test_123 (apenas em brand com affiliateClever: true)
2. DevTools → Cookies → lastclick deve estar clever_test_123 com SameSite=None
3. Verifique que cookie sobrevive 30 dias

Anti-patterns

1. Sanitizar o lastclick. Quebra IDs Clever. Sempre raw.
2. Mudar SameSite do lastclick. Quebra ~99% do tráfego Clever cross-site.
3. Setar ?ref= em link interno (ex: header → "Convide um amigo"). Auto-abre modal pra users já logados, atrapalha UX.
4. Desativar affiliateClever numa brand que tem contrato ativo. Quebra atribuição silenciosamente — afiliados continuam mandando tráfego e ninguém recebe crédito.
5. Tentar unificar os dois sistemas. São contratos comerciais separados; um não substitui o outro.