Guía paso a paso de Integración de face-detector

Este documento describe paso a paso cómo crear un proyecto desde cero que reproduzca como hacer uso deface-detector-js-example de jaak-ai en un entorno sencillo con HTML, Javascript y CSS.

🚀 Prerrequisitos

Node.js v14 o superior instalado en tu máquina.
npm v6 o superior.
Editor de código (Visual Studio Code, WebStorm, etc.).
Conexión a Internet para cargar el componente desde un CDN.

📂 1. Crear la Carpeta del Proyecto

Abre tu terminal y ejecuta:

mkdir face-detector-example
cd face-detector-example

(Opcional) Inicializa un repositorio Git para control de versiones:
```
git init
```
Abre la carpeta en tu editor de código.

🛠️ 2. Levantar servidor local(Opción de Desarrollo)

Para poder ver los cambios en tiempo real sin refrescar manualmente el navegador, utilizaremos live-server.

Instalación global (requiere permisos de administrador):
```
npm install -g live-server
```
O bien ejecutarlo con npx sin instalación global:
```
npx live-server --port=8000
```

⚙️ 3. Crear el Archivo `index.html`

En la raíz del proyecto, crea un archivo llamado index.html y agrega el siguiente contenido:

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  <title>Face Detector Usage</title>
  <!-- Importa el componente desde unpkg -->
  <script type="module" src="https://unpkg.com/@jaak.ai/face-detector"></script>
</head>
<body>
  <div class="content">
    <div class="card">
      <div class="card-title">
        <h1>Face Detector</h1>
      </div>

      <!-- Overlay de carga -->
      <div id="loading" class="loading">Cargando...</div>

      <!-- Contenedor del componente -->
      <div class="frame">
        <div class="component-container">
          <face-detector id="faceDetector"></face-detector>
        </div>
      </div>
    </div>
  </div>

  <!-- Estilos inline para simplicidad -->
  <style>
    .content {
      height: 90vh;
      display: flex;
      align-items: center;
      justify-content: center;
      padding: 10px;
      margin-top: 1rem;
    }
    .card {
      border-radius: 10px;
      border: solid 1px #e5e5e5;
      box-shadow: 0 10px 40px 0 rgba(32, 41, 69, 0.1);
      height: 100%;
      max-height: 560px;
      width: 80%;
    }
    .card-title {
      text-align: center;
      margin-bottom: 20px;
    }
    .frame {
      position: relative;
      width: 100%;
      height: calc(560px - 80px); /* Altura total menos título */
      overflow: hidden;
    }
    .component-container {
      position: absolute;
      top: 0;
      right: 0;
      bottom: 0;
      left: 0;
      display: flex;
      align-items: center;
      justify-content: center;
      flex-direction: column;
    }
    .loading {
      position: absolute;
      top: 0;
      left: 0;
      width: 100%;
      height: 100%;
      background-color: rgba(0, 0, 0, 0.5);
      color: white;
      display: flex;
      align-items: center;
      justify-content: center;
      font-size: 1.2rem;
      z-index: 10;
    }
  </style>

  <!-- Lógica de configuración y eventos -->
  <script type="module">
    // ✨ Seleccionamos el componente en el DOM
    const faceDetector = document.querySelector('face-detector');
    const loading = document.getElementById('loading');

    // Ocultamos el overlay de carga inicialmente
    loading.style.display = 'none';

    // 📑 Configuración del componente
    const config = {
      mode: 'video-camera',           // Modo de captura: cámara o archivo
      timerStyles: {                  // Opciones de estilo del temporizador
        width: 80,
        height: 80,
        fontSize: 40,
        posY: 70,
      },
      width: '100%',                  // Ancho del componente
      height: '100%',                 // Alto del componente
      offlineModel: false,            // Si usa o no modelo offline
      validateCamera: true,           // Validar acceso a cámara
      enableInstructions: true,       // Mostrar instrucciones en pantalla
      delayInstructions: 1000,        // Tiempo antes de mostrar instrucciones (ms)
      delayReplayInstructions: 3000,  // Retraso para repetir instrucciones (ms)
      autoRecorder: true,             // Inicio automático de grabación
    };
    faceDetector.config = config;

    // 🔔 Manejo de eventos de estado
    faceDetector.addEventListener('status', (event) => {
      console.log('Status event:', event.detail);
      if (event.detail === 'loading') {
        loading.style.display = 'flex';
      } else {
        loading.style.display = 'none';
      }
    });

    // ⚠️ Manejo de errores del componente
    faceDetector.addEventListener('componentError', (event) => {
      console.error('Error event:', event.detail);
      // Aquí puedes mostrar una alerta o mensaje al usuario
    });

    // 📤 Recepción de resultados de captura (base64)
    faceDetector.addEventListener('fileResult', (event) => {
      console.log('Video capturado con éxito:', event.detail);
      sendVideoToVerify(event.detail.base64);
    });

    // Función de ejemplo para enviar video al servidor
    function sendVideoToVerify(videoBase64) {
      console.log('Enviando video para verificación:', videoBase64);
      stop();
      // Simulación de llamada a API...
      setTimeout(() => {
        console.log('Reiniciando componente tras verificación');
        restart();
      }, 3000);
    }

    // Métodos auxiliares del componente
    function stop() {
      faceDetector.stopComponent();     // Detiene la captura/temporizador
    }
    function restart() {
      faceDetector.restartComponent();  // Reinicia el flujo interno
      faceDetector.resetFaceDetector(); // Limpia datos de la sesión previa
    }
  </script>
</body>
</html>

📖 4. Explicación de la Configuración

mode: Determina si la captura es desde la cámara ("video-camera") o desde un archivo local.
timerStyles: Objeto para personalizar la apariencia del temporizador de cuenta regresiva.
width / height: Tamaño del área de video dentro del componente.
offlineModel: Si true, carga un modelo que no requiera conexión a Internet.
validateCamera: Verifica permisos de cámara antes de iniciar.
enableInstructions: Muestra guías visuales al usuario durante el proceso.
delayInstructions y delayReplayInstructions: Retrasos en milisegundos para mostrar o repetir instrucciones.
autoRecorder: Si true, inicia automáticamente la grabación cuando el modelo esté listo.

⚙️ 5. Eventos Principales

status: Indica el estado interno del componente. Valores frecuentes:
- "loading": Cargando modelo o recursos.
- "ready": Listo para capturar.
- "capturing": Grabando video.
componentError: Dispara cuando ocurre un error interno (p.ej., sin permisos de cámara).
- event.detail contiene el mensaje o código de error.
fileResult: Se emite al finalizar la captura de video.
- event.detail.base64 contiene el vídeo en formato Base64.

🛠️ 6. Métodos Útiles del Componente

Método	Descripción
`stopComponent()`	Detiene la grabación o temporizador activo.
`restartComponent()`	Reinicia el flujo de captura (temporizador, cámara).
`resetFaceDetector()`	Limpia datos y estados previos del detector facial.

✅ 7. Ejecutar la Aplicación

En la terminal, dentro de la carpeta del proyecto, lanza el servidor:

npx live-server --port=8000

Abre tu navegador en http://localhost:8000.
Verifica en la consola de desarrollador los logs de eventos.

🎉 8. Felicidades, has terminado!

Con esto tendrás un proyecto idéntico al ejemplo face-detector-js-example, totalmente funcional.