@jaak.ai/document-detector NPM

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:

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

Descarga e instala Node.js desde nodejs.org. npm se incluye automáticamente con Node.js.
Verifica las versiones instaladas ejecutando:
```
node -v
npm -v
```

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

Ejecuta el siguiente comando para instalar el componente:
```
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.

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

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

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

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

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

Response

{
  "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:

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

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

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

<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 como parte de un componente de React, simplemente impórtalo de la siguiente manera:

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

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:

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.

schemas: [CUSTOM_ELEMENTS_SCHEMA]

Paso 2: Importar el componente

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

// main.ts

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

Paso 3: Usar el componente en tu proyecto

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

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 inhttps://jaak.ai

@jaak.ai/file-uploader @jaak.ai/video-camera @microblink/blinkid-in-browser-sdk @tensorflow/tfjs rxjs

1 year ago

8 months ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

12 months ago

12 months ago

8 months ago

1 year ago

1 year ago

1 year ago

12 months ago

1 year ago

6 months ago

1 year ago

6 months ago

1 year ago

6 months ago

7 months ago

1 year ago

8 months ago

1 year ago

6 months ago

6 months ago

1 year ago

7 months ago

12 months ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

1 year ago

2 years ago

2 years ago

2 years ago

2 years ago

1 year ago

1 year ago

2 years ago

2 years ago

1 year ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago

2 years ago