IDCheckIO SDK - ReactNative module

Getting started

Install from NPM

// with npm
npm install @idnow/react-idcheckio

// with yarn
yarn add @idnow/react-idcheckio

You need to add this into your app.json to link the plugin IDCheckIO.

{
  "expo": {
    "plugins": [
      [
        "@idnow/react-idcheckio",
        {
          "version": "9.1.0"
        }
      ]
    ]
  }
}

Usage

You will have access to four methods to communicate with the sdk.

  /**
   * Preload the native models of the sdk.
   *
   * @param extractData - A boolean indicating whether to use extract data. True by default.
   * @returns Void on success.
   */
  export function preload(extractData: boolean): void;

  /**
   * Activates the sdk with the given token.
   *
   * @param token - The token string used for activation.
   * @param extractData - A boolean indicating whether to use extract data. True by default.
   * @returns Void on success.
   * @throws An error of type {@link IDCheckioError} if the activation fails.
   */
  export function activate(token: string, extractData: boolean): Promise<void>;

  /**
   * Start an onboarding session with the given folder uid.
   *
   * @param folderUid - The folder that will be used to run the session.
   * @returns Void on success.
   * @throws An error of type {@link IDCheckioError} if the session fails.
   */
  export function startOnboarding(folderUid: string): Promise<void>;

  /**
   * Start the capture of one document with the given parameters.
   *
   * @param parameters - The parameters to configure the capture session.
   * @param onlineContext - Online context. Let it null and the first capture and send the one you receive on result to chain to capture.
   * @returns {@link IDCheckioResult}
   * @throws An error of type {@link IDCheckioError} if the capture fails.
   */
  export function startSession(onlineContext: IDCheckioOnlineContext | null, parameters: IDCheckioParams): Promise<IDCheckioResult>;

Preload

The preload is completely optional and will preload the embedded model of the sdk, this way the activate will be faster afterwards. You don't to wait for a result, there is no result expected.

import { preload } from '@idnow/react-idcheckio';

const preloadSdk = preload(true);

Activate

The activate is a mandatory call that need to be done once before starting any session. The token is unique and will be provided by our CS team, contact them at [email protected] if needed. On a success, no result is expected, on error you will receive an IDCheckioError, check the error section for more information.

import { activate } from '@idnow/react-idcheckio';

const activateSdk = async () => {
   activate('YOUR_ACTIVATION_TOKEN', true).then(
    () => {
      setIsSdkActivated(true);
    },
    (error) => {
      handleError(error.message);
    }
  );
};

Start an onboarding (recommended)

The onboarding mode is the recommended mode to start the sdk as it simplify a lot the integration and improve the UX. To start it you need to call the startOnboarding with a CIS folderUid, if the folder already exists, every captured document will be pushed into it. And if the folderUid does not exist it will be created.

All the parameters of the onboarding are on the server you don't have to set any parameter on your side. (To check what is configurable, look at the official documentation or contact your dedicated CSM).

No result is expected, you will also receive an IDCheckioError if something happens during the session.

import { startOnboarding } from '@idnow/react-idcheckio';

const startCapture = async () => {
  startOnboarding(generateUUID()).then(
    () => {
      Alert.alert('Success', 'Onboarding ended successfully.');
    },
    (error) => {
      handleError(error.message);
    }
  );
};

Start a capture session

The start mode is a single capture of a document that can be configured directly in the code. To perform a full onboarding, you must manage the flow of multiple documents yourself by calling start as many times as you have documents to capture.

To start it, you need to call the start with an IDCheckioParams object containing all the parameters you have set for this capture, an optional IDCheckioOnlineContext.

The result is an IDCheckioResult that will only contain an IDCheckioOnlineContext. I will explain more about this IDCheckioOnlineContext in the dedicated section. Like others calls, you will also receive an IDCheckioError if something happens during the session.

import { useState } from 'react';
import { start } from '@idnow/react-idcheckio';

const [onlineContext, setOnlineContext] = useState<IDCheckioOnlineContext | null>(null);

const startCapture = async () => {
  let params = new IDCheckioParamsBuilder().build();
  startSession(onlineContext, params).then(
    (result) => {
      setOnlineContext(result.onlineContext);
      Alert.alert('Success', 'Capture ended successfully.');
    },
    (error) => {
      handleError(error.message);
    }
  );
};

Recommended parameters for each document type

Here is a list of the best practice we recommend for each document.

const id = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.ID)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .setIntegrityCheck(new IntegrityCheck({ readEmrtd: false, docLiveness: false }))
    .setOnlineConfig(new OnlineConfig({ isReferenceDocument: true }))
    .build()

const liveness = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.LIVENESS)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .setConfirmAbort(true)
    .build()

const frenchHealthCard = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.FRENCH_HEALTH_CARD)
    .setConfirmationType(ConfirmationType.DATA_OR_PICTURE)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .build()

const selfie = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.SELFIE)
    .setConfirmationType(ConfirmationType.DATA_OR_PICTURE)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .build()

const addressProof = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.A4)
    .setConfirmationType(ConfirmationType.DATA_OR_PICTURE)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .setUseHd(true)
    .setOnlineConfig(new OnlineConfig({ cisType: CISType.ADDRESS_PROOF }))
    .build()

const vehicleRegistration = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.VEHICLE_REGISTRATION)
    .setConfirmationType(ConfirmationType.DATA_OR_PICTURE)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .setSideOneExtraction(new Extraction(Codeline.VALID, FaceDetection.DISABLED))
    .build()

const iban = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.PHOTO)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .setCaptureMode(CaptureMode.PROMPT)
    .setOnlineConfig(new OnlineConfig({ cisType: CISType.IBAN }))
    .build()

const attachment = new IDCheckioParamsBuilder()
    .setDocType(DocumentType.PHOTO)
    .setConfirmationType(ConfirmationType.DATA_OR_PICTURE)
    .setOrientation(IDCheckioOrientation.PORTRAIT)
    .setUseHd(true)
    .setAdjustCrop(true)
    .setOnlineConfig(new OnlineConfig({ cisType: CISType.OTHER }))
    .build()

IDCheckioOnlineContext

The IDCheckioOnlineContext is an object that will be used by the sdk to chain the capture in a none onboarding mode. In the first capture, you can set it to null and for the other captures you need to retrieve the IDCheckioOnlineContext from the latest IDCheckioResult and set it to the next call of the start method.

IDCheckioResult

The IDCheckioResult is only used in response of a start to retrieve the IDCheckioOnlineContext.

export type IDCheckioResult = {
  onlineContext: IDCheckioOnlineContext;
};

IDCheckioError

Here is the content of an error, you will find this object in the message of the error you will receive.

export type IDCheckioError = {
  cause: IDCheckioErrorCause;
  details: string;
  subCause?: IDCheckioSubCause | undefined;
  message?: string | undefined;
};

export type IDCheckioErrorCause =
  | 'CUSTOMER_ERROR'
  | 'NETWORK_ERROR'
  | 'USER_ERROR'
  | 'INTERNAL_ERROR'
  | 'DEVICE_ERROR'
  | 'DOCUMENT_ERROR';

export type IDCheckioSubCause =
  | 'MISSING_PERMISSIONS'
  | 'CANCELLED_BY_USER'
  | 'MODEL_REJECTED'
  | 'ANALYSIS_EXPIRED_DOC'
  | 'PVID_NOT_ELIGIBLE'
  | 'UNIDENTIFIED'
  | 'DOC_NOT_USABLE_FACEREC'
  | 'UNSUPPORTED_FILE_EXTENSION';

Two possibilities here, the easier is to handle the IDCheckioErrorCause and show generic errors for all or each cause.

If you want to go deeper, you can also handle the IDCheckioSubCause, those are mainly that the user did something wrong, and we had to stop the session after X retries. You can if you want handle those and show some specific messages for each or for the ones you want. (For example if the user refuses the permission, you can tell him that it is mandatory to create an account, ...)