Migración a v3.x

Introducción

La versión 3.x de la biblioteca OCRID introduce actualizaciones significativas que mejoran la interacción del usuario, mejoran el manejo de errores y añaden soporte para configuraciones adicionales como ajustes de entorno y suscripciones a eventos. Esta guía te ayudará a migrar tu integración a la última versión.

---

Cambios Clave

1. Importación de la Biblioteca

• Anterior: La biblioteca se importaba como tm-ocrid.
• Nueva: La biblioteca ahora es fw-ocrid.

// Old
import { OcrId } from 'tm-ocrid';

// New
import { OcrId } from 'fw-ocrid';

Después de reemplazar `tm-ocrid` con `fw-ocrid`, asegúrate de instalar la nueva biblioteca.

```bash
npm install fw-ocrid --save

2. Configuración de Entorno

La nueva versión de la biblioteca permite configurar entornos explícitamente (DEV3, PRE3, PRO3) durante la instanciación.

También soporta parámetros opcionales adicionales como el idioma.

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

const ocrid = new OcrId('YOUR_API_KEY', Envs.PRE3, undefined, 'en');

3. Manejo Mejorado de Eventos

La versión 3.x introduce varios nuevos tipos de eventos que proporcionan un control más detallado del proceso de escaneo y permiten manejar mejor la retroalimentación del usuario. Suscribirse a los eventos adecuados es crucial para gestionar el flujo de manera efectiva.

Actualizaciones Clave en el Manejo de Eventos

• Nuevos eventos como EventType.CONNECTED y EventTypeUserFeedback.CAMERA_PROCESS_STARTED han sido introducidos para proporcionar mayor control y retroalimentación durante el proceso de escaneo.
• El evento USER_FEEDBACK incluye subtipos adicionales como PROCESS_FINISHED, que notifica cuando se ha completado todo el proceso.
• Importante: Asegúrate de suscribirte a los eventos requeridos antes de llamar a ocrid.startStream para garantizar un manejo adecuado y retroalimentación durante el proceso OCR.

Para una lista detallada de todos los eventos disponibles y cómo manejarlos, consulta la Documentación de Eventos.

---

4. Manejo de Errores

El proceso no se reinicia automáticamente ante errores específicos. Para manejar esto, necesitas reiniciar explícitamente el proceso usando el método ocrid.restart(). Además, asegúrate de gestionar este comportamiento utilizando las suscripciones a eventos adecuadas.

5. Target del Stream

El stream ahora está vinculado a un contenedor específico (elemento HTML), el cual debe pasarse explícitamente a startStream.

await ocrid.startStream(document.getElementById('video-container'));

Pasos de Migración para Javascript

Ejemplo Básico (Antes)

import { OcrId } from 'tm-ocrid';

const ocrid = new OcrId('YOUR_API_KEY');
await ocrid.openCamera().then((stream) => {
  return ocrid.startStream();
});
ocrid.close();

Ejemplo Básico (Después)

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

const ocrid = new OcrId('YOUR_API_KEY', Envs.PRE3, undefined, 'en');
await ocrid.startStream(document.getElementById('video-container'));
ocrid.close();

Ejemplo de Suscripción a Eventos (Antes)

ocrid.events(EventType.USER_FEEDBACK).subscribe((e) => {
  console.log(e);
});

Ejemplo de Suscripción a Eventos (Después)

ocrid.events(EventType.USER_FEEDBACK).subscribe((feedback) => {
  switch (feedback) {
    case EventTypeUserFeedback.SHOW_DOCUMENT_FRONT_SIDE:
      console.log('Show the front side of the document.');
      break;
    case EventTypeUserFeedback.SHOW_DOCUMENT_REVERSE_SIDE:
      console.log('Show the reverse side of the document.');
      break;
    case EventTypeUserFeedback.DOCUMENT_FRONT_SIDE_COMPLETED:
      console.log('Front side scanned successfully.');
      break;
    case EventTypeUserFeedback.PROCESS_FAILED_DUE_ANALYSIS_ERROR:
      console.log('Restart due to analysis error.');
      ocrid.restart()
      break;
    default:
      console.log(feedback);
  }
});

ocrid.events(EventType.RESULT).subscribe((result) => {
  console.log(result);
});

ocrid.events(EventType.ERROR).subscribe((error) => {
  console.error('Error:', error);
});

Pasos de Migración para Angular

Ejemplo Básico (Antes)

import {Component, OnInit, OnDestroy} from '@angular/core';
import { OcrId } from 'tm-ocrid';

@Component({
    selector: 'app',
    template: `<video [srcObject]="stream" autoplay playsinline>`
});
export class App implements OnInit, OnDestroy {
  stream;
  ocrid;

  async ngOnInit(): void {
    this.ocrid = new OcrId('YOUR_API_KEY');
    this.stream = await this.ocrid.openCamera();
    await this.ocrid.startStream();
  }

  ngOnDestroy(): void {
    this.ocrid.close();
  }
}

Ejemplo Básico (Después)

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

@Component({
  selector: 'app',
  template: `<div #videoContainer></div>`
})
export class App implements OnInit, OnDestroy {
  @ViewChild('videoContainer', { static: false }) videoContainer: any;
  private ocrid: OcrId;

  async ngOnInit(): void {
    this.ocrid = new OcrId('YOUR_API_KEY', Envs.PRE3, undefined, 'en');
    this.ocrid.events(EventType.USER_FEEDBACK).subscribe((feedback) => {
      console.log('User Feedback:', feedback);
    });
    await this.ocrid.startStream(this.videoContainer.nativeElement);
  }

  ngOnDestroy(): void {
    this.ocrid.close();
  }
}

Lista de Verificación para la Migración

• Actualizar Importación de Biblioteca:

  • Reemplazar tm-ocrid con fw-ocrid.
  • Ejecutar el comando correspondiente para instalar la nueva biblioteca.

    npm install fw-ocrid --save

• Configurar Entorno:

  • Usar Envs para establecer el entorno correcto (DEV3, PRE3 o PRO3).

• Suscribirse a Nuevos Eventos:

  • Manejar PROCESS_FAILED_DUE_ANALYSIS_ERROR y otros nuevos tipos de eventos.

• Pasar un Contenedor a startStream:

  • Asegurarse de que el método startStream apunte a un elemento HTML válido.

• Probar Exhaustivamente:

  • Validar la integración contra todas las interacciones del usuario y casos extremos.

---