Primeros Pasos

Esta guía te ayudará a añadir Noxtica a tu aplicación web en solo unos minutos.

Requisitos Previos

• Una cuenta de Noxtica (solicita el acceso a través de contacto)
• Tu Site Key (se proporciona tras la configuración de la cuenta)

Integración Rápida

Una vez que tu cuenta esté configurada y tengas tu Site Key, añade nuestro colector a tu HTML — eso es toda la instalación.

Recopilación Automática (Recomendada)

La forma más sencilla de empezar es dejar que Noxtica se gestione solo, usando el modo de ejecución única:

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

Esto hará lo siguiente:

• Evaluar a un visitante en su primera visita
• Reutilizar ese resultado para visitas repetidas dentro del período de caché (por defecto: 7 días)
• Registrar discretamente las visitas de retorno sin repetir la evaluación completa
• Coordinarse entre las pestañas abiertas para que un visitante solo sea evaluado una vez

Los resultados están disponibles a través de:

// Escuchar los 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);
});

// O acceder directamente tras la recopilación
console.log(window.noxticaResult);

Recopilación Manual

Para mayor control, usa la API de JavaScript:

<script src="https://collect.noxtica.com/collector/noxtica.js"></script>
<script>
	// Crear un cliente con tu Site Key
	const client = NoxticaCollector.createClient({
		siteKey: 'pk_prod_your_site_key_here',
	});

	// Recopilar y enviar en una sola llamada
	client.collectAndSubmit().then((result) => {
		console.log('Risk score:', result.score);
		console.log('Risk level:', result.risk_level);
		console.log('Flags:', result.flags);
	});
</script>

Recopilación Inteligente con checkOnce()

Para una huella mínima, usa checkOnce() — respeta el intervalo de recopilación que configures en el servidor, de modo que los visitantes no sean reevaluados más a menudo de lo necesario:

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

// Solo recopila si está fuera de la ventana del intervalo de verificación (por defecto: 7 días)
// De lo contrario, registra una visita y devuelve el resultado en caché
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);

Rendimiento e Impacto en el Sitio

El colector está diseñado para tener un impacto mínimo en la carga de página y la latencia visible para el usuario:

Cómo lo mantenemos ligero:

• Atributo async del script — el colector se carga en segundo plano y nunca retrasa que la página sea visible o interactiva.
• Modo de ejecución única (data-auto-check-once) — tras la primera evaluación, las visitas repetidas dentro del período de caché solo envían un pequeño ping de visita (~150 bytes).
• Coordinación entre pestañas — múltiples pestañas abiertas colapsan en una sola evaluación.
• Caché tras la primera carga — el KHAN VM resistente a manipulaciones es almacenado en caché por el navegador, por lo que se carga al instante en visitas posteriores.
• Procesamiento en segundo plano cuando está soportado, para que el trabajo se mantenga fuera del hilo principal y la página siga respondiendo.

Si notas una ralentización tras añadir el SDK, captura un perfil con await client.collectAndSubmit({ telemetry: true }) — el result.telemetry devuelto incluye un desglose de tiempos.

Sandbox frente a Producción

Tendrás dos Site Keys: una para desarrollo y staging, otra para producción. Cada una funciona bajo sus propias políticas y mantiene sus datos completamente separados.

Cambia siempre la Site Key según el entorno. Nunca uses una clave pk_sand_* en tráfico de producción — los datos de sandbox no aparecerán en tus paneles de producción y la puntuación de riesgo será demasiado permisiva. De igual forma, usar una clave pk_prod_* en desarrollo consume el presupuesto del límite de solicitudes de producción.

Un patrón habitual:

<script>
	// Elegir la clave según el hostname; usar sandbox en desarrollo.
	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>

Compatibilidad con Gestores de Etiquetas

El colector funciona dentro de Google Tag Manager, Adobe Launch, Tealium y Segment, PERO con advertencias:

Recomendado (preferido): añade el script directamente a tu HTML, inmediatamente antes de </body> o en <head> con async. Empezar lo antes posible da al colector la mayor ventaja, de modo que esté listo cuando un visitante interactúe.

Gestores de etiquetas — funciona, con advertencias:

• ✅ La mayoría de los gestores de etiquetas modernos (GTM Custom HTML, Adobe Launch Custom Code, Segment Custom Source) cargan el colector correctamente.
• ⚠️ Las barreras de consentimiento que bloquean scripts hasta que un visitante acepta retrasarán la primera evaluación — normalmente nada se ejecuta hasta que se descarta el banner de consentimiento. Esto es el comportamiento correcto; solo ten en cuenta que puede sesgar tus métricas de “tiempo hasta decisión”.
• ⚠️ Algunos gestores de etiquetas más antiguos eliminan los atributos data-* personalizados. Si data-site-key no llega al tag del script, el auto-init no arrancará. En ese caso, configúralo manualmente en código:

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

• ❌ Unos pocos contenedores de etiquetas muy aislados (raros) impiden que el entorno de ejecución resistente a manipulaciones arranque. El SDK sigue funcionando con una forma más ligera de recopilación y registra una advertencia en la consola.

Si debes integrar a través de un gestor de etiquetas, configúralo para disparar el tag de Noxtica en All Pages — Window Loaded (o equivalente) en lugar de DOM Ready — esto asegura que el estado del consentimiento sea definitivo antes de que se ejecute nada.

Content Security Policy

Si tu sitio usa una política de seguridad de contenido, tendrás que permitir que Noxtica se cargue, ejecute su entorno de ejecución resistente a manipulaciones (el KHAN VM) y se comunique con nuestra API. El ejemplo siguiente cubre las tres cosas:

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

Si a la política le falta el token 'wasm-unsafe-eval', el navegador bloquea el entorno de ejecución resistente a manipulaciones y verás una advertencia relacionada en la consola. Noxtica sigue funcionando — recurre a una forma más ligera de recopilación — pero con menor protección contra manipulaciones. Añadir el token anterior restaura la experiencia completa.

Site Keys

Tu Site Key (pk_...) es un identificador público que autentica las solicitudes desde tu dominio. Cada dominio que añadas en el Backoffice obtiene una Site Key única.

Notas importantes:

• Las Site Keys son públicas y pueden incrustarse de forma segura en tu HTML
• Cada Site Key está ligada a un origen específico (por ejemplo, https://example.com)
• La API rechazará las solicitudes cuyo origen no coincide con el dominio registrado de la Site Key

Opciones de Configuración

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

	// Endpoint de la API (por defecto: producción)
	apiUrl: 'https://collect.noxtica.com',

	// Modo de recopilación: 'max' (por defecto), 'standard' o 'minimal'
	// Omítalo para usar el modo max (recomendado)
	// mode: 'standard', // Descomentar para renunciar a las señales solo de max
});

Modos de Recopilación

Formato de Respuesta

Tras recopilar y enviar, recibes:

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

Niveles de Riesgo

Autenticación

El SDK autentica cada visita con credenciales de corta duración y rotación automática vinculadas a tu Site Key. Las solicita, las renueva y las adjunta a cada envío por ti.

No necesitas gestionar nada de esto — el SDK lo hace automáticamente.

Proceso de Alta

1. Solicita acceso: contáctanos para pedir una demo o empezar
2. Configuración de la cuenta: creamos tu cuenta de tenant en la plataforma
3. Añade dominios: inicia sesión en el Backoffice, ve a Domains y añade tus orígenes
4. Copia tu Site Key: cada dominio obtiene una Site Key única
5. Integra: añade el script con tu Site Key a tus páginas
6. Supervisa: visualiza fingerprints y analítica en el panel del Backoffice

Gestión de Varios Dominios

Noxtica admite varios dominios por cuenta:

• Producción: https://www.yoursite.com
• Staging: https://staging.yoursite.com
• Móvil: https://m.yoursite.com

Cada dominio tiene su propia Site Key. Puedes:

• Habilitar o deshabilitar dominios sin regenerar claves
• Rotar las Site Keys si se ven comprometidas
• Ver analítica filtrada por dominio

Versión del SDK

Versión actual del SDK: 3.3.0 (Schema: 2026-05-24)

Novedades en 3.3.0

• Señales de comportamiento ligeras (siempre activas) — indicadores de timing simples como la duración de la sesión y la velocidad de la primera interacción del visitante. Sin datos biométricos y sin necesidad de consentimiento del usuario final.
• Biometría conductual (opt-in) — cuando lo activas en Backoffice → Settings → Behavioral Biometrics, Noxtica también analiza el ritmo del movimiento del ratón, el timing de clics y el desplazamiento. Esto cuenta como datos biométricos bajo la normativa de privacidad estricta, por lo que se requiere consentimiento explícito del usuario final. Consulta Biometría Conductual a continuación.
• Comprobación de coherencia de Apple Pay — confirma que un dispositivo que dice ser un iPhone se comporta como tal, detectando un truco de suplantación habitual.
• Coincidencia de fingerprint de red — reconoce los patrones de conexión característicos de las herramientas de automatización más comunes, de modo que el tráfico de scripts y bots destaca incluso cuando el navegador parece convincente.
• Reputación de IP — señala a los visitantes que llegan desde redes con mala reputación, con la opción de conectar tu propio feed de inteligencia de amenazas preferido.

Biometría Conductual (Opcional, Opt-In)

Noxtica también puede analizar el ritmo de cómo alguien mueve el ratón, hace clic y se desplaza. Es una función opt-in, desactivada por defecto.

¿Por qué opt-in? Este tipo de datos de comportamiento cuenta como datos personales sensibles bajo la normativa de privacidad estricta, por lo que capturarlos requiere el consentimiento explícito de tu usuario final. Lo hacemos opt-in para que tengas el control de cuándo y cómo se usa.

Para activarlo:

1. Inicia sesión en Backoffice → Settings → Behavioral Biometrics
2. Revisa el aviso de cumplimiento con tu equipo de privacidad o legal
3. Actualiza tu política de privacidad y banner de consentimiento para informar de esta captura
4. Activa la función

Una vez habilitado, Noxtica incorpora automáticamente estas señales de comportamiento en las evaluaciones futuras, y tu panel muestra la puntuación de comportamiento resultante por dominio.

Próximos Pasos

• Prueba la demo en vivo para ver el fingerprinting en acción
• Lee la guía de Integración con el Backend para consultas en el servidor
• Accede al panel para explorar los datos recopilados