IDCheckIO SDK - ReactNative module

Getting started

Install from NPM

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

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

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.
   * @param theme - A theme to customize SDK colors.
   * @returns Void on success.
   * @throws An error of type {@link IDCheckioError} if the session fails.
   */
  export function startOnboarding(folderUid: string, theme: IDCheckTheme | null): 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.
   * @param theme - A theme to customize SDK colors.
   * @returns {@link IDCheckioResult}
   * @throws An error of type {@link IDCheckioError} if the capture fails.
   */
  export function start(parameters: IDCheckioParams, onlineContext: IDCheckioOnlineContext | null, theme: IDCheckTheme | null): 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).

You can also provide an IDCheckTheme to customize the colors of the sdk, check the associated section for more information.

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 () => {
  let theme = new IDCheckTheme({});
  startOnboarding(generateUUID(), theme).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 and an optional IDCheckTheme.

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 theme = new IDCheckTheme({});
  let params = new IDCheckioParamsBuilder().build();
  start(params, onlineContext, theme).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 }))
    .setOverrideWordings(new Map([
        // Label that will update the type of document wanted in the title of the presentation page.
        ['label', 'document'],
        // A quick description of the document you want your users to capture. Can be useful if the label is not clear by itself.
        ['description', 'Capture a document of your choice.'],
    ]))
    .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, ...)

IDCheckTheme

When starting a single capture or an onboarding, you can provide an IDCheckTheme to customize the colors of the session. The theme look like this :

export class IDCheckTheme {
  // Correspond to the primary color of the SDK, applied to buttons and images.
  public primaryColor?: string | null;
  // Correspond to the background color of all the presentation/informational views.
  public foregroundColor?: string | null;
  // Correspond to the color of the camera overlay.
  public backgroundColor?: string | null;
  // Correspond to the cropping mask border color.
  public borderColor?: string | null;
  // Not recommended to use it as by default the sdk will change the text color from white to black depending on the background it is on.
  public textColor?: string | null;
  // Not recommended to use it as by default the sdk will change the text color from white to black depending on the background it is on.
  public titleColor?: string | null;
}

You need to provide the name of color (name of the resources for Android and name of the ColorAssets or iOS). For example :

new IDCheckTheme({ primaryColor: "blue", foregroundColor: "white", backgroundColor: "white", borderColor: "blue" })