[ MANUALS & TECHNICAL DOCS ]

Manuales e Instructivos

Documentación técnica completa del ecosistema BRAIN: desde la integración del BrainPixel hasta la interpretación avanzada de métricas biométricas y el flujo de calibración GTI.

Integración del BrainPixel

Instala el pixel de telemetría biométrica en tu sitio web en menos de 5 minutos. Autorización de dominio, snippet y verificación de señal.

→ LEER GUÍA

Flujo GTI de Calibración

Entiende el protocolo de 7 estados que vive el participante: desde el consentimiento hasta la subida de telemetría al búnker de BRAIN.

→ LEER GUÍA

Interpretación de Métricas

Mapas de calor, ScanPath, Valencia Emocional y Disonancia Cognitiva: cómo leer cada output biométrico para tomar decisiones.

→ LEER GUÍA

Diseño de Experimentos

Mejores prácticas para configurar tests de Facial Coding y Eye Tracking con alta precisión. Entorno, postura y duración óptima.

→ LEER GUÍA
[ PIXEL INTEGRATION ]

Integración del BrainPixel

El BrainPixel es el script de telemetría que conecta cualquier sitio web externo con el motor biométrico de Synapse. Opera bajo pixel.js y requiere que el dominio esté previamente autorizado en tu cuenta de BRAIN.

Requiere HTTPS

El pixel usa la API de cámara del navegador. Solo funciona en sitios bajo protocolo HTTPS. En HTTP el navegador bloqueará los permisos.

1

Accede al Centro de Activación BrainPixel

Desde tu dashboard, navega a Configuración → BrainPixel o accede directamente a pixel-guide.html. Esta pantalla es tu panel de gestión de dominios y verificación de señal. Debes estar autenticado con tu cuenta de BRAIN.

2

Autoriza tu Dominio

Ingresa el dominio de tu sitio (sin https:// ni www) en el campo de texto y haz clic en "Autorizar Dominio". El sistema normaliza automáticamente la URL y registra el dominio en Firestore bajo tu ownerId.

Ejemplo de dominio autorizado 
// Ejemplos de entrada válida:
misitio.com
app.misitio.com
checkout.tienda.com

// El sistema normaliza automáticamente:
// "https://www.misitio.com/landing" → "misitio.com"

Un dominio por configuración de pixel

Puedes autorizar múltiples dominios desde la misma cuenta. Cada dominio tiene su propio árbol de sesiones en Firestore: users/{ownerId}/sites/{domain}/sessions.

3

Copia tu Snippet Personalizado

El Centro de Activación genera automáticamente un snippet único con tu ownerId incrustado. Cópialo con el botón "Copiar".

HTML Snippet — Pegar en <head> 
<!-- BrainPixel · Synapse Biometric Telemetry -->
<script src="https://brainresearch.online/pixel.js?owner=TU_OWNER_ID"></script>

El parámetro ?owner=TU_OWNER_ID es el identificador único de tu cuenta Firebase Auth. El pixel lo lee al inicializarse para asociar cada sesión a tu cuenta.

4

Pégalo en el <head> de tu Sitio

Inserta el snippet dentro de la etiqueta <head> de tu HTML, justo antes del cierre </head>. No es necesario el atributo async porque el pixel requiere ejecutarse antes de que el DOM esté completo para inicializar la telemetría.

Ejemplo de integración completa en HTML 
<head>
  <meta charset="UTF-8">
  <title>Mi Landing Page</title>
  
  <!-- Tu CSS y scripts -->
  <link rel="stylesheet" href="styles.css">

  <!-- BrainPixel (justo antes de cerrar /head) -->
  <script src="https://brainresearch.online/pixel.js?owner=TU_OWNER_ID"></script>
</head>
5

Verifica la Señal en Tiempo Real

En el Centro de Activación, selecciona el dominio que acabas de configurar en el menú desplegable. El panel de estado escucha en tiempo real via Firestore onSnapshot. Cuando el pixel se detecte correctamente en tu sitio, el indicador cambiará a ¡CONEXIÓN EXITOSA!.

Señal detectada: pixelDetected: true

El campo pixelDetected en el documento Firestore users/{ownerId}/sites/{domain} se actualiza a true cuando el pixel hace su primer handshake exitoso desde el dominio autorizado.

⚙

Integración Avanzada: Contexto Manual OPCIONAL

Si necesitas asociar sesiones a un experimento específico o pasar un ID de sesión personalizado, puedes definir el objeto window.synapse_context antes del snippet del pixel:

Contexto avanzado — window.synapse_context 
<script>
  // Define el contexto ANTES del pixel
  window.synapse_context = {
    ownerId: "TU_OWNER_ID",   // requerido
    sid:     "SESION_UNICA",    // ID único del visitante (ej: UUID generado)
    domain:  "misitio.com",    // debe coincidir con el dominio autorizado
    expId:   "ID_EXPERIMENTO",  // opcional: vincula sesión a un test específico
    duracion: 20               // opcional: segundos de grabación (defecto: 15)
  };
</script>
<script src="https://brainresearch.online/pixel.js?owner=TU_OWNER_ID"></script>

Si expId está presente, Firestore carga la duración del experimento desde la colección tests_images/{expId}. Si no se especifica, la sesión se registra como expId: "libre".

[ GTI PROTOCOL ]

Flujo GTI de Calibración

El protocolo GTI (Gestión de Transición Inteligente) es la máquina de estados que orquesta la experiencia del participante: desde el consentimiento legal hasta la subida de biometría al búnker de BRAIN. Está implementado en synapse-core.js v3.7.

GTI
LEGAL — Consentimiento Informado

El overlay negro aparece con el modal de bienvenida. Se informa al participante que el experimento requiere acceso a la cámara y que ningún dato personal, imagen ni video saldrá de su dispositivo. El usuario debe hacer clic en "Aceptar y Continuar" para proceder. Si rechaza, el flujo se detiene.

ADJ
ADJUST — Ajuste y Centrado Facial

Se activa SynapseFacial.startMirror(), que carga los modelos de IA (faceapi.js: TinyFaceDetector + FaceExpression + FaceLandmark68) y enciende WebGazer. El espejo facial aparece mostrando el video de la cámara con un canvas superpuesto. El sistema dibuja un encuadre BRAIN sobre el rostro detectado: rojo cuando no está centrado, cyan cuando sí. El botón "Estoy Centrado" solo se activa cuando el algoritmo de distancia elíptica confirma que el rostro está centrado y tiene el tamaño mínimo requerido.

INS
INSTRUCT — Instrucciones de Calibración

Se muestra el modal de instrucciones de calibración ocular. El participante ve las tarjetas de requisitos: Sin Lentes y Sin Contraluz. Se explica la mecánica del marcianito (Space Invader): hay que mirarlo fijamente y hacer clic para dispararle. La mira reticular seguirá la posición de los ojos en tiempo real para guiar al participante.

CAL
CALIBRATE — Calibración Ocular de 7 Puntos

El fondo de partículas aparece. El marcianito (punto de calibración) vuela sucesivamente a 7 posiciones del viewport: esquinas superior-izquierda y superior-derecha, laterales medios (izquierda y derecha), centro, esquinas inferior-izquierda e inferior-derecha. Para cada punto:

  • El Gaze Security Gate valida que la distancia euclidiana entre el punto donde mira el ojo (via WebGazer) y la posición del clic sea ≤ 130px. Si la distancia es mayor, el clic se ignora.
  • Si pasa el gate, webgazer.recordScreenPosition() registra el punto de calibración.
  • Un destello amarillo confirma visualmente el punto aceptado.
  • El marcianito anima su animación "hit" y se mueve al siguiente punto.

Completados los 7 puntos, el estado transiciona a READY.

RDY
READY — Sistema Listo

Modal de confirmación: "Configuración Completada. Los parámetros biométricos han sido sincronizados con éxito." El participante hace clic en "Iniciar Experimento" para comenzar la grabación. En este punto el fondo de partículas sigue visible pero el espejo facial ya está oculto.

TEST
TEST — Grabación Activa

El overlay negro desaparece (quitarBacking + quitarBlackout) y el estímulo visual queda expuesto. Simultáneamente se activan dos motores en paralelo:

  • SynapseGaze: Registra cada frame de WebGazer con posición absoluta (x, y en px), normalizada (nx, ny de 0 a 1), scroll offset (s) y timestamp relativo (t en ms).
  • SynapseFacial: A 4Hz (cada 250ms), detecta la expresión facial dominante con faceapi.detectSingleFace().withFaceExpressions() y la mapea a Valencia Emocional (positiva/neutral/negativa). Si el rostro desaparece por más de 2 segundos, se emite core:expulsion.

El timer del experimento corre según duracion (default: 15s). Al agotarse, transiciona automáticamente a FINISH.

FIN
FINISH — Sincronización y Cierre

Aparece el modal "Sincronizando Red Neural…" con el loader animado. En paralelo:

  • SynapseFacial.stopAll() emite el JSON de emociones hacia SynapseSync.uploadBiometrics().
  • SynapseGaze.stopAll() emite el array de gaze hacia SynapseSync.uploadTelemetry().
  • SynapseSync sube ambos archivos a Firebase Storage: capturas_neuro/{ownerId}/{domain}/{sid}/emociones_ia.json y telemetria_neuro.json.
  • Una vez completas ambas subidas, actualiza Firestore con hasNeuro: true, estado: "pendiente_ia" y consume un crédito de sesión via SynapseBilling.
  • El Portero (finalPush) espera a que activeUploads === 0 y redirige a test-ended.html.

Protocolo de Expulsión por Integridad

Si durante el estado TEST el motor facial detecta que el rostro desapareció por más de 2 segundos consecutivos (el participante se alejó, tapó la cámara o cerró los ojos extendidamente), el sistema emite el evento core:expulsion y redirige automáticamente a experimento-fallido.html. Esto protege la calidad de los datos capturados.

Estructura de archivos en Firebase Storage

📁 Firebase Storage
├── capturas_neuro/
│   └── {ownerId}/
│       └── {domain}/
│           └── {sid}/
│               ├── emociones_ia.json      ← array de {t, e, v, p}
│               └── telemetria_neuro.json  ← {mirada: [{x,y,nx,ny,s,t}]}
└── procesados/
    └── {ownerId}/
        └── {domain}/
            └── {sid}_Consolidado.json  ← reporte fusionado final
[ METRICS & ANALYTICS ]

Interpretación de Métricas

Cada sesión procesada por BRAIN produce un Reporte Consolidado con cuatro capas de análisis. Aprende a leer cada output biométrico para extraer insights accionables.

Attention Heatmap

Visualización de densidad de la mirada. Las zonas rojas/calientes concentran la mayor cantidad de tiempo de fijación foveal; las azules/frías son áreas ignoradas. Los puntos de gaze raw (nx, ny) normalizados de 0 a 1 se acumulan en una grilla y se representan con un gradiente de color. Úsalo para validar si tu CTA, headline o imagen principal captura atención.

ScanPath Chronology

Recorrido cronológico de la mirada representado con círculos numerados. El algoritmo agrupa puntos de gaze consecutivos dentro de un radio de 65px para crear fijaciones. El tamaño del círculo refleja la duración de la fijación. Las líneas entre círculos muestran sacadas (saltos de mirada). Revela el orden de lectura real vs. el orden diseñado.

Valencia Emocional

Mide la respuesta afectiva del participante a 4Hz. faceapi detecta 7 emociones base: happy, surprised (→ positiva); neutral (→ neutral); angry, disgusted, fearful, sad (→ negativa). Cada frame incluye emoción dominante (e), valencia (v) y probabilidad (p). Identifica picos de impacto emocional frente a estímulos específicos.

Gaze Plot & Fijaciones

Output procesado que fusiona la telemetría ocular con la valencia emocional. Cada fijación del gaze_plot incluye: posición (x, y en px), timestamp (t), duración en ms, número de orden y valencia dominante del cluster. Permite ver no solo dónde miró el usuario sino cómo se sentía en ese momento.

Estructura del Reporte Consolidado

JSON — {sid}_Consolidado.json 
{
  "sid": "abc123",          // ID de sesión
  "uid": "owner456",       // ID del propietario
  "dom": "misitio.com",   // Dominio del experimento
  "url": "https://...",   // URL exacta del estímulo
  "duracion": 18,         // Segundos efectivos capturados
  
  "neuro": [              // Array de puntos de mirada con emoción fusionada
    { "x": 640, "y": 320, "nx": 0.5, "ny": 0.42, "s": 0, "t": 450,
      "emotion": "happy", "valencia": "positiva" },
    // ... un punto por frame de WebGazer (aprox. cada 33ms)
  ],
  
  "gaze_plot": [          // Fijaciones calculadas (clusters de gaze)
    { "x": 635, "y": 315, "t": 200, "duracion": 820, 
      "orden": 1, "valencia": "positiva" },
    // ... una fijación por cluster (radio umbral: 65px)
  ],
  
  "movimientos": [],     // Movimientos de mouse (web tracker)
  "clics": [],           // Clics registrados
  "video_dom": [],       // Eventos DOM en video (si aplica)
  "fecha_proceso": "2026-06-28T..."
}
📊

Cómo leer el Dashboard de Resultados

En tu dashboard de BRAIN (dashboard-general.html), cada sesión procesada aparece en el panel de sesiones con su estado:

  • pendiente_ia — Los archivos están en Storage, esperando procesamiento por Cloud Functions.
  • completado — El reporte consolidado fue generado y está disponible para visualización.
  • error_ia — El procesamiento falló (archivo corrupto o vacío). La sesión fue marcada para evitar bucles.
  • error_consolidacion — El archivo web no pudo leerse o la carpeta estaba vacía.

Accede a la radiografía completa de una sesión haciendo clic en su fila. Dispondrás del Heatmap, ScanPath, gráfica de Valencia Emocional y la cronología de eventos.

[ EXPERIMENT DESIGN ]

Diseño de Experimentos

La calidad de los datos biométricos depende directamente de las condiciones del entorno y la configuración del test. Estas guías se derivan de los requisitos técnicos reales de los módulos SynapseFacial y SynapseGaze.

1

Iluminación: el Factor Crítico

El modelo TinyFaceDetector de faceapi.js necesita al menos 30 lux de iluminación frontal uniforme para detectar la cara con fiabilidad. Recomienda a tus participantes:

  • Posicionarse frente a una fuente de luz (lámpara de escritorio, ventana frontal), nunca detrás.
  • Evitar luz directa muy intensa que genere sombras fuertes en el rostro.
  • Apagar luces de neón de colores: crean dominantes que confunden al detector.
  • Nunca usar lentes (ni transparentes). Los reflejos en los cristales interfieren con el tracking de la pupila de WebGazer.
2

Posición y Distancia del Participante

El algoritmo de centrado facial de SynapseFacial.verificarCentrado() valida que:

  • El centro del rostro esté dentro de una elipse de 35x50px respecto al centro del canvas (380x280px).
  • El ancho detectado del rostro sea mayor a 105px escalado al canvas.

En la práctica esto equivale a:

  • Distancia a pantalla: entre 50 y 70 cm.
  • Cámara a la altura de los ojos, no desde abajo ni desde arriba.
  • Cara centrada en el frame de la cámara, no desplazada lateralmente.
3

Calibración: 7 Puntos vs. 5 Puntos

El módulo SynapseGaze v2.6 usa 7 puntos de calibración (superior-izquierda, superior-derecha, lateral-izquierda, lateral-derecha, centro, inferior-izquierda, inferior-derecha) para mayor cobertura del viewport y mejor anclaje en las esquinas. Versiones anteriores usaban 5 puntos.

El Gaze Security Gate requiere que el usuario esté mirando al marcianito (distancia ojo→marcianito ≤ 130px) en el momento del clic. Si el clic se hace sin mirar el punto, se ignora. Esto garantiza que los datos de calibración sean auténticos.

Instrucción al participante

Debe mantener la cabeza fija durante toda la calibración. Solo deben moverse los ojos, no la cabeza. Si mueve la cabeza entre puntos, el modelo pierde precisión.

4

Duración Óptima del Experimento

La duración se configura en el experimento (tests_images/{expId}.segundos). Guía de referencia:

  • 10–15 s: Landing pages simples, creatividades estáticas. Alta atención, datos densos.
  • 15–25 s: Páginas de producto, emails, infografías. Rango óptimo recomendado.
  • 25–45 s: Flujos de checkout, páginas largas con scroll. Datos válidos pero mayor varianza.
  • +45 s: No recomendado. La fatiga visual degrada la señal de gaze y la expresión emocional pierde naturalidad.
5

Diseño del Estímulo Visual

Para obtener resultados accionables, el estímulo visual (tu landing page, creatividad o video) debe:

  • Ser una sola pantalla de alto valor: evita páginas con demasiado scroll durante el test.
  • Tener un CTA visible sin hacer scroll (above the fold), para evaluar si recibe atención.
  • Ser la versión HTTPS de producción, no una vista local o en localhost.
  • Si incluye video, asegurarte de que el autoplay esté habilitado para que inicie al aparecer el estímulo.

Tip: A/B Testing Biométrico

Crea dos experimentos con el mismo domain pero diferentes expId. Cada experimento apunta a una versión diferente del estímulo (variante A y variante B). Compara los Heatmaps y la Valencia Emocional promedio para identificar cuál versión genera mayor engagement.

6

Muestra Estadística Mínima

Para que los mapas de calor y los datos de Valencia Emocional sean estadísticamente robustos, se recomienda:

  • Mínimo 15 sesiones completadas por variante para tendencias de atención visual.
  • Mínimo 25–30 sesiones para comparaciones de Valencia Emocional y análisis de Disonancia Cognitiva.
  • Excluir sesiones con duración < 5s (el participante probablemente cerró la ventana antes de que el estímulo cargara).

El dashboard muestra el contador de subjectsCompleted en tiempo real desde el documento del experimento en Firestore.