@jaak.ai/document-detector

v2.0.5

Published

13 days ago

Stencil Component Starter

Downloads

1,038

0High
0Medium
0Low

rcristian

soyjesus

dev-jaak-ai

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

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 |

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'
 };

 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);
});

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'
        }
      };

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