Runtime del Navegador

Esta guía explica cómo funciona el SDK de Noxtica dentro del navegador de tus visitantes — qué ocurre durante una evaluación, cómo la caché mantiene las cosas ágiles y cómo resolver los problemas más habituales.

Cómo Funciona

Cuando añades el SDK de Noxtica a tu página, este realiza silenciosamente cuatro tareas:

1. Autenticación: se identifica con tu Site Key usando credenciales que gestiona por ti
2. Recopilación: lee las señales habituales que un navegador ya expone
3. Envío: las envía a Noxtica para su puntuación
4. Caché: almacena el resultado localmente para no repetir el trabajo en cada visita

Todo esto ocurre en segundo plano y nunca bloquea tu página.

Flujo de Recopilación

Automático (Recomendado)

Al usar data-auto-check-once, el SDK emplea la recopilación 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>

¿Usas una política de seguridad de contenido? Tendrás que permitir que Noxtica cargue y ejecute su entorno de ejecución resistente a manipulaciones, el KHAN VM. Si no puede hacerlo, Noxtica sigue funcionando con una forma más ligera de recopilación y menor protección contra manipulaciones. Consulta Primeros Pasos → Content Security Policy para el fragmento exacto.

Primera visita: se realiza una evaluación completa y el resultado se almacena en caché.

Visitas posteriores (dentro del período de caché): se devuelve el resultado en caché y se registra una visita ligera. No se repite el trabajo pesado.

Al expirar el período de caché: se realiza una evaluación nueva.

Control Manual

Para control programático, usa el 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');
}

Comportamiento de la Caché

El SDK almacena cada resultado en el navegador para no reevaluar al mismo visitante en cada carga de página.

Clave de Caché

nox_fp_{your_site_key}

Qué Se Almacena

• Device ID
• Marca de tiempo del último envío
• Marca de tiempo de la última visita
• Puntuación y nivel de riesgo anteriores

TTL (Tiempo de Vida)

El TTL por defecto de la caché es de 7 días. Se puede configurar:

// Sobrescribir en el momento de la recopilación
const result = await client.checkOnce({
	checkIntervalDays: 14, // 14 días en lugar de 7
});

// O en segundos
const result = await client.checkOnce({
	ttlSeconds: 86400, // 1 día
});

Forzar Actualización

Para saltarse la caché y recopilar un fingerprint nuevo:

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

Coordinación Entre Pestañas

Cuando un visitante abre varias pestañas de tu sitio a la vez, el SDK se asegura de que solo se evalúe una vez:

• Solo una pestaña realiza el trabajo real
• Las demás pestañas esperan y comparten ese resultado

Esto ocurre automáticamente — no requiere ninguna configuración.

Eventos

El SDK emite eventos que puedes escuchar:

noxtica:collected

Se dispara tras una recopilación exitosa o al devolver un resultado en caché:

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

Se dispara específicamente cuando se devuelve un resultado en caché:

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

noxtica:error

Se dispara cuando la recopilación falla:

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

Variables Globales

Tras la recopilación, los resultados están disponibles de forma global:

// Una vez completada la recopilación
console.log(window.noxticaResult);

// Instancia del cliente (cuando se usa auto-init)
console.log(window.noxticaClient);

// Último error (si lo hubiera)
console.log(window.noxticaLastError);

Gestión de Errores

Errores Habituales

Gestionar Errores Manualmente

try {
	const result = await client.collectAndSubmit();
} catch (error) {
	if (error.message.includes('origin_mismatch')) {
		// Problema de configuración de la Site Key
	} else if (error.message.includes('rate')) {
		// Esperar y reintentar más tarde
	}
}

Modos de Recopilación

El SDK admite tres modos de recopilación:

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

Modo Protegido (KHAN VM)

Lo más difícil de combatir bots es que cualquier cosa que corre en un navegador es, en principio, visible y editable. Un atacante decidido puede leer el código de la página, averiguar qué se está midiendo y devolver silenciosamente respuestas falsas.

KHAN VM eleva el costo de eso. En lugar de dejar la recopilación expuesta como código legible en la página, Noxtica ejecuta la parte sensible dentro de un entorno de ejecución sellado y aislado. La lógica que decide qué medir no está a la vista para que un atacante la estudie y reescriba, y el resultado que produce se sella antes de salir del navegador — por lo que es mucho más difícil manipularlo o reproducirlo.

Lo que KHAN VM aporta:

• Resultados resistentes a manipulaciones — la evaluación se sella dentro del entorno aislado antes de enviarse, de modo que otros scripts de la página no pueden alterarla ni reproducirla silenciosamente.
• Más difícil de hacer ingeniería inversa — la lógica de recopilación permanece oculta dentro del entorno de ejecución en lugar de ser legible desde las herramientas de desarrollo del navegador.
• Protección contra reproducción — cada resultado es de un solo uso y se verifica, de modo que una respuesta capturada no puede reutilizarse para simular un visitante legítimo.

Límites honestos — lo que no hace:

• Es una función de resistencia a manipulaciones, no cifrado de extremo a extremo.
• Si tu propia página está comprometida (por ejemplo, por una vulnerabilidad de scripting entre sitios), un atacante en esa página puede ver las mismas señales brutas del navegador que ve Noxtica. KHAN VM protege el procesamiento y el resultado, no la página que lo rodea.

KHAN VM se activa desde el servidor y no requiere ningún cambio en tu integración. Si no puede arrancar — por ejemplo, porque una política de seguridad de contenido lo bloquea — Noxtica recurre a una forma más ligera de recopilación para que la detección siga funcionando, aunque con menor protección contra manipulaciones.

Compatibilidad con Navegadores

El SDK es compatible con navegadores modernos:

Los navegadores más antiguos pueden tener menor precisión de señal, pero seguirán funcionando.

Modo de Depuración

Activa el registro de depuración para resolver problemas:

// Antes de que se cargue el SDK
globalThis.NOXTICA_DEBUG = true;

// O por cliente
const client = NoxticaCollector.createClient({
	siteKey: 'pk_prod_...',
	debug: true,
});

// O mediante un atributo de script
<script src="..." data-debug></script>;

El modo de depuración registra:

• El progreso de la recopilación
• El ciclo de vida del token
• Aciertos y fallos de caché
• Cualquier error encontrado

Nota: el modo de depuración es silencioso por defecto en producción. No aparece ninguna salida en la consola a menos que se habilite explícitamente.

Consideraciones de Almacenamiento

Almacenamiento del Navegador

El SDK usa el almacenamiento local del navegador para guardar resultados en caché. Si no está disponible (por ejemplo, en navegación privada o con el almacenamiento deshabilitado):

• La detección sigue funcionando
• Cada carga de página realiza una evaluación nueva
• La coordinación entre pestañas puede verse reducida

Sin Cookies

El SDK no usa cookies. Todo lo que necesita se guarda en el almacenamiento local del navegador.

Impacto en el Rendimiento

Primera Visita

La recopilación se ejecuta de forma asíncrona y no bloquea el renderizado de la página.

Visitas Posteriores (Acierto de Caché)

Resolución de Problemas

Fingerprint No Recopilado

1. Comprueba la consola del navegador en busca de errores
2. Verifica que la Site Key coincide exactamente con tu dominio (incluido https://)
3. Asegúrate de que el dominio está habilitado en el Backoffice
4. Activa el modo de depuración para ver registros detallados

”WebAssembly blocked by Content Security Policy”

Si ves esta advertencia en la consola del navegador, la política de seguridad de contenido de tu página está bloqueando el entorno de ejecución resistente a manipulaciones (el KHAN VM). La detección sigue funcionando en un modo más ligero, pero obtendrás la máxima protección si lo permites.

Usa el fragmento siguiente para que Noxtica pueda cargar y ejecutarse:

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

Consulta Primeros Pasos → Content Security Policy para la referencia completa.

Diferentes Device IDs en el Mismo Dispositivo

Esto puede ocurrir cuando:

• Se borran los datos almacenados del navegador
• Cambia el perfil del navegador
• El visitante usa el modo privado o de incógnito
• El navegador pasa por una actualización importante

Esto es lo esperado — el reconocimiento se adapta a medida que un dispositivo cambia con el tiempo.

La Recopilación Tarda Demasiado

1. Comprueba la pestaña de red en busca de respuestas lentas de la API
2. Considera usar mode: 'minimal' para una recopilación más rápida
3. Asegúrate de que el SDK se carga con el atributo async

Los Eventos No Se Disparan

1. Asegúrate de empezar a escuchar antes de que el SDK se ejecute
2. Comprueba que los atributos de auto-init son correctos
3. Verifica que no hay errores de JavaScript que bloqueen la ejecución

Buenas Prácticas

1. Usa data-auto-check-once en lugar de data-auto-collect para minimizar las recopilaciones redundantes

2. Carga el SDK de forma asíncrona con el atributo async para no bloquear la carga de la página

3. Escucha los eventos en lugar de hacer polling sobre window.noxticaResult

4. No sobrescribas el TTL innecesariamente — el intervalo por defecto de 7 días está optimizado para la mayoría de los casos de uso

5. Gestiona los errores correctamente — un fallo de recopilación no debería romper tu página

Próximos Pasos

• Primeros Pasos — guía de configuración inicial
• Integración con el Backend — consultas de dispositivos en el servidor