Primeiros Passos

Este guia vai ajudar você a adicionar a Noxtica à sua aplicação web em apenas alguns minutos.

Pré-requisitos

• Uma conta Noxtica (solicite acesso pelo contato)
• A sua Site Key (fornecida após a configuração da conta)

Integração rápida

Quando sua conta estiver configurada e você tiver a Site Key em mãos, adicione o nosso collector ao seu HTML — essa é toda a instalação.

Coleta automática (recomendado)

A maneira mais simples de começar é deixar a Noxtica se gerenciar, usando o modo executar uma vez:

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

Isso fará o seguinte:

• Avaliar um visitante na primeira visita
• Reutilizar aquele resultado em visitas repetidas dentro da janela de cache (padrão: 7 dias)
• Registrar visitas de retorno sem refazer a avaliação completa
• Coordenar entre abas abertas para que um visitante seja avaliado apenas uma vez

Os resultados ficam disponíveis via:

// Escute os resultados
document.addEventListener('noxtica:collected', function (e) {
	console.log('Fingerprint collected:', e.detail);
	console.log('Risk score:', e.detail.score);
	console.log('Risk level:', e.detail.risk_level);
});

// Ou acesse diretamente após a coleta
console.log(window.noxticaResult);

Coleta manual

Para mais controle, use a API JavaScript:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Crie um cliente com a sua Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Colete e envie em uma única chamada
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

Coleta inteligente com checkOnce()

Para o menor impacto possível, use checkOnce() — ele respeita o intervalo de coleta que você configura no servidor, para que os visitantes não sejam reavaliados com mais frequência do que precisam:

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

// Only collects if outside the check interval window (default: 7 days)
// Otherwise records a visit and returns cached result
const result = await client.checkOnce();

if (result.fromCache) {
	console.log('Using cached result, next collection in:', result.nextSubmitIn, 'days');
} else {
	console.log('Fresh collection submitted');
}
console.log('Risk level:', result.risk_level);

Desempenho e impacto no site

O collector foi projetado para ter impacto mínimo no carregamento da página e na latência percebida pelo usuário:

Como mantemos o impacto baixo:

• Atributo async no script — o collector carrega em segundo plano e nunca atrasa a visibilidade ou interatividade da sua página.
• Modo executar uma vez (data-auto-check-once) — após a primeira avaliação, visitas repetidas dentro da janela de cache enviam apenas um pequeno ping de visita (~150 bytes).
• Coordenação entre abas — múltiplas abas abertas colapsam em uma única avaliação.
• Cache após a primeira carga — a KHAN VM resistente a adulteração é armazenada em cache pelo navegador, carregando instantaneamente em visitas posteriores.
• Processamento em segundo plano quando disponível, para que o trabalho fique fora da thread principal e sua página permaneça responsiva.

Se você notar lentidão após adicionar o SDK, capture um perfil com await client.collectAndSubmit({ telemetry: true }) — o result.telemetry retornado inclui um detalhamento de timing.

Sandbox vs. Produção

Você terá duas Site Keys: uma para desenvolvimento e staging, outra para produção. Cada uma roda com suas próprias políticas e mantém seus dados totalmente separados.

Sempre troque a Site Key por ambiente. Nunca use uma chave pk_sand_* em tráfego de produção — os dados de sandbox não aparecerão nos seus painéis de produção e o scoring de risco será muito permissivo. Por outro lado, usar uma chave pk_prod_* em desenvolvimento consome sua cota de limite de taxa de produção.

Um padrão comum:

<script>
	// Pick the key by hostname; fall back to sandbox in dev.
	const KEY = location.hostname === 'www.example.com' ? 'pk_prod_REPLACE_ME' : 'pk_sand_REPLACE_ME';
	const s = document.createElement('script');
	s.src = 'https://collect.noxtica.com/collector/noxtica.js';
	s.async = true;
	s.dataset.siteKey = KEY;
	s.dataset.autoInit = '';
	s.dataset.autoCheckOnce = '';
	document.head.appendChild(s);
</script>

Compatibilidade com gerenciadores de tags

O collector funciona dentro do Google Tag Manager, Adobe Launch, Tealium e Segment, MAS com ressalvas:

Recomendado (preferido): adicione o script diretamente ao seu HTML, imediatamente antes de </body> ou em <head> com async. Iniciar o mais cedo possível dá ao collector a melhor vantagem inicial, para que esteja pronto quando um visitante interagir.

Gerenciadores de tags — funciona, com ressalvas:

• ✅ A maioria dos gerenciadores de tags modernos (GTM Custom HTML, Adobe Launch Custom Code, Segment Custom Source) carrega o collector com sucesso.
• ⚠️ Portões de consentimento que bloqueiam scripts até o visitante aceitar atrasarão a primeira avaliação — geralmente nada roda até o banner de consentimento ser descartado. Esse é o comportamento correto; apenas saiba que pode distorcer suas métricas de “tempo para decisão”.
• ⚠️ Alguns gerenciadores de tags mais antigos descartam atributos data-* personalizados. Se data-site-key não chegar à tag script, o auto-init não iniciará. Configure manualmente no código:

  NoxticaCollector.createClient({ siteKey: 'pk_prod_...' }).checkOnce();

• ❌ Alguns containers de tags fortemente isolados (raros) impedem o runtime resistente a adulteração de iniciar. O SDK continua funcionando com uma forma mais leve de coleta e registra um aviso no console.

Se precisar integrar via gerenciador de tags, configure-o para disparar a tag da Noxtica em All Pages — Window Loaded (ou equivalente) em vez de DOM Ready — isso garante que o estado de consentimento esteja finalizado antes de qualquer coisa rodar.

Content Security Policy

Se o seu site usa uma content-security-policy, você precisará permitir que a Noxtica carregue, rode seu runtime resistente a adulteração (a KHAN VM) e se comunique com nossa API. O exemplo abaixo cobre os três casos:

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

Se a política não incluir o token 'wasm-unsafe-eval', o navegador bloqueia o runtime resistente a adulteração e você verá um aviso relacionado no console. A Noxtica continua funcionando — recorre a uma forma mais leve de coleta — mas com proteção contra adulteração mais fraca. Adicionar o token acima restaura a experiência completa.

Site Keys

Sua Site Key (pk_...) é um identificador público que autentica requisições do seu domínio. Cada domínio que você adiciona no Backoffice recebe uma Site Key única.

Observações importantes:

• Site Keys são públicas e podem ser incorporadas com segurança ao seu HTML
• Cada Site Key está vinculada a uma origin específica (ex: https://example.com)
• A API rejeitará requisições onde a origin não corresponda ao domínio registrado na Site Key

Opções de configuração

const client = NoxticaCollector.createClient({
	// Your Site Key (required)
	siteKey: 'pk_prod_your_site_key_here',

	// API endpoint (defaults to production)
	apiUrl: 'https://collect.noxtica.com',

	// Collection mode: 'max' (default), 'standard', or 'minimal'
	// Omit to use max mode (recommended)
	// mode: 'standard', // Uncomment to opt out of max-only signals
});

Modos de coleta

Formato da resposta

Após coletar e enviar, você recebe:

{
	"success": true,
	"fingerprintId": "abc123...",
	"score": 15,
	"risk_level": "minimal",
	"confidence": 0.5,
	"flags": [],
	"details": {
		"summary": "Detected 0 risk indicator(s)."
	}
}

Níveis de risco

Autenticação

O SDK autentica cada visita com credenciais de curta duração e rotação automática vinculadas à sua Site Key. Ele as solicita, renova e as anexa a cada envio por você.

Você não precisa gerenciar nada disso — o SDK cuida tudo automaticamente.

Processo de onboarding

1. Solicite acesso: fale conosco para solicitar uma demo ou começar
2. Configuração da conta: criamos a sua conta tenant na plataforma
3. Adicione domínios: faça login no Backoffice, vá em Domains e adicione as suas origins
4. Copie a Site Key: cada domínio recebe uma Site Key única
5. Integre: adicione o script com a sua Site Key às suas páginas
6. Monitore: visualize fingerprints e analytics no painel do Backoffice

Gerenciando múltiplos domínios

A Noxtica suporta múltiplos domínios por conta:

• Produção: https://www.yoursite.com
• Staging: https://staging.yoursite.com
• Mobile: https://m.yoursite.com

Cada domínio tem a sua própria Site Key. Você pode:

• Ativar/desativar domínios sem regenerar chaves
• Rotacionar Site Keys caso sejam comprometidas
• Ver analytics filtradas por domínio

Versão do SDK

Versão atual do SDK: 3.3.0 (Schema: 2026-05-24)

O que há de novo na 3.3.0

• Sinais comportamentais leves (sempre ativos) — dicas simples de timing como a duração da sessão e a rapidez com que um visitante interage pela primeira vez. Sem dados biométricos e sem necessidade de consentimento do usuário final.
• Biometria comportamental (opt-in) — quando ativado em Backoffice → Settings → Behavioral Biometrics, a Noxtica também analisa o ritmo de movimento do mouse, timing de cliques e rolagem. Isso conta como dados biométricos sob regulamentações de privacidade rígidas, portanto é necessário consentimento explícito do usuário final. Veja Biometria Comportamental abaixo.
• Verificação de consistência do Apple Pay — confirma que um dispositivo que afirma ser um iPhone se comporta como um, detectando um truque comum de falsificação.
• Correspondência de fingerprint de rede — reconhece os padrões de conexão característicos de ferramentas de automação comuns, para que o tráfego de scripts e bots se destaque mesmo quando o navegador pareça convincente.
• Reputação de IP — sinaliza visitantes chegando de redes com má reputação, com a opção de conectar seu próprio feed de inteligência de ameaças preferido.

Biometria Comportamental (Opcional, Opt-In)

A Noxtica também pode analisar o ritmo de como alguém move o mouse, clica e rola. É um recurso opt-in, desativado por padrão.

Por que opt-in? Esse tipo de dados comportamentais conta como dado pessoal sensível sob regulamentações de privacidade rígidas, portanto capturá-lo requer consentimento explícito do seu usuário final. Tornamos opt-in para que você mantenha o controle de quando e como é usado.

Para ativar:

1. Faça login em Backoffice → Settings → Behavioral Biometrics
2. Revise o aviso de conformidade com sua equipe jurídica ou de privacidade
3. Atualize sua política de privacidade e banner de consentimento para divulgar essa captura
4. Ative o recurso

Uma vez ativado, a Noxtica automaticamente incorpora esses sinais comportamentais em avaliações futuras, e seu painel mostra o score comportamental resultante por domínio.

Próximos passos

• Experimente a demo ao vivo para ver o fingerprinting em ação
• Leia o guia de Integração com o Backend para consultas no servidor
• Acesse o painel para explorar os dados coletados