Browser Runtime

Este guia explica como o SDK da Noxtica funciona dentro dos navegadores dos seus visitantes — o que acontece durante uma avaliação, como o cache mantém tudo rápido e como resolver problemas comuns.

Como funciona

Quando você adiciona o SDK da Noxtica à sua página, ele faz quatro coisas de forma discreta:

1. Autentica: conecta com a sua Site Key usando credenciais que ele gerencia por você
2. Coleta: lê os sinais cotidianos que um navegador já expõe
3. Envia: os encaminha à Noxtica para pontuação
4. Armazena em cache: guarda o resultado localmente para não repetir o trabalho em cada visita

Tudo isso roda em segundo plano e nunca bloqueia sua página.

Fluxo de coleta

Automático (recomendado)

Ao usar data-auto-check-once, o SDK utiliza coleta inteligente:

<script
	src="https://collect.noxtica.com/collector/noxtica.js"
	data-site-key="pk_prod_your_site_key"
	data-auto-init
	data-auto-check-once
	async
></script>

Usando uma content-security-policy? Você precisará permitir que a Noxtica carregue e rode seu runtime resistente a adulteração, a KHAN VM. Se não puder, a Noxtica continua funcionando com uma forma mais leve de coleta e proteção contra adulteração mais fraca. Veja Primeiros Passos → Content Security Policy para o snippet exato.

Primeira visita: uma avaliação completa é executada e o resultado é armazenado em cache.

Visitas seguintes (dentro da janela de cache): o resultado em cache é devolvido e uma visita leve é registrada. Nenhum trabalho pesado é executado.

Após a janela de cache expirar: uma nova avaliação é executada.

Controle manual

Para controle programático, use o método checkOnce():

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_your_site_key',
});

const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached fingerprint');
	console.log('Next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh fingerprint collected');
}

Comportamento do cache

O SDK armazena cada resultado em cache no navegador para não reavaliar o mesmo visitante em cada visualização de página.

Chave do cache

nox_fp_{your_site_key}

O que é armazenado em cache

• ID do dispositivo
• Timestamp do último envio
• Timestamp da última visualização
• Score e nível de risco anteriores

TTL (Time-To-Live)

O TTL padrão do cache é de 7 dias. Ele pode ser configurado:

// Override at collection time
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 days instead of 7
});

// Or in seconds
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 day
});

Forçar atualização

Para ignorar o cache e coletar um novo fingerprint:

const result = await client.checkOnce({
	forceRefresh: true,
});

Coordenação entre abas

Quando um visitante abre várias abas do seu site ao mesmo tempo, o SDK garante que ele seja avaliado apenas uma vez:

• Apenas uma aba faz o trabalho real
• As outras abas aguardam e compartilham aquele resultado

Isso acontece automaticamente — nenhuma configuração necessária.

Eventos

O SDK dispara eventos que você pode escutar:

noxtica:collected

Disparado após coleta bem-sucedida ou ao devolver resultado em cache:

document.addEventListener('noxtica:collected', (e) => {
	console.log('Fingerprint ID:', e.detail.fingerprintId);
	console.log('Risk Level:', e.detail.risk_level);
	console.log('Score:', e.detail.score);
	console.log('From Cache:', e.detail.fromCache);
});

noxtica:cache-hit

Disparado especificamente quando um resultado em cache é devolvido:

document.addEventListener('noxtica:cache-hit', (e) => {
	console.log('Cache hit, days since submission:', e.detail.daysSinceSubmit);
});

noxtica:error

Disparado quando a coleta falha:

document.addEventListener('noxtica:error', (e) => {
	console.log('Error source:', e.detail.source);
	console.log('Error message:', e.detail.message);
});

Variáveis globais

Após a coleta, os resultados ficam disponíveis globalmente:

// After collection completes
console.log(window.noxticaResult);

// Client instance (when using auto-init)
console.log(window.noxticaClient);

// Last error (if any)
console.log(window.noxticaLastError);

Tratamento de erros

Erros comuns

Tratando erros manualmente

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Site key configuration issue
	} else if (error.message.includes('rate')) {
		// Back off and retry later
	}
}

Modos de coleta

O SDK suporta três modos de coleta:

const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	mode: 'max', // or 'minimal', 'standard'
});

Modo protegido (KHAN VM)

A parte mais difícil de combater bots é que qualquer coisa rodando num navegador é, em princípio, visível e editável. Um atacante determinado pode ler o código da página, descobrir o que está sendo medido e silenciosamente devolver respostas falsas.

A KHAN VM eleva o custo disso. Em vez de deixar a coleta exposta como código legível na página, a Noxtica roda a parte sensível dentro de um ambiente isolado e selado. A lógica que decide o que medir não está à vista para um atacante estudar e reescrever, e o resultado que ela produz é selado antes de sair do navegador — tornando muito mais difícil adulterá-lo ou reproduzi-lo.

O que a KHAN VM ajuda:

• Resultados resistentes a adulteração — a avaliação é selada dentro do sandbox antes de ser enviada, para que outros scripts na página não possam alterá-la ou reproduzi-la silenciosamente.
• Mais difícil de fazer engenharia reversa — a lógica de coleta fica oculta dentro do runtime em vez de ser legível nas ferramentas de desenvolvedor do navegador.
• Proteção contra replay — cada resultado é de uso único e verificado, então uma resposta capturada não pode ser simplesmente reutilizada para falsificar um visitante limpo.

Limites honestos — o que ela não faz:

• É um recurso de resistência a adulteração, não criptografia de ponta a ponta.
• Se sua própria página for comprometida (por exemplo, por uma falha de cross-site scripting), um atacante nessa página pode ver os mesmos sinais brutos do navegador que a Noxtica vê. A KHAN VM protege o processamento e o resultado, não a página ao redor.

A KHAN VM é ativada pelo servidor e não exige nenhuma alteração na sua integração. Se não puder iniciar — por exemplo, porque uma content-security-policy a bloqueia — a Noxtica recorre a uma forma mais leve de coleta para que a detecção continue funcionando, apenas com proteção contra adulteração mais fraca.

Suporte a navegadores

O SDK suporta navegadores modernos:

Navegadores mais antigos podem ter precisão de sinal reduzida, mas ainda funcionarão.

Modo de depuração

Habilite o registro de depuração para resolver problemas:

// Before SDK loads
globalThis.NOXTICA_DEBUG = true;

// Or per-client
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// Or via script attribute
<script src="..." data-debug></script>;

O modo de depuração registra:

• Progresso da coleta
• Ciclo de vida do token
• Acertos e falhas de cache
• Quaisquer erros encontrados

Nota: o modo de depuração é silencioso por padrão em produção. Nenhuma saída de console aparece a menos que seja explicitamente ativado.

Considerações sobre armazenamento

Armazenamento do navegador

O SDK usa o armazenamento local do navegador para armazenar resultados em cache. Se não estiver disponível (por exemplo, em navegação privada ou com armazenamento desativado):

• A detecção continua funcionando
• Cada carregamento de página executa uma nova avaliação
• A coordenação entre abas pode ser reduzida

Sem cookies

O SDK não usa cookies. Tudo que ele precisa é mantido no armazenamento local do navegador.

Impacto de desempenho

Primeira visita

A coleta é executada de forma assíncrona e não bloqueia a renderização da página.

Visitas seguintes (cache hit)

Solução de problemas

Fingerprint não coletado

1. Verifique o console do navegador em busca de erros
2. Confirme que a Site Key corresponde exatamente ao seu domínio (incluindo https://)
3. Garanta que o domínio está ativado no Backoffice
4. Ative o modo de depuração para ver logs detalhados

”WebAssembly blocked by Content Security Policy”

Se você vir este aviso no console do navegador, a content-security-policy da sua página está bloqueando o runtime resistente a adulteração (a KHAN VM). A detecção continua funcionando em modo mais leve, mas você terá a proteção mais forte ao permiti-lo.

Use o snippet abaixo para permitir que a Noxtica carregue e rode:

Content-Security-Policy: script-src 'self' 'wasm-unsafe-eval' https://collect.noxtica.com; connect-src 'self' https://collect.noxtica.com

Veja Primeiros Passos → Content Security Policy para a referência completa.

IDs de dispositivo diferentes no mesmo dispositivo

Isso pode acontecer quando:

• Os dados armazenados no navegador são limpos
• O perfil do navegador muda
• O visitante usa modo privado/anônimo
• O navegador passa por uma atualização significativa

Esse é o comportamento esperado — o reconhecimento se adapta conforme um dispositivo muda ao longo do tempo.

Coleta demorando demais

1. Verifique a aba de rede em busca de respostas lentas da API
2. Considere usar mode: 'minimal' para coleta mais rápida
3. Garanta que o SDK seja carregado com o atributo async

Eventos não disparando

1. Certifique-se de estar escutando antes de o SDK rodar
2. Confirme que os atributos de auto-init estão corretos
3. Verifique se não há erros de JavaScript bloqueando a execução

Boas práticas

1. Use data-auto-check-once em vez de data-auto-collect para minimizar coletas redundantes

2. Carregue o SDK de forma assíncrona com o atributo async para não bloquear o carregamento da página

3. Escute eventos em vez de fazer polling em window.noxticaResult

4. Não sobrescreva o TTL desnecessariamente — o intervalo padrão de 7 dias é otimizado para a maioria dos casos

5. Trate erros com elegância — uma falha de coleta não deve quebrar sua página

Próximos passos

• Primeiros Passos — guia de configuração inicial
• Integração com o Backend — consultas de dispositivo no servidor