> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```javascript Após login bem-sucedido theme={null}
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
}
```

<Warning>
  **LGPD:** o operador é responsável por obter consentimento explícito antes
  de enviar traits que contenham PII. Veja [traits seguros vs perigosos](#traits-recomendados)
  abaixo.
</Warning>

## O que `identify()` faz internamente

<Steps>
  <Step title="Vincula identidades">
    Persiste a relação `distinct_id ↔ user_ext_id` em `localStorage`.
    Todos os eventos seguintes carregam `user_ext_id` populado no payload.
  </Step>

  <Step title="Emite evento user.identified">
    Adiciona ao buffer um evento `user.identified` com source `'manual'` e
    os traits informados.
  </Step>

  <Step title="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.
  </Step>
</Steps>

## 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)

```javascript theme={null}
// 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

```javascript theme={null}
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()`:

```javascript theme={null}
// 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

```javascript Cole no DevTools depois do identify theme={null}
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](/sdk/web-analytics/events) — eventos automáticos + custom
* [Privacidade & LGPD](/sdk/web-analytics/privacy) — banner consent, masking PII