Migrating to v3.x

Introduction

The 3.x version of the OCRID library introduces significant updates that enhance user interaction, improve error handling, and add support for additional configurations such as environment settings and event subscriptions. This guide will help you migrate your integration to the latest version.

---

Key Changes

1. Library Import

• Previous: The library was imported as tm-ocrid.
• New: The library is now fw-ocrid.

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

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

After replacing tm-ocrid with fw-ocrid, make sure to install the new library:

npm install fw-ocrid --save

2. Environment Configuration

The new library version allows setting environments explicitly (DEV3, PRE3, PRO3) during instantiation.

It also supports additional optional parameters like language.

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

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

3. Enhanced Event Handling

The 3.x version introduces several new event types that provide more granular control over the scanning process and allow for better user feedback handling. Subscribing to the right events is crucial for managing the flow effectively.

Key Updates in Event Handling

• New events like EventType.CONNECTED and EventTypeUserFeedback.CAMERA_PROCESS_STARTED have been introduced to provide greater control and feedback during the scanning process.
• The USER_FEEDBACK event includes additional subtypes like PROCESS_FINISHED, which notifies when the entire process is completed.
• Important: Make sure to subscribe to the required events before calling ocrid.startStream to ensure proper handling and feedback during the OCR process.

4. Error Handling

The process does not restart automatically upon specific errors. To handle this, you need to explicitly restart the process using the ocrid.restart() method. Additionally, ensure you manage this behavior using the appropriate event subscriptions.

5. Stream Target

The stream is now tied to a specific container (HTML element), which must be passed explicitly to startStream.

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

Migration Steps for Javascript

Basic Example (Before)

import { OcrId } from 'tm-ocrid';

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

Basic Example (After)

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

Event Subscription Example (Before)

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

Event Subscription Example (After)

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

Migration Steps for Angular

Basic Example (Before)

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

@Component({
    selector: 'app',
  template: `<div #videoContainer></div>`
});
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();
  }
}

Basic Example (After)

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

Migration Checklist

• Update Library Import:

  • Replace tm-ocrid with fw-ocrid.
  • Run the following command to install the new library:

    npm install fw-ocrid --save

• Configure Environment:

  • Use Envs to set the correct environment (DEV3, PRE3, or PRO3).

• Subscribe to New Events:

  • Handle PROCESS_FAILED_DUE_ANALYSIS_ERROR and other new event types.

• Pass a Container to startStream:

  • Ensure the startStream method targets a valid HTML element.

• Test Thoroughly:

  • Validate the integration against all user interactions and edge cases.