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:

(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:

<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:

console.log({
  optedIn:  iGamingSDK.has_opted_in_capturing(),
  storage:  localStorage.getItem('ig_consent')
});

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

Solução:

iGamingSDK.opt_in_capturing();
iGamingSDK.capture('debug.fix', {});
iGamingSDK.flush();

Ou reset completo (apaga todo estado):

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.

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.

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:

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.

// 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:

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:

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:

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

Ou peça consent explícito:

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:

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:

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: [e-mail]
• 💬 Discord: discord.gg/atlas
• 🐛 GitHub Issues: twinfo-io/atlas-webanalytics