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

# Troubleshooting

> Problemas comuns na integração do Atlas Web Analytics SDK e como resolver.

## Diagnóstico rápido

Cole este snippet no DevTools Console da página onde o SDK roda:

```javascript theme={null}
(async () => {
  console.group('🔍 Atlas Diagnóstico');
  console.log('1. Página:', location.href, '(protocolo:', location.protocol, ')');
  console.log('2. SDK loaded:', typeof iGamingSDK?.init === 'function');
  console.log('3. Distinct ID:', iGamingSDK?.get_distinct_id?.());
  console.log('4. Consent:', {
    optedIn:  iGamingSDK?.has_opted_in_capturing?.(),
    optedOut: iGamingSDK?.has_opted_out_capturing?.(),
    storage:  localStorage.getItem('ig_consent'),
  });

  const _f = window.fetch;
  let captured = null;
  window.fetch = async function(url, opts) {
    if (String(url).includes('sdk-events')) {
      captured = { url: String(url), method: opts?.method, bodyLen: opts?.body?.length };
      console.log('5. → tentando POST', captured);
      try {
        const res = await _f.apply(this, arguments);
        console.log('6. ✓ resposta', res.status, res.statusText);
        return res;
      } catch (e) {
        console.error('6. ✗ falhou:', e.message);
        throw e;
      }
    }
    return _f.apply(this, arguments);
  };

  iGamingSDK.opt_in_capturing();
  iGamingSDK.capture('debug.smoke', { ts: Date.now() });
  iGamingSDK.flush();
  await new Promise(r => setTimeout(r, 2000));

  if (!captured) console.warn('7. ⚠ Nenhum POST tentado — buffer vazio ou bloqueio');
  const resources = performance.getEntriesByType('resource').filter(r => r.name.includes('sdk-events'));
  console.log('8. Requests via Performance API:', resources.length);
  console.groupEnd();
})();
```

## Problemas comuns

### `window.iGamingSDK` é `undefined`

**Causa provável:** o bundle não carregou (404, bloqueio CSP, async race).

**Solução:**

1. Network → procure `sdk.min.js` → status deve ser 200
2. Confirme polling do snippet de init:

```html theme={null}
<script>
  (function init() {
    if (!window.iGamingSDK || !window.iGamingSDK.init) {
      return setTimeout(init, 50);
    }
    window.iGamingSDK.init({ /* ... */ });
  })();
</script>
```

3. Se CSP bloqueia, libere domínios:

```
script-src   'self' https://cdn.twinfo.io;
connect-src  'self' https://ingest.atlas.io;
```

### POSTs falham com CORS error

**Causa provável:** preflight OPTIONS bloqueado ou origin não permitida.

**Solução:** o endpoint Atlas responde `Access-Control-Allow-Origin: *` em
`/v1/sdk-events`. Confirme no Network → request `OPTIONS` retorna 204 com
headers corretos.

Se seu app usa CSP, libere:

```
connect-src 'self' https://ingest.atlas.io;
```

### POST retorna `429 Too Many Requests`

**Causa provável:** rate limit per `org+brand+ip` estourou (default 100 req/s
por pod).

**Solução:**

* Em dev: aguarde 1 minuto e tente novamente
* Em produção: contate suporte para aumentar o limite via env
  `HTTP_SDK_RATE_LIMIT_PER_SECOND`

### Eventos somem após `capture()` — `flush()` não envia nada

**Causa provável:** SDK em estado opt-out persistido em `localStorage`.

**Como confirmar:**

```javascript theme={null}
console.log({
  optedIn:  iGamingSDK.has_opted_in_capturing(),
  storage:  localStorage.getItem('ig_consent')
});
```

Se `optedIn: false` e/ou `storage: '0'` → SDK silenciado.

**Solução:**

```javascript theme={null}
iGamingSDK.opt_in_capturing();
iGamingSDK.capture('debug.fix', {});
iGamingSDK.flush();
```

Ou reset completo (apaga todo estado):

```javascript theme={null}
Object.keys(localStorage).filter(k => k.startsWith('ig_')).forEach(k => localStorage.removeItem(k));
location.reload();
```

### Eventos chegam mas `user_ext_id` está vazio

**Causa provável:** `identify()` nunca foi chamado.

**Solução:** chame `identify(userId, traits)` no callback de login do seu app.
Veja [Identificar usuário](/sdk/web-analytics/identify).

```javascript theme={null}
function onLoginSuccess(user) {
  window.iGamingSDK.identify(user.id, {
    account_type: user.tier,
    kyc_status:   user.kycStatus
  });
}
```

### Eventos não aparecem no Kafka mesmo após `flush()`

**Causa 1:** Mixed content — page HTTPS chamando endpoint HTTP.

```javascript theme={null}
console.log({
  pageProtocol: location.protocol,    // 'https:'
  endpointProtocol: 'http://localhost:8084'   // ← BLOQUEADO
});
```

**Solução:** use endpoint HTTPS (production Atlas) ou teste em page HTTP local.

**Causa 2:** Extensão bloqueando (uBlock, Privacy Badger, Brave Shields).

Verifique:

```javascript theme={null}
performance.getEntriesByType('resource')
  .filter(r => r.name.includes('sdk-events'))
  .forEach(r => console.log(r.name, r.responseStatus, 'dur:', r.duration));
```

Se o array está vazio mas você chamou `flush()` → request bloqueado pela
extensão. Teste em janela anônima.

**Causa 3:** Endpoint errado.

```javascript theme={null}
// O SDK só expõe getters de identidade, não da config.
// Verifique via Network: a URL do POST deve bater com o endpoint do init.
```

### Heatmap não dispara

**Causa provável:** sessão não foi amostrada (default 10%).

**Solução em dev:**

```javascript theme={null}
iGamingSDK.init({
  // ...
  heatmap: { enabled: true, sampleRate: 1.0 }   // 100% das sessões em dev
});
```

### Buffer não envia antes de 30s

Comportamento esperado. O SDK acumula eventos e flusha em:

* **50 eventos** no buffer
* **30 segundos** desde último flush
* `visibilitychange:hidden` / `beforeunload`
* `iGamingSDK.flush()` manual

**Solução para envio imediato:**

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

### Vários `session.ended` em pouco tempo

**Causa provável:** usuário alternando entre tabs frequentemente
(`visibilitychange:hidden` dispara em cada switch).

**Solução:** comportamento esperado e correto. O dashboard agrega corretamente —
não trata cada `session.ended` como sessão nova, apenas o último wins.

### Erro "respect\_dnt is true and navigator.doNotTrack is '1'"

Não é um erro — é o SDK respeitando o sinal DNT do browser do usuário e
silenciando captura. Configurações relacionadas:

```javascript theme={null}
iGamingSDK.init({
  respect_dnt: false   // ignora DNT (não recomendado em produção)
});
```

Ou peça consent explícito:

```javascript theme={null}
iGamingSDK.init({ respect_dnt: true });
// Depois do banner:
iGamingSDK.opt_in_capturing();   // sobrescreve DNT
```

### Cookies não persistem entre subdomínios

**Causa provável:** auto-detect do `cookie_domain` falhou (TLD composto).

**Solução:** force o domínio raiz:

```javascript theme={null}
iGamingSDK.init({
  // ...
  cookie_domain: '.brand.com.br'    // ← com ponto inicial
});
```

### Bundle muito grande para meu CSP / quote bundle

O bundle core é **\~8 KB gzipped**. Se ainda precisa reduzir:

1. Desligue `capture_performance: false` se não usa Web Vitals (economiza \~2KB peer dep)
2. Use a build core sem polyfills (assume ES2020+)

## Coletar logs para suporte

Antes de abrir ticket de suporte, capture:

```javascript theme={null}
JSON.stringify({
  page:        location.href,
  protocol:    location.protocol,
  user_agent:  navigator.userAgent,
  sdk_version: iGamingSDK?.version,
  distinct_id: iGamingSDK?.get_distinct_id?.(),
  session_id:  iGamingSDK?.get_session_id?.(),
  consent: {
    optedIn:  iGamingSDK?.has_opted_in_capturing?.(),
    optedOut: iGamingSDK?.has_opted_out_capturing?.(),
    storage:  localStorage.getItem('ig_consent')
  },
  requests: performance.getEntriesByType('resource')
    .filter(r => r.name.includes('sdk-events'))
    .map(r => ({ url: r.name, status: r.responseStatus, dur: Math.round(r.duration) }))
}, null, 2);
```

Cole o output no ticket — acelera diagnóstico.

## Suporte

* 📧 Email: [suporte@atlas.io](mailto:suporte@atlas.io)
* 💬 Discord: [discord.gg/atlas](https://discord.gg/atlas)
* 🐛 GitHub Issues: [twinfo-io/atlas-webanalytics](https://github.com/twinfo-io)