React Integration

Learn how to integrate the fw-ocrid library into your React project by creating a reusable component for OCR functionality, step by step.

---

Basic Implementation

import React, { useEffect, useRef } from 'react';
import { OcrId, Envs, EventType, EventTypeUserFeedback, FeedbackEvent, ResultEvent, ErrorEvent } from 'fw-ocrid';

const OcrComponent: React.FC = () => {
  const videoRef = useRef<HTMLDivElement | null>(null);

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

    // Handle user feedback events
    ocrid.events(EventType.USER_FEEDBACK).subscribe((feedback: FeedbackEvent) => {
      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.error('Process failed due to an analysis error.');
          break;
        case EventTypeUserFeedback.PROCESS_FINISHED:
          console.log('Scanning process completed.');
          break;
        default:
          console.log('Feedback:', feedback);
      }
    });

    // Handle result events
    ocrid.events(EventType.RESULT).subscribe((result: ResultEvent) => {
      console.log('Scan completed:', result);
      ocrid.close(); // Close the process
    });

    // Handle error events
    ocrid.events(EventType.ERROR).subscribe((error: ErrorEvent) => {
      console.error('An error occurred:', error);
    });

    // Start the camera stream
    const startStream = async () => {
      try {
        if (videoRef.current) {
          await ocrid.startStream(videoRef.current);
          console.log('Camera stream started.');
        } else {
          console.error('Video element reference is null.');
        }
      } catch (error) {
        console.error('Error starting camera stream:', error);
      }
    };

    startStream();

    return () => {
      ocrid.close();
    };
  }, []);

  return (
    <div style={{ width: '600px', height: '100%' }}>
      <div ref={videoRef} style={{ width: '100%', height: 'auto' }} />
    </div>
  );
};

export default OcrComponent;

---

Using the Component

Integrate the OcrComponent into your React application:

import React from 'react';
import ReactDOM from 'react-dom';
import OcrComponent from './OcrComponent';

const App: React.FC = () => (
  <div>
    <h1>OCR Integration Example</h1>
    <OcrComponent />
  </div>
);

ReactDOM.render(<App />, document.getElementById('root'));

---

Implementation Keys

1. OCR Initialization: Create an instance of OcrId with your API key, environment (Envs.PRE3), and desired language.

2. Camera Container: Use a div element with a reference (ref) that will be passed to the startStream method to render the camera. The library will handle creating and managing the video element inside this container.

3. Event Handling:

   • User Feedback Events: Guide the user to show document sides or notify about scanning progress.
   • Result Events: Provide scanned data when the process is completed.
   • Error Events: Capture errors during the process to handle them appropriately.

4. Camera Stream Management:

   • Use the startStream method with the referenced div element to start the camera stream.
   • Make sure to close the OCR instance using close to release resources once the process has finished.

5. Development Environment Optimizations:

   • In React Strict Mode, effects run twice in development.
   • Use an isInitialized state to prevent multiple camera initializations.
   • Store the OCR instance in a reference to ensure proper cleanup.

6. License Managment:

   • Initially, request access from Finwave to the URLs you want to use with the component, specifying the following:
     1. Which URLs are intended for production.
     2. Which URLs are intended for testing or development.
   • Once you receive the license, you can use the product properly.
   • For local testing, a temporary license will be provided. You can work in three types of environments: production (PRO3), testing (PRE3), and development (DEV3).
   • To use the temporary license, add the following code in your browser before using the component: window.regulaLicense = { license: "..." };

7. React Demo

   To test the functionality of the OCR ID program, a demo has been implemented in React that provides an interactive interface. This allows users to explore the features and behavior of the library without the need to integrate it into their own interface.

   • You can access the demo at the following link: React-Demo.