Integración con Angular

Aprenda cómo integrar la biblioteca fw-ocrid en su proyecto Angular creando un componente reutilizable para la funcionalidad de OCR, paso a paso.

---

Implementación Básica

import { Component, ViewChild, OnInit, OnDestroy } from '@angular/core';
import { OcrId, Envs, EventType, EventTypeUserFeedback, Endpoints, ResultHelper } from 'fw-ocrid';

@Component({
  selector: 'app',
  template: `<div class="videoContainer" #container></div>`
})
export class App implements OnInit, OnDestroy {
  @ViewChild('videoContainer', { static: false }) videoContainer: any; // Referencia al contenedor de video
  private ocrid: OcrId; // Instancia de OCRID
  public processId: string;
  public result: any;

  async ngOnInit(): Promise<void> {
    // Inicializar OCRID con API Key, entorno, configuración opcional e idioma opcional
    this.ocrid = new OcrId('YOUR_API_KEY', Envs.PRE3, undefined, 'en');

    // Suscripción a eventos de retroalimentación del usuario
    this.ocrid.events(EventType.USER_FEEDBACK).subscribe((feedback) => {
      switch (feedback) {
        case EventTypeUserFeedback.SHOW_DOCUMENT_FRONT_SIDE:
          console.log('Muestra el frente del documento.');
          break;
        case EventTypeUserFeedback.SHOW_DOCUMENT_REVERSE_SIDE:
          console.log('Muestra el reverso del documento.');
          break;
        case EventTypeUserFeedback.DOCUMENT_FRONT_SIDE_COMPLETED:
          console.log('Frente del documento escaneado con éxito.');
          break;
        case EventTypeUserFeedback.PROCESS_FAILED_DUE_ANALYSIS_ERROR:
          console.error('Proceso fallido debido a un error de análisis.');
          break;
        case EventTypeUserFeedback.PROCESS_FINISHED:
          console.log('Proceso de escaneo completado.');
          break;
      }
    });

    // Suscripción a eventos de resultado
    this.ocrid.events(EventType.RESULT).subscribe((result) => {
      console.log('Escaneo completado con éxito:', result);
      // Obtener el resultado usando el processId
      this.getOcrResult(this.processId);
      this.ocrid.close(); // Cerrar la instancia de OCRID
    });

    // Suscripción a eventos de error
    this.ocrid.events(EventType.ERROR).subscribe((error) => {
      console.error('Ocurrió un error durante el escaneo:', error);
    });

    // Iniciar el proceso de escaneo
    this.processId = await this.ocrid.startStream(this.videoContainer.nativeElement);
    console.log('Proceso OCR iniciado.');
  }

  async getOcrResult(processId: string): Promise<void> {
    try {
      // Método 1: Usando ResultHelper (recomendado)
      this.result = await ResultHelper.get(processId, Envs.PRE3);
      console.log('Resultado obtenido:', this.result);
      
      // Acceder a los campos específicos del resultado
      if (this.result?.success) {
        const documentTypes = this.result.value.types;
        const fields = this.result.value.fields;
        const images = this.result.value.images;
        
        console.log('Tipo de documento:', documentTypes);
        console.log('Campos extraídos:', fields);
        console.log('Imágenes:', images);
      }
      
      // Método 2: Usando llamada HTTP directa al endpoint
      // const url = `${Endpoints[Envs.PRE3]}result/${processId}`;
      // Utilizar HttpClient de Angular para la llamada
      // this.http.get(url).subscribe(data => {
      //   console.log('Resultado desde API:', data);
      // });
    } catch (error) {
      console.error('Error al obtener el resultado OCR:', error);
    }
  }

  ngOnDestroy(): void {
    // Liberar recursos y cerrar OCRID
    if (this.ocrid) {
      this.ocrid.close();
    }
  }
}

---

Recuperación y Procesamiento de Resultados

Una vez completado el proceso de escaneo, se obtendrá un processId que permite recuperar los resultados del análisis OCR. Existen dos formas principales de obtener estos resultados:

Método 1: Utilizando ResultHelper (Recomendado)

La biblioteca proporciona una clase ResultHelper que simplifica la obtención de resultados:

import { ResultHelper, Envs } from 'fw-ocrid';

async getOcrResult(processId: string): Promise<void> {
  try {
    // Obtener resultado usando el helper proporcionado por la biblioteca
    const resultado = await ResultHelper.get(processId, Envs.PRE3);
    console.log('Resultado obtenido:', resultado);
    
    // Procesar los datos según necesidades
    if (resultado?.success) {
      // Tipos de documento identificados
      const documentTypes = resultado.value.types;
      
      // Campos extraídos del documento
      const fields = resultado.value.fields;
      
      // Imágenes capturadas
      const images = resultado.value.images;
      
      // Validaciones realizadas
      const validations = resultado.value.validations;
    }
  } catch (error) {
    console.error('Error al obtener el resultado:', error);
  }
}

Método 2: Llamada HTTP Directa

Alternativamente, puede realizar una llamada HTTP directa al endpoint correspondiente:

import { HttpClient } from '@angular/common/http';
import { Endpoints, Envs } from 'fw-ocrid';

constructor(private http: HttpClient) {}

getOcrResultManual(processId: string): void {
  // Construir la URL utilizando los Endpoints predefinidos
  const url = `${Endpoints[Envs.PRE3]}result/${processId}`;
  
  // Realizar petición GET
  this.http.get<IResult>(url).subscribe({
    next: (resultado) => {
      console.log('Resultado obtenido:', resultado);
      // Procesar el resultado según necesidades
    },
    error: (error) => {
      console.error('Error al obtener el resultado:', error);
    }
  });
}

Estructura del Resultado

El resultado obtenido tiene la siguiente estructura:

interface IResult {
  id: string;              // ID del proceso
  startTimestamp: number;  // Timestamp de inicio
  endTimestamp: number;    // Timestamp de finalización
  success?: boolean;       // Indicador de éxito
  value?: {
    types: Array<{         // Tipos de documento identificados
      name: string;        // Nombre del tipo de documento
      year: number;        // Año del documento
      id: string;          // ID del tipo de documento
      probability: number; // Probabilidad de coincidencia
      country: string;     // País del documento
    }>;
    fields: Array<{        // Campos extraídos del documento
      name: string;        // Nombre del campo
      value: any;          // Valor extraído
    }>;
    authenticity: Array<{  // Validaciones de autenticidad
      name: string;
      value: any;
    }>;
    images: Array<{        // Imágenes capturadas
      name: string;
      value: any;          // Generalmente valor en base64
    }>;
    validations: Array<{   // Validaciones adicionales
      name: string;
      value: any;
    }>;
  };
}

Puntos Claves de la Implementación

1. Inicialización del Componente: Se crea una instancia de OcrId proporcionando los parámetros requeridos como la clave de API, el entorno de ejecución (Envs.PRE3) y el idioma ('en').

2. Suscripción a Eventos: El componente se suscribe a tres tipos principales de eventos:

   • Eventos de Retroalimentación del Usuario (USER_FEEDBACK): Indica acciones que el usuario debe realizar, como mostrar el frente o el reverso del documento.
   • Eventos de Resultados (RESULT): Señala el éxito del proceso de escaneo, entregando los datos obtenidos.
   • Eventos de Error (ERROR): Captura y maneja errores que ocurren durante el proceso.

3. Gestión de la Cámara:

   • Se utiliza el método startStream para iniciar el flujo de la cámara y capturar datos del documento.
   • El contenedor de video (videoContainer) se configura para mostrar la transmisión de la cámara en tiempo real.

4. Recuperación de Resultados:

   • Una vez completado el escaneo, se utiliza el processId para obtener los resultados del análisis OCR.
   • Se puede usar ResultHelper.get() o realizar una llamada directa al endpoint /result/{processId}.
   • Los resultados incluyen información detallada sobre el documento escaneado, incluyendo tipo, campos extraídos e imágenes.

5. Finalización del Proceso: Una vez completado el proceso de OCR, la instancia de OcrId se cierra mediante el método close para liberar los recursos utilizados.

6. Limpieza de Recursos: En el método ngOnDestroy, se asegura que todos los recursos relacionados con el proceso de OCR se liberen correctamente cuando el componente se destruya.

7. Manejo de Resultados y Errores:

   • Los resultados del escaneo se procesan según sea necesario para su visualización o almacenamiento.
   • Los errores se manejan y registran para proporcionar información de diagnóstico en caso de fallos.

8. Gestión de Licencia:

   • Inicialmente solicite a Finwave el acceso a las URLs que desean utilizar con el componente, indicando lo siguiente:
     1. Cuáles son URLs para producción.
     2. Cuáles son URLs para pruebas ó desarrollo.
   • Tras recibir la licencia puede usar el producto de forma correcta.
   • Para pruebas locales se le proveerá una licencia temporal. Puede trabajar en tres tipos de ambientes: producción (PRO3), pruebas (PRE3) y desarrollo (DEV3).
   • Para usar la licecia temporal añada el siguiente código en el navegador antes de utilizar el componente: window.regulaLicense = { license: "..." };

9. Demo Angular

Para probar el funcionamiento del programa OCR ID, se ha implementado una demo en Angular que proporciona una interfaz interactiva. Esto permite explorar las funcionalidades y el comportamiento de la biblioteca sin necesidad de integrarla previamente en su propia interfaz.

• Puede acceder a la demo en el siguiente enlace: Demo-Angular.

---