npm package: @jaak.ai/document-detector
Description: Stencil Component Starter
Latest version: 2.1.2

## Introducción

DocumentDetector es un componente independiente desarrollado en StencilJS que permite a los desarrolladores integrar la
funcionalidad de captura y detección de imágenes de documentos de identificación en sus plataformas. Este componente
ofrece dos principales capacidades:

Selección de archivos desde el dispositivo: Permite al usuario cargar imágenes desde el almacenamiento del dispositivo.
El componente verifica si el archivo corresponde a un documento válido y, en caso afirmativo, emite la imagen procesada
en formato Base64.

Captura de imágenes mediante la cámara: Activa la cámara del dispositivo, detecta automáticamente el documento y permite
capturar una imagen cuando el documento está correctamente posicionado. La imagen capturada también se emite en formato
Base64.

El uso de DocumentDetector, permite una implementar la funcionalidad de detección y procesamiento de documentos en sus
aplicaciones, de forma fácil y sencilla proporcionando una experiencia ágil y confiable para los usuarios.

## Instalación

Para integrar el componente web **DocumentDetector** en tu proyecto, es necesario utilizar **npm**, el gestor de
paquetes de Node.js. Sigue estos pasos:

1. **Asegúrate de tener instalado Node.js y npm:**

- Descarga e instala Node.js desde [nodejs.org](https://nodejs.org). npm se incluye automáticamente con Node.js.
- Verifica las versiones instaladas ejecutando:
   ```bash
   node -v
   npm -v
   ```

2. **Ubica la raíz de tu proyecto:**

- Navega hasta el directorio raíz de tu proyecto, donde se encuentra el archivo `package.json`.

> Nota: Si no tienes un archivo package.json, inicializa un proyecto de node con el comando ```npm init```

1. **Ejecuta el siguiente comando para instalar el componente:**

 ```bash 
 npm install @jaak.ai/document-detector 
 ```

Este comando añadirá el paquete **"@jaak.ai/document-detector"** como dependencia en tu proyecto, lo que permitirá
utilizar el componente en tu código.

4. **Verifica la instalación:**

- Una vez instalado, asegúrate de que el componente aparece en las dependencias listadas en tu archivo `package.json`.

## Setup y Configuración del Componente

El componente **DocumentDetector** requiere una configuración inicial mediante propiedades que se establecen como
atributos en su instancia. Estas propiedades permiten personalizar su comportamiento y apariencia. A continuación, se
detalla cada uno de los parámetros configurables:

| Propiedad            | Descripción                                                                                                                                                                                                                | Requerido | Tipo                           | Valor por defecto |
|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|--------------------------------|-------------------|
| key                  | Key de autenticación proporcionado por el equipo de administración de JAAK al contratar los servicios. Contacte a soporte para más información.                                                                            | Si        | string                         |                   |
| mode                 | Define el modo de operación del componente: detección y captura mediante subida de archivos (`upload-file`) o mediante la cámara del dispositivo (`video-camera`).                                                         | si        | `video-camera`or `upload-file` | `upload-file`     |
| documentDetect       | Activa la detección de documentos en el modo (`video-camera`).                                                                                                                                                             | no        | boolean                        | true              |
| videoFeedback        | Activa los mensajes en pantalla en la detección de documentos en el modo (`video-camera`).                                                                                                                                 | no        | boolean                        | true              |
| width                | Especifica el ancho del elemento HTML del componente.                                                                                                                                                                      | no        | string                         | `500px`           |
| height               | Especifica el alto del elemento HTML del componente.                                                                                                                                                                       | no        | string                         | `400px`           |
| progressiveDetection | Activa la detección progresiva, permitiendo que el componente siga detectando y capturando documentos de forma continua hasta que el desarrollador detenga manualmente la operación o elimine la instancia del componente. | no        | boolean                        | false             |
| placeholder          | (Modo `'upload-file'`) Define el texto que se mostrará como marcador de posición en el campo de selección de archivos.                                                                                                     | no        | string                         | N/A               |
| buttonText           | (Modo `'upload-file'`) Define el texto que aparecerá en el botón para subir archivos.                                                                                                                                      | no        | string                         | N/A               |
| size                 | (Modo `'upload-file'`) Establece el tamaño máximo permitido para los archivos que se pueden subir, especificado en kilobytes (KB).                                                                                         | no        | number                         | N/A               |
| translate            | (Modo 'video-camera') Permite personalizar los textos de las instrucciones para la captura del documento, proporcionando un objeto de traducciones.                                                                        | no        | Object                         | N/A               |
| sdkConfig            | Permite configurar opciones avanzadas del SDK de reconocimiento de documentos.                                                                                                                                              | no        | Object                         | N/A               |

#### Configuración propiedad Translate:

Para configurar las instrucciones de los textos utiliza un objeto con las siguientes propiedades:

| Propiedad                        | Tipo     | Valor por defecto                                       |
|----------------------------------|----------|---------------------------------------------------------|
| `front`                          | `string` | Acerca la parte frontal de tu documento                 |
| `back`                           | `string` | Acerca la parte trasera de tu documento                 |
| `changeSide`                     | `string` | Voltea tu documento                                     |
| `adjustAngle`                    | `string` | Ajustar el ángulo                                       |
| `cameraFeedbackBlur`             | `string` | Quédate quieto                                          |
| `cameraFeedbackFacePhotoCovered` | `string` | Incline o mueva el documento para eliminar los reflejos |
| `cameraFeedbackGlare`            | `string` | Dar la vuelta al documento                              |
| `cameraFeedbackWrongSide`        | `string` | Mantenga la foto de la cara completamente visible       |
| `moveCloser`                     | `string` | Acércate más                                            |
| `moveFarther`                    | `string` | Muévete más lejos                                       |

#### Configuración propiedad sdkConfig:

Para configurar opciones avanzadas del SDK de reconocimiento de documentos utiliza un objeto con las siguientes propiedades:

| Propiedad         | Tipo                      | Descripción                                                                                                                 | Valor por defecto |
|-------------------|---------------------------|-----------------------------------------------------------------------------------------------------------------------------|-------------------|
| `forceMobileMode` | `boolean`                 | Fuerza el modo móvil del SDK independientemente del dispositivo detectado.                                                  | false             |
| `modelIdVariant`  | `'lightweight' \| 'full'` | Define la variante del SDK a utilizar: 'lightweight' para una versión más ligera o 'full' para todas las funcionalidades.  | 'full'            |
| `initialMemory`   | `number`                  | Establece la cantidad inicial de memoria (en MB) asignada al SDK.                                                           | 64                |
| `numberOfWorkers` | `number \| null`          | Define el número de workers que utilizará el SDK. Si es null, se utilizará el número óptimo según el dispositivo.           | null              |

### Añade el Componente a tu archivo HTML

```html
<!DOCTYPE html>
<html dir="ltr" lang="en">
<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0, minimum-scale=1.0, maximum-scale=5.0"/>
  <title>Jaak Web Components</title>
  <script type="module" src="https://unpkg.com/@jaak.ai/document-detector"></script>
  <style>
    .demo-container {
      display: flex;
      padding-top: 80px;
      justify-content: center;
      gap: 50px;
      flex-wrap: wrap;
    }
  </style>
</head>
<body>
<div class="demo-container">
  <document-detector></document-detector>
</div>
</body>
</html>
```

### Ejemplo de Configuración

Para configurar el componente, añade un bloque `<script>` en tu archivo HTML. Dentro de este, obtendrás la instancia del
componente y establecerás las configuraciones necesarias.

#### Paso 1: Obtener la instancia del componente

Utiliza el método `document.querySelector` para seleccionar el elemento **DocumentDetector** que has añadido en tu HTML:

```html

<script>
  const detector = document.querySelector("document-detector");
</script>
```

#### Paso 2: Configurar las propiedades del componente

Define un objeto de configuración llamado `userConfig` con las propiedades deseadas. Luego, asigna este objeto a la
propiedad `config` de la instancia del componente:

 ```js
const userConfig = {
  key: 'your-access-key',
  width: '640px',
  height: '480px',
  mode: 'video-camera',
  placeholder: 'Upload your document',
  buttonText: 'Upload',
  size: 2048,
  translate: {
    front: 'Acerca el doc',
    back: 'Acerca el reverso del doc',
    changeSide: 'Voltea tu doc',
    adjustAngle: 'Rota tu doc',
    cameraFeedbackBlur: 'No te muevas'
  },
  sdkConfig: {
    forceMobileMode: false,
    modelIdVariant: 'full',
    initialMemory: 64,
    numberOfWorkers: null
  }
}

  detector.config = userConfig;
  ```

### Obtener Resultados del DocumentDetector

Para recibir los resultados generados por el componente, utiliza un `EventListener` que escuche los eventos emitidos por
el componente. Este evento proporciona los resultados a través del atributo `detail` del objeto del evento.

Añade el siguiente código dentro del bloque `<script>`:

```js
detector.addEventListener("results", e => {
  // Los resultados emitidos por el componente
  console.log('RESULTS:');
  console.log(e.detail);
});
```

#### Response

```json
{
  "documentData": {
    "generalData": {
      "type": "ID",
      "nationality": "MEXICAN",
      "name": "MARIA FERNANDA",
      "surname": "RODRIGUEZ",
      "motherSurname": "VALENCIA",
      "address": "AV REFORMA 247\nCOL JUAREZ 06600\nCUAUHTEMOC, CDMX",
      "expiryPermanent": false,
      "birthDate": "891225",
      "gender": "M",
      "documentImage": {
        "frontFull": "/9j/4AAQ...",
        "backFull": "/9j/4AAQ...",
        "front": "/9j/4AAQ...",
        "back": "/9j/4AAQ...",
        "signature": "/9j/4AAQ...",
        "face": "/9j/4AAQ..."
      }
    },
    "mechanicalReadingZone": "IDMEX8901234567<<8912254M2512311MEX<02<<12345<6\nRODRIGUEZ<VALENCIA<<MARIA<FERNANDA<<\n",
    "specificData": [
      {
        "label": "curp",
        "value": "ROVM123456MDFDRR78"
      },
      {
        "label": "electorKey",
        "value": "RDVLMF123456M789"
      },
      {
        "label": "registerYear",
        "value": 2023
      },
      {
        "label": "registerMonth",
        "value": 6
      },
      {
        "label": "emissionYear",
        "value": 2023
      },
      {
        "label": "identificationOCR",
        "value": "0123456789123"
      },
      {
        "label": "numIdentificationCredential",
        "value": "123456789"
      }
    ]
  }
}
```

| **Llave**                    | **Tipo de Dato**     | **Descripción**                                         |
|------------------------------| -------------------- |---------------------------------------------------------|
| documentData                 | Objeto               | Contiene toda la información extraída del documento.    |
| └── generalData              | Objeto               | Datos generales del titular del documento.              |
| └──── type                   | Cadena (string)      | Tipo de documento identificado (ej. "ID").              |
| └──── nationality            | Cadena (string)      | Nacionalidad del titular.                               |
| └──── name                   | Cadena (string)      | Nombre(s) del titular.                                  |
| └──── surname                | Cadena (string)      | Primer apellido del titular.                            |
| └──── motherSurname          | Cadena (string)      | Segundo apellido o apellido materno del titular.        |
| └──── address                | Cadena (string)      | Dirección completa del titular.                         |
| └──── expiryPermanent        | Booleano (boolean)   | Indica si el documento tiene vigencia permanente.       |
| └──── birthDate              | Cadena (string)      | Fecha de nacimiento del titular.                        |
| └──── gender                 | Cadena (string)      | Género del titular.                                     |
| └──── documentImage          | Objeto               | Imágenes relacionadas con el documento.                 |
| └────── front                | Cadena (string)      | Imagen frontal del documento (puede estar vacía).       |
| └────── back                 | Cadena (string)      | Imagen trasera del documento (puede estar vacía).       |
| └────── signature            | Cadena (string)      | Imagen de la firma del titular (puede estar vacía).     |
| └────── face                 | Cadena (string)      | Imagen del rostro del titular (puede estar vacía).      |
| └────── frontFull            | Cadena (string)      | Imagen completa de la parte frontal del documento.      |
| └────── backFull             | Cadena (string)      | Imagen completa de la parte trasera del documento.      |
| └── mechanicalReadingZone    | Cadena (string)      | Zona de lectura mecánica (MRZ) del documento.           |
| └── specificData             | Arreglo de Objetos   | Información específica adicional del documento.         |
| └──── label                  | Cadena (string)      | Etiqueta identificadora del dato específico.            |
| └──── value                  | Variado (string/int) | Valor del dato específico (CURP, clave de elector, etc.). |

> Nota: La información extraída del documento puede variar según el tipo de documento identificado.

### Resultado Final

Tu archivo HTML quedará estructurado de la siguiente forma:

```html

<document-detector></document-detector>
<script>
  const detector = document.querySelector("document-detector");
  const userConfig = {
    key: 'your-access-key',
    width: '640px',
    height: '480px',
    mode: 'video-camera',
    placeholder: 'Upload your document',
    buttonText: 'Upload',
    size: 2048,
    translate: {
      front: 'Acerca el documento',
      back: 'Acerca el reverso del documento',
      changeSide: 'Voltea tu documento',
      adjustAngle: 'Rota tu documento',
      cameraFeedbackBlur: 'Mantén la cámara estable'
    }
  };
  detector.config = userConfig;
  detector.addEventListener("results", (e) => {
    console.log('RESULTS:');
    console.log(e.detail);
  });
</script>
```

## Métodos Adicionales

La instancia del componente ofrece métodos adicionales que permiten acceder y ejecutar funcionalidades predefinidas del
componente de manera sencilla.

| **Método**              | **Descripción**                                                                                        | **Parámetros**                                                      | **Retorno**                                     |
|-------------------------|--------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------|-------------------------------------------------|
| **switchMode(newMode)** | Cambia el modo operativo del componente.                                                               | `newMode` _(string)_: Puede ser `'video-camera'` o `'upload-file'`. | Ninguno (`void`).                               |
| **getMode()**           | Devuelve el modo operativo actual del componente.                                                      | Ninguno                                                             | _(string)_: `'video-camera'` o `'upload-file'`. |
| **uploadFile()**        | Permite subir un archivo e iniciar el proceso de detección de documentos.                              | Ninguno                                                             | Ninguno (`void`).                               |
| **startDetection()**    | Inicia la detección de documentos utilizando la cámara del dispositivo.                                | Ninguno                                                             | Ninguno (`void`).                               |
| **stopComponent()**     | Detiene las operaciones del componente invocando internamente el método `stopCore`.                    | Ninguno                                                             | Ninguno (`void`).                               |
| **restartComponent()**  | Reinicia el componente, restableciéndolo a su estado inicial utilizando el método interno `resetCore`. | Ninguno                                                             | Ninguno (`void`).                               |

### Ejemplo de uso

En este ejemplo, añadiremos un botón a tu archivo HTML que permitirá alternar entre los dos modos operativos del
componente (`video-camera` y `upload-file`).

#### Estructura HTML

Crea un contenedor que incluya el componente y un botón para realizar el cambio de modo:

```html

<div class="demo-container">
  <document-detector></document-detector>
</div>


<button onclick="switchMode()">Switch mode</button>
```

#### Lógica del Botón

Dentro de la etiqueta `<script>`, añade el siguiente código para implementar la funcionalidad del botón:

```html

<script>
  //...Código anterior
  //...
  //...
  async function switchMode() {
    detector.switchMode(await detector.getMode() === "video-camera" ? "upload-file" : "video-camera");
  }
</script>
```

#### Resultado

Con este código, al hacer clic en el botón, el componente alternará dinámicamente entre los modos `video-camera` y
`upload-file`. Esto facilita cambiar la funcionalidad según las necesidades del usuario sin necesidad de recargar la
página.

## Eventos Adicionales

El componente emite diferentes eventos que permiten al desarrollador recibir información y retroalimentación sobre el
estado y los resultados del componente. Estos eventos pueden ser utilizados para ejecutar lógica personalizada según las
necesidades del proyecto.

| **Evento**         | **Descripción**                                                                            | **Detalle del Evento**                                             |
|--------------------|--------------------------------------------------------------------------------------------|--------------------------------------------------------------------|
| **status**         | Se emite cuando el estado del componente cambia.                                           | _(string)_: El nuevo estado del componente.                        |
| **componentError** | Se emite cuando ocurre un error interno en el componente.                                  | _(object)_: Detalles del error ocurrido.                           |
| **results**        | Emite los resultados de la detección de documentos.(ejemplo de uso descrito anteriormente) | _(object)_: Contiene los datos procesados del documento detectado. |

#### Ejemplo de Uso

Puedes escuchar estos eventos utilizando el método `addEventListener` sobre la instancia del componente:

```html

<script>
  const detector = document.querySelector("document-detector");
  // Tú Código
  // ...
  // ...
  // Escucha el evento 'status' 
  detector.addEventListener("status", (e) => {
    console.log("Nuevo estado del componente:", e.detail);
  });

  // Escucha el evento 'componentError'   
  detector.addEventListener("componentError", (e) => {
    console.error("Error en el componente:", e.detail);
  });
</script>
```

## Eso en React

Paso 1: Configurar componente

Para usar <document-detector /> como parte de un componente de React, simplemente
impórtalo de la siguiente manera:

```tsx
// Importarlo dentro del archivo de carga de la app App.tsx, main.tsx, index.tsx, etc.

import {defineCustomElements as defineDocumentDetector} from '@jaak.ai/document-detector/loader';

defineDocumentDetector(window);
```

Paso 2: Definir el componente para su uso en React

Declarar de manera global el componente en un archivo global.d.ts o seguido del archivo anterior

```tsx

declare global {
  namespace JSX {
    interface IntrinsicElements {
      'document-detector': React.DetailedHTMLProps<
        React.HTMLAttributes<HTMLElement>,
        HTMLElement
      >;
    }
  }
}

```

Paso 3: Usar el componente en tu proyecto

Ahora lo podrás usar en tu proyecto de React:

```tsx
function App() {
  const documentDetectorRef = useRef<any>(null);

  useEffect(() => {
    if (documentDetectorRef.current) {
      documentDetectorRef.current.config = {
        key: 'your-access-key',
        width: '640px',
        height: '480px',
        mode: 'video-camera',
        placeholder: 'Upload your document',
        buttonText: 'Upload',
        size: 2048,
        translate: {
          front: 'Acerca el documento',
          back: 'Acerca el reverso del documento',
          changeSide: 'Voltea tu documento',
          adjustAngle: 'Rota tu documento',
          cameraFeedbackBlur: 'Mantén la cámara estable'
        },
        sdkConfig: {
          forceMobileMode: false,
          modelIdVariant: 'full',
          initialMemory: 64,
          numberOfWorkers: null
        }
      };

      const documentDetector = documentDetectorRef.current;

      // Escucha el evento results
      documentDetector.addEventListener('results', (event: any) =>
        console.log('result ->', event.detail)
      );
    }
  }, []);

  return (
    <>
      <div>
        <document-detector
          ref={documentDetectorRef}
        ></document-detector>
      </div>
    </>
  );
}

export default App;
```

## Uso en Angular

Paso 1: Configurar componente

En Angular Además, debes configurar CUSTOM_ELEMENTS_SCHEMA en el módulo donde se utilizara el componente.

```ts
schemas: [CUSTOM_ELEMENTS_SCHEMA]
```

Paso 2: Importar el componente

Impórtalo en el archivo main.ts de la siguiente manera:

```ts 
// main.ts

import '@jaak.ai/document-detector';
```

Paso 3: Usar el componente en tu proyecto

```html

<document-detector
  [config]="{
        key: 'your-access-key',
        width: '640px',
        height: '480px',
        mode: 'video-camera',
        placeholder: 'Upload your document',
        buttonText: 'Upload',
        size: 2048,
        translate: {
            front: 'Acerca el documento',
            back: 'Acerca el reverso del documento',
            changeSide: 'Voltea tu documento',
            adjustAngle: 'Rota tu documento',
            cameraFeedbackBlur: 'Mantén la cámara estable'
        },
        sdkConfig: {
            forceMobileMode: false,
            modelIdVariant: 'full',
            initialMemory: 64,
            numberOfWorkers: null
        }
    }"
  (results)="handleResults($event)"
  (status)="handleStatus($event)"
  (componentError)="handleComponentError($event)"
></document-detector>
```

#### Información Adicional

Este paquete puede requerir el uso de dependencias adicionales para su correcto funcionamiento, revise su versión de
node:

```bash
npm install @jaak.ai/video-camera @jaak.ai/document-detector
```

This component is designed, developed and owned by JAAK and is their intellectual property. Visit more details
in[https://jaak.ai](https://jaak.ai/)