Identificar usuário

Vincule o distinct_id anônimo do SDK ao user_ext_id interno do operador via identify(). Sem isso, eventos ficam anônimos no Kafka.

O SDK gera um distinct_id anônimo (UUID persistido em localStorage + cookie) no primeiro pageview de cada visitante. Para cruzar comportamento web com dados transacionais (depósitos, apostas) no dashboard, você precisa vincular esse distinct_id ao user_ext_id interno do operador via identify().

Quando chamar

Situação	API	Onde chamar
Após login bem-sucedido	identify(userId, traits)	Callback de autenticação do app
Após cadastro	identify(newUserId, traits)	Callback de signup confirmado
Mudança de identidade	alias(newId, oldId)	Migrações, troca anônimo→identificado
Logout	reset()	Callback de logout

Exemplo básico

Após login bem-sucedido

function onLoginSuccess(user) {
  window.iGamingSDK.identify(user.id, {
    account_type: user.tier,         // 'vip' | 'standard' | 'new'
    kyc_status:   user.kycStatus,    // 'approved' | 'pending' | 'rejected'
    country:      user.country,      // 'BR'
    signup_at:    user.createdAt
  });
}

function onLogout() {
  window.iGamingSDK.reset();         // rotaciona distinct_id e limpa user_ext_id
}

LGPD: o operador é responsável por obter consentimento explícito antes de enviar traits que contenham PII. Veja traits seguros vs perigosos abaixo.

O que identify() faz internamente

1. Vincula identidades

   Persiste a relação distinct_id ↔ user_ext_id em localStorage. Todos os eventos seguintes carregam user_ext_id populado no payload.

2. Emite evento user.identified

   Adiciona ao buffer um evento user.identified com source 'manual' e os traits informados.

3. Persiste cross-session

   Próximas visitas do mesmo browser (mesmo dispositivo) já abrem com user_ext_id preenchido — não precisa chamar identify() de novo.

Traits recomendados

✅ Seguros (operador pode enviar livremente)

Trait	Tipo	Exemplo
account_type	enum	'vip', 'standard', 'new', 'inactive'
kyc_status	enum	'approved', 'pending', 'rejected'
country	ISO 3166-1 alpha-2	'BR', 'PT'
state / region	abreviação	'SP', 'RJ'
signup_at	ISO 8601	'2026-01-15T10:30:00Z'
lifetime_value_tier	enum	'bronze', 'silver', 'gold'
preferred_sport	enum	'football', 'basketball', 'tennis'
preferred_provider	string	'pragmatic', 'evolution'
language	ISO 639-1	'pt-BR', 'en-US'
marketing_opt_in	boolean	true/false
acquisition_source	string	'paid-google', 'organic', 'referral'

❌ Nunca enviar (PII alto risco)

Trait	Por quê
email (completo)	LGPD exige justificativa específica. Use hash SHA-256 se necessário.
phone (completo)	Idem email
document / cpf	Direito ao esquecimento — manter fora do tracking
card_number, cvv, card_exp	Compliance PCI-DSS
password, password_hash	Nunca em telemetria
address (endereço completo)	LGPD — use só country/state se necessário
birthdate (completa)	Use só ano (birth_year: 1990) se necessário
full_name	Use só inicial (first_name_initial: 'J') se necessário

⚠️ Use com cuidado

Trait	Recomendação
total_deposits_brl	OK se agregado, evite valor exato em risk-fraud
last_seen_ip	Já enriquecido pelo servidor — não envie do cliente
referrer_user_id	OK se for o ID interno e não PII

Alias — fundir duas identidades

Útil quando você tem dois IDs diferentes que representam o mesmo usuário:

• Anônimo (distinct_id SDK) que depois loga → fundir com user_ext_id
• Migração de sistema (ID antigo → ID novo)
• Multi-platform (web user + mobile user)

// Cenário: usuário anônimo visitou várias páginas, depois se cadastrou.
// Antes do cadastro: distinct_id = 'abc-uuid-anonymous'
// Após cadastro:    user.id = 'user_ext_99'

iGamingSDK.alias('user_ext_99', iGamingSDK.get_distinct_id());
iGamingSDK.flush();

// Agora a Atlas mescla o histórico anônimo com o usuário identificado.

Reset — logout

function onLogout() {
  window.iGamingSDK.reset();
  // O que acontece:
  // 1. Gera novo distinct_id UUID
  // 2. Limpa user_ext_id
  // 3. Limpa super-properties registradas via register()
  // 4. Mantém o estado de consent (opt-in/out persistido)
}

Sem reset() no logout, o próximo usuário que acessar do mesmo browser teria seus eventos atribuídos ao usuário anterior.

Super properties (avançado)

Atributos que você quer adicionar a todos os eventos sem precisar passar em cada capture():

// Define uma vez (persistente entre sessões)
iGamingSDK.register({
  ab_test_variant: 'B',
  promo_active: 'spring_2026'
});

// Apenas se ainda não existir (não sobrescreve)
iGamingSDK.register_once({
  acquisition_source: 'google-ads-q1'
});

// Remove
iGamingSDK.unregister('promo_active');

// Limpa todas (reset também faz isso)
iGamingSDK.reset();

Toda chamada capture() subsequente vai incluir ab_test_variant: 'B' e promo_active: 'spring_2026' no payload.

Validar

Cole no DevTools depois do identify

console.log({
  distinct_id: iGamingSDK.get_distinct_id(),
  session_id:  iGamingSDK.get_session_id()
});

// Force envio para ver imediatamente no Kafka
iGamingSDK.flush();

No dashboard Atlas, filtre por user_ext_id na aba Sessions — deve listar todas as sessões do usuário, anônimas e identificadas, vinculadas via alias.

Próximos passos

• Catálogo de eventos — eventos automáticos + custom
• Privacidade & LGPD — banner consent, masking PII