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

# Catálogo de eventos

> Os 14 eventos automáticos do SDK + convenções para eventos custom de negócio iGaming.

O SDK captura 14 tipos de eventos automaticamente. Adicione `capture('nome', props)`
nos pontos-chave do funil de negócio.

## Visão rápida

| #   | Evento                | Origem | Trigger                                          |
| --- | --------------------- | ------ | ------------------------------------------------ |
| 1   | `session.started`     | AUTO   | Init do SDK                                      |
| 2   | `session.heartbeat`   | AUTO   | A cada 30s com aba ativa                         |
| 3   | `session.ended`       | AUTO   | `visibilitychange:hidden` / `beforeunload`       |
| 4   | `page.viewed`         | AUTO   | Pageview inicial + SPA navigation                |
| 5   | `page.left`           | AUTO   | Antes da navegação                               |
| 6   | `ig.autocapture`      | AUTO   | Click / change / submit em elementos interativos |
| 7   | `rage.click`          | AUTO   | ≥3 cliques em 2s no mesmo target                 |
| 8   | `dead.click`          | AUTO   | Click sem mutação DOM em 3s                      |
| 9   | `scroll.depth`        | AUTO   | Marcos 25/50/75/100%                             |
| 10  | `heatmap.click`       | AUTO   | Click (10% sessões amostradas)                   |
| 11  | `web.vitals`          | AUTO   | LCP/INP/CLS/FCP/TTFB                             |
| 12  | `error.occurred`      | AUTO   | `window.onerror` / promise rejection             |
| 13  | `user.identified`     | API    | `identify(userId, traits)`                       |
| 14  | `feature_flag.called` | API    | `getFeatureFlag(key)`                            |
| 15+ | `<custom>`            | CUSTOM | `capture('nome', props)`                         |

## Eventos de sessão

### `session.started`

Início da sessão. Dispara 1× na primeira interação. Carrega contexto inicial.

```json Payload exemplo theme={null}
{
  "event": "session.started",
  "properties": {
    "is_new_visitor":  true,
    "first_seen_at":   "2026-05-18T19:00:00Z",
    "entry_url":       "https://brand.com/casino/slots",
    "referrer":        "https://google.com/search?q=casino",
    "browser_name":    "Chrome",
    "browser_version": "146",
    "os_name":         "macOS",
    "device_type":     "desktop",
    "language":        "pt-BR",
    "timezone":        "America/Sao_Paulo",
    "viewport_width":  1920,
    "viewport_height": 1080,
    "utm_source":      "google-ads",
    "utm_campaign":    "spring_promo_2026"
  }
}
```

### `session.heartbeat`

Sinaliza usuário online. Disparado a cada 30s com aba ativa, pausa quando aba está em background.

```json theme={null}
{
  "event": "session.heartbeat",
  "properties": {
    "url":                   "https://brand.com/casino/slots",
    "active_time_ms":        90000,
    "current_route_time_ms": 60000
  }
}
```

### `session.ended`

Fim da sessão por inatividade ou unload da página.

```json theme={null}
{
  "event": "session.ended",
  "properties": {
    "duration_ms":  720000,
    "pages_viewed": 5,
    "is_bounce":    false,
    "exit_url":     "https://brand.com/conta/depositar",
    "reason":       "visibilitychange"
  }
}
```

## Eventos de pageview

### `page.viewed`

Pageview inicial + SPA navigation (intercepta `pushState`/`replaceState`/hashchange).

```json theme={null}
{
  "event": "page.viewed",
  "properties": {
    "url":          "https://brand.com/casino/slots/sweet-bonanza",
    "referrer":     "https://brand.com/casino/slots",
    "trigger":      "navigation",
    "title":        "Sweet Bonanza · Brand",
    "game_slug":    "sweet-bonanza",
    "game_ext_id":  "sweet-bonanza",
    "game_type":    "casino"
  }
}
```

### `page.left`

Antes da navegação para outra rota. Carrega tempo na página.

```json theme={null}
{
  "event": "page.left",
  "properties": {
    "previous_url":            "https://brand.com/casino/slots/sweet-bonanza",
    "time_on_page_ms":         45000,
    "total_time_on_route_ms":  45000
  }
}
```

## Eventos de interação

### `ig.autocapture`

Click / change / submit em `<a>`, `<button>`, `<input>`, `<form>`, `<select>`,
`<textarea>`, `<label>` e elementos com `role="button"`. Carrega o **selector
chain completo** do elemento.

```json theme={null}
{
  "event": "ig.autocapture",
  "properties": {
    "$event_type": "click",
    "$elements": [
      {
        "tag_name":        "button",
        "$el_text":        "Depositar R$ 50",
        "attr__id":        "deposit-cta",
        "attr__class":     "btn btn-primary",
        "attr__data_testid": "cta-deposit",
        "nth_child":       1
      },
      { "tag_name": "div", "attr__class": "header" },
      { "tag_name": "body" }
    ],
    "$elements_chain": "button#deposit-cta.btn.btn-primary:text=\"Depositar R$ 50\";div.header;body",
    "$el_text":        "Depositar R$ 50",
    "url":             "/casino",
    "viewport_width":  1920,
    "viewport_height": 1080
  }
}
```

### `rage.click`

≥3 cliques em 2s no mesmo target (raio 30px). Indica frustração de UX.
Excluir botões `+`/`-` de aposta com classe `.ig-no-rageclick`.

```json theme={null}
{
  "event": "rage.click",
  "properties": {
    "url":             "/conta/depositar",
    "click_count":     5,
    "window_ms":       1200,
    "x":               320,
    "y":               480,
    "target_tag":      "button",
    "target_selector": "#btn-deposit-confirm"
  }
}
```

### `dead.click`

Click em elemento que não causou mutação DOM em 3s. Indica botão quebrado /
CTA sem handler / link com `href="#"` esquecido.

```json theme={null}
{
  "event": "dead.click",
  "properties": {
    "url":             "/casino",
    "x":               250,
    "y":               380,
    "target_tag":      "button",
    "target_selector": "#btn-broken"
  }
}
```

### `scroll.depth`

Marcos 25 / 50 / 75 / 100% da página. 1× por marco por rota por sessão (não
duplica em SPA navigation entre rotas).

```json theme={null}
{
  "event": "scroll.depth",
  "properties": {
    "url":              "/promocoes",
    "milestone":        75,
    "scroll_y":         1536,
    "viewport_height":  1080,
    "document_height":  2400,
    "reachable_height": 1320
  }
}
```

### `heatmap.click`

Coordenadas XY de cada clique. **Disparado em 10% das sessões** (sampling
determinístico por hash do `session_id`). Configurável via `heatmap.sampleRate`.

```json theme={null}
{
  "event": "heatmap.click",
  "properties": {
    "url":                  "/casino/slots",
    "x":                    420,
    "y":                    200,
    "scroll_y":             0,
    "scroll_depth_percent": 25,
    "viewport_width":       1920,
    "viewport_height":      1080,
    "target_tag":           "a",
    "target_selector":      ".game-card"
  }
}
```

## Eventos de performance e erro

### `web.vitals`

Core Web Vitals reportados pela lib `web-vitals` (Google). Um evento por
métrica por pageview.

```json theme={null}
{
  "event": "web.vitals",
  "properties": {
    "url":             "/casino/slots",
    "metric":          "LCP",
    "value":           2350,
    "rating":          "good",
    "metric_id":       "v3-1234567890",
    "viewport_width":  1920,
    "viewport_height": 1080
  }
}
```

| Métrica | "good"  | "needs improvement" | "poor"  |
| ------- | ------- | ------------------- | ------- |
| LCP     | ≤ 2.5s  | 2.5–4.0s            | > 4.0s  |
| INP     | ≤ 200ms | 200–500ms           | > 500ms |
| CLS     | ≤ 0.1   | 0.1–0.25            | > 0.25  |
| FCP     | ≤ 1.8s  | 1.8–3.0s            | > 3.0s  |
| TTFB    | ≤ 0.8s  | 0.8–1.8s            | > 1.8s  |

### `error.occurred`

Captura `window.onerror` e `unhandledrejection`. Stack trace sanitizada
(redact de query strings em URLs — pode conter tokens).

```json theme={null}
{
  "event": "error.occurred",
  "properties": {
    "message":    "Cannot read properties of undefined (reading 'amount')",
    "filename":   "https://brand.com/static/js/checkout.abc.js",
    "lineno":     142,
    "colno":      18,
    "stack":      "TypeError: ...\n  at confirmDeposit (checkout.abc.js:142:18)",
    "session_id": "sess_abc_123",
    "url":        "/conta/depositar",
    "type":       "runtime"
  }
}
```

Tipos: `'runtime'` (Error event), `'unhandled_promise'` (PromiseRejectionEvent).

## Eventos de identidade

### `user.identified`

Disparado quando você chama `iGamingSDK.identify(distinctId, traits)`.

```json theme={null}
{
  "event": "user.identified",
  "user_ext_id": "user_42",
  "properties": {
    "distinct_id": "user_42",
    "source":      "manual",
    "traits": {
      "account_type": "vip",
      "kyc_status":   "approved",
      "country":      "BR"
    }
  }
}
```

`source` pode ser `'manual'` (identify direto), `'alias'` ou `'datalayer'`
(fallback automático via DataLayerSpy quando operador esquece de chamar identify).

### `feature_flag.called`

Disparado em cada `iGamingSDK.getFeatureFlag(key)`.

```json theme={null}
{
  "event": "feature_flag.called",
  "properties": {
    "flag_key":   "experiment_new_deposit_flow",
    "flag_value": "B"
  }
}
```

## Eventos custom

Use `capture('event.name', props)` para qualquer evento de negócio. O nome é
livre. Convenção: `namespace.action` em minúsculas separadas por ponto.

### Eventos recomendados para iGaming

| Funil         | Evento               | Props principais                         |
| ------------- | -------------------- | ---------------------------------------- |
| **Aquisição** | `signup.intent`      | `source`, `plan_intent`                  |
|               | `signup.completed`   | `method` (email/social), `country`       |
| **KYC**       | `kyc.started`        | `step_total`                             |
|               | `kyc.approved`       | `level` (basic/full)                     |
| **Depósito**  | `deposit.intent`     | `amount`, `method`, `source`             |
|               | `deposit.completed`  | `amount`, `method`, `is_first_deposit`   |
|               | `deposit.failed`     | `reason_code`, `amount`                  |
| **Apostas**   | `bet.placed`         | `amount`, `market`, `odds`, `game_id`    |
|               | `bet.settled`        | `outcome` (won/lost/void), `payout`      |
| **Saque**     | `withdraw.requested` | `amount`, `method`                       |
|               | `withdraw.confirmed` | `amount`, `method`, `transaction_id`     |
| **Jogos**     | `game.opened`        | `game`, `provider`, `bet_min`, `bet_max` |
|               | `game.closed`        | `game`, `duration_ms`                    |
| **Promo**     | `promo.viewed`       | `promo_id`, `placement`                  |
|               | `promo.accepted`     | `promo_id`, `bonus_amount`               |

### Exemplo — funil de depósito

```javascript theme={null}
// 1. Click no CTA "Depositar"
iGamingSDK.capture('deposit.intent', {
  amount: 100,
  method: 'pix',
  source: 'casino-landing'
});

// 2. Confirmação pelo gateway
iGamingSDK.capture('deposit.completed', {
  amount:           100,
  method:           'pix',
  transaction_id:   'tx_abc123',
  is_first_deposit: true
});

// 3. Antes do redirect crítico, força envio
iGamingSDK.flush();
window.location.href = '/conta/extrato';
```

## Forçar envio imediato

O SDK enfileira eventos e flusha em **batches de 50 OU a cada 30 segundos OU
no unload**. Para envios imediatos (ex: antes de redirect crítico):

```javascript theme={null}
iGamingSDK.capture('deposit.completed', { amount: 100 });
iGamingSDK.flush();   // POST imediato
```

## Validar no Kafka

Cada evento POSTado vira uma mensagem no tópico `atlas.sdk-events`. Veja
no [Kafka UI Atlas](https://kafka-ui.atlas.io) ou via consumer:

```bash theme={null}
docker exec atlas-kafka kafka-console-consumer \
  --bootstrap-server localhost:9092 \
  --topic atlas.sdk-events \
  --from-beginning
```

## Próximos passos

* [Configuração](/sdk/web-analytics/configuration) — controlar quais eventos auto-capturar
* [Privacidade & LGPD](/sdk/web-analytics/privacy) — denylist, sanitize, classes CSS
* [Identificar usuário](/sdk/web-analytics/identify) — vincular comportamento ao user