readid-react-native v4.112.0

ReadID React Native Module

Table of contents

• Introduction
• Requirements
• Limitations and Known Issues
• Repository Contents
• Installation
  • Android
    • Add ReadID SDK and Configure Build
    • Android Environment Setup
  • iOS
• Client-server vs client-only
• Getting Started
• Sample code
• Features
  • Flows
  • Screens
    • Document selection screen
    • Instruction animations screens
    • Manual input screen
    • VIZ confirmation screen
    • VIZ result screen
    • NFC reading screen
    • NFC result screen
  • Configuration
    • Configuration options available for all flows
    • Configuration options available for all VIZ flows
    • Configuration options available for all NFC flows
    • VIZOnlyOnePageFlow configuration options
    • NFCOnlyFlow configuration options
    • NFCWithAccessControlFlow configuration options
  • Document and device NFC location
  • iProov
  • Optical Orchestration
    • Overview
    • Technical implementation details
• ReadID React Native Module Data Model Documentation
  • Flow Objects
    • Not available at this current time for NFC/VIZ
    • (Abstract) Flow
    • VIZOnlyOnePageFlow
    • NFCWithAccessControlFlow
    • NFCOnlyFlow
  • Result Objects
    • ReadIDResult
    • (Abstract) BaseResult
    • NFCResult extends BaseResult
    • VIZResult
    • ReadIDSession
• License
• Help and support
• Glossary

Introduction

The ReadID React Native Module wraps ReadID's native iOS (Swift) and Android (Kotlin) UI SDKs behind a TypeScript interface for use from within your React Native app. The module requires that your app uses Expo.

This is a beta release, some features might be unstable.

Requirements

• node.js
• TypeScript
• Watchman
• Expo
• Android API Level 24 (Android 7) and above.
• Android Studio or Visual Studio (latest version recommended)
• xCode (latest version recommended)
• iOS 14 and above.
• A valid ReadID Access Key and URL.

Refer to the native Android and iOS tech guides on the Documentation portal for platform specific requirements.

Limitations and Known Issues

A subset of the native SDK API is not available in the React Native Module due to technical limitations. This includes:

• All Flow configuration properties have a setter but no getter, i.e. you can configure all settings but you cannot query configuration settings.
• vizConfirmationScreenConfiguration, vizResultScreenConfiguration, and isTouchToFocusEnabled (Android only) are not available

Repository Contents

• README.md - This document.
• example - A demonstration React Native app using this React Native Module.
• src - Contains the implementation code, such as TypeScript files, native bridge code, and platform-specific logic.
• android - Android native side of the native module.
• ios - iOS native side of the native module.

Installation

You can install this package by running the following command in your React Native project: npm install readid-react-native

Android

Add ReadID SDK and Configure Build

1. Add repositories to your build.gradle (root scope):

allprojects {
    repositories {
        google()
        maven {
            url "s3://maven-readid-7npn738r9muhb5r6mm97b7pxcck84euw1a-s3alias"
            authentication { awsIm(AwsImAuthentication) }
        }
    }
}

2. Configure AWS credentials. Create ~/.aws/credentials with contents:

[default]
aws_access_key_id=<your_key_id>
aws_secret_access_key=<your_access_key>

Do not add a newline after aws_secret_access_key. The aws_access_key_id and aws_secret_access_key are provided to you by Inverid.

3. Set Java compatibility to Java 8 in your build.gradle:

android {
    compileOptions {
        // Sets Java compatibility to Java 8
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

4. Add AndroidX properties to your gradle.properties (project root). Create if it does not exist:

android.useAndroidX=true

5. Make sure enableJetifier is false on gradle.properties

android.enableJetifier=false

6. Add required features for NFC: Add the nfc feature to your AndroidManifest.xml

<uses-feature
  android:name="android.hardware.nfc"
  android:required="true"/>

7. Optional: add required features for VIZ: Add camera and autofocus features to your AndroidManifest.xml. As an alternative, you can perform runtime checks before starting ReadID, in case you want to support devices without camera or without auto focus.

<manifest>
...
  <uses-feature
    android:name="android.hardware.camera"
    android:required="true"/>
  <uses-feature
    android:name="android.hardware.camera.autofocus"
    android:required="true"/>
</manifest>

If you start any NFC flow and the device does not have NFC support, then the native module will throw an NFCNotSupportedException. You should perform runtime checks before starting ReadID and handle the NFCNotSupportedException. The exception here is that if you make use of the NFCWithVIZFallbackFlow, then the native module will perform the check, and will fall back to a second VIZ capture if the device does not support NFC.

Finally, do not forget to set the Android minSdkVersion to at least 24

Android Environment Setup

Add following statements to your shell path:

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

Optionally:

export ANDROID_BUILD_TOOLS=~/Library/Android/sdk/build-tools/<latest_version>
export ANDROID_PLATFORM_TOOLS=~/Library/Android/sdk/platform-tools
export ANDROID_TOOLS=~/Library/Android/sdk/cmdline-tools/latest/bin
export ANDROID_EMULATOR=~/Library/Android/sdk/emulator

Then load your changes in the path with src ~/.zshrc for example, or whatever your shell environment is.

iOS

You can use the sample code to get started quickly or you can integrate the SDK into your own app as follows:

1. Add ReadID frameworks: To integrate the ReadID SDK, which consists of two frameworks: ReadID_UI.xcframework, and ReadID_Interop.xcframework, please consult your onboarding specialist for access to these files. To initiate the ReadID flow, copy the two .xcframework files into your React Native ios folder and then add them to your iOS project. Open the project in Xcode, select your main target, navigate to General -> Frameworks, Libraries, and Embedded Content, and drag the frameworks into this section. Make sure the Embed & Sign option is selected for each framework.

2. Change the Podfile to add the following to the post_installer do |installer| code block:

   installer.pods_project.targets.each do |target|
       if target.name == 'ReadidReactNative'
         xcframeworks_paths = ['../ReadID_Interop.xcframework', '../ReadID_UI.xcframework']
         xcframeworks_group = installer.pods_project.main_group.find_subpath('Frameworks', true)
         xcframeworks_paths.each do |path|
           file_ref = xcframeworks_group.new_file(path)
           target.frameworks_build_phase.add_file_reference(file_ref, true)
         end
     end
   end

3. In the Signing & Capabilities tab of your app target, click the + Capability button and add the Near Field Communication Tag Reading capability.

4. Add NSCameraUsageDescription to the App's Info.plist file. The camera is needed to scan the document, including the MRZ.

5. Add NFCReaderUsageDescription to the App's Info.plist. For example,

   <key>NFCReaderUsageDescription</key>
   <string>Read an electronic passport or drivers license</string>
   <key>NSCameraUsageDescription</key>
   <string>We need access to the camera to capture the document before reading the NFC chip</string>

6. On the Apple developer portal create a distribution provisioning profile and enable capability NFC Tag Reading.
7. To enable specific NFC functionalities in your application, copy the following snippet into your Info.plist. This declares the list of application identifiers that are supported by your app. For more information, refer to the Core NFC documentation. Apple requires you to explicitly declare these identifiers to access the NFC chip's functions. To specify them, add the com.apple.developer.nfc.readersession.iso7816.select-identifiers key in your Info.plist, as shown below:

   <key>com.apple.developer.nfc.readersession.iso7816.select-
   identifiers</key>
   <array>
   <string>A0000002471001</string>
   <string>A00000045645444C2D3031</string>
   </array>

Client-server vs client-only

In most situations, the ReadID client-server SDK is the most suitable solution, and is the default flavor for the React Native Module. If you need to use the client-only solution this can be accomplished in iOS simply by adding the correct version of the xcframework. For Android, in your app's build gradle you need to add the following line:

gradle.ext.readIDFlavor = 'clientOnly'

Getting Started

To use the SDK, you must obtain credentials first. You can obtain your AccessKey and URL by contacting your onboarding specialist.

Once you have a valid token, obtained via Credentials, you can start to setup a flow (for example an NFCWithAccessControlFlow or VIZOnlyOnePageFlow). With your newly created flow, you can start using the ReadID native module.

The most simplest form is the following:

const flow: NFCWithAccessControlFlow = {
      baseUrl: 'Your URL',
      accessKey: 'Your access key',
      allowedDocumentTypes: [DocumentType.passport, DocumentType.identityCardTD1],
    }
ReadID.startNFCWithAccessControlFlow(flow).then(
      (result) => {
      console.log(result);
        // handle result
      },
      (error) => {
        // handle error
      }
    );

This will start the ReadID and will allow your users to verify themselves using a passport or an identity card. The readIDResult will contain information about the session the user just performed. Depending on the flow that was selected, it's possible to retrieve the users name, photo image, and more.

For instance, if the user scanned their identity document using NFC, you can retrieve their face image in the following way:

let faceImage = readIDResult?.nfcResult?.faceImage

The faceImage is returned as a string, which you can display using the Image component in React Native.

Sample code

For a simple ReadID experience that is ready to run out-of-the-box, check out the React Native example project. Note that ReadID is not supported on an iOS or Android simulator, you have to run it on a physical device. Before you can run the example app, run npm install in the example folder. Afterwards, be sure you include the frameworks for iOS and Android as described in their installation chapters.

In the example app folder, open the Body.tsx file in components folder. Here you will see where and how to add your base URL and access key.

export const Environment = {
  baseURL: "your_base_url",
  accessKey: "your_access_key"
}

NOTE: Never commit or store your AccessKey or URL in publicly accessible code. Always use secure methods to store and retrieve these credentials in production environments.

Features

Flows

The UI SDK supports several different Flows that determine how and what you want to capture or read from the document. The following flows exist:

• NFCWithAccessControlFlow iOS | Android: This flow is optimized for reading the document's NFC chip. It will attempt scan the document's MRZ page for access control information, and will also provide the option to enter the access control key manually. Once it has obtained the access control key it will proceed to read the document. This flow may or may not return a usable VIZ capture of the document. Note that if you require the personal number when using this flow, it can result in lower VIZ capture performance, because the flow may have to capture a QR code too. See Flow.shouldRequirePersonalNumber below.

• VIZOnlyOnePageFlow iOS | Android: Captures a single configured page type. You can "chain" this flow with another VIZOnlyOnePageFlow and/or NFCOnlyFlow in order to achieve the most flexibility w.r.t. UX/UI, such as presenting your own instructions, animations, and/or feedback screens.

• NFCOnlyFlow iOS | Android: Only read the identity document's NFC chip. This flow can be combined with the VIZOnlyOnePageFlow in order to implement custom business logic in between and around these flows. It is typically used when none of the other flows sufficiently matches your use case. It can also be used without the ReadID UI VIZ SDK entirely.

The VIZ SDK will attempt to scan only the requested page or document type(s), as specified via VIZOnlyOnePageFlow.allowedPageTypes or .allowedDocumentTypes for the other flows, but we cannot guarantee that the result is of the requested type. The more distinctive features a page has, the higher the chance that the SDK captures the correct page type, and vice versa, but there is always the possibility of a wrong page type. If you rely on the VIZ capture result to be accurate then you must verify the page capture results via some other means. We recommend to always use NFC reading, if possible, and rely on those results instead.

Screens

The Flow that you choose to use also defines the screens that the SDK should present to the user, their order, and the possible transitions between those screens. The following screens exist:

1. Document selection screen
2. Instruction animation screen
3. VIZ capture screen
4. Manual input screen
5. VIZ confirmation screen
6. VIZ result screen
7. NFC instruction animation screen
8. NFC reading screen
9. NFC result screen

All screens except the VIZ capture screen and NFC reading screen are optional:

• The document selection screen can be shown or disabled by setting the Flow property shouldShowDocumentSelection and is described in section Document selection screen below.

• The option to enter NFC access control data manually on the manual input screen is only available in NFCWithAccessControlFlow. That flow is intended to capture an NFC access control key, and is optimized towards that goal at the expense of the quality of the VIZ image and features.

• To disable the VIZ result screen, set Flow property shouldShowVIZResult to false.

• The manual access key input screen will only be shown during the NFCWithAccessControlFlow, if the SDK detects a wrong NFC access key. This is extracted from the MRZ.

• You can skip the NFC result screen by setting NFCWithAccessControlFlow property shouldShowNFCResult to false. It is shown by default.

Document selection screen

The ReadID UI SDK can optionally show a document selection screen that allows users to choose the type of document to scan. Depending on the flow configuration, ReadID UI SDK can display specific instruction animations and a VIZ capture screen screen tailored to that document type.

This screen is disabled by default. Enable it by setting the Flow property shouldShowDocumentSelection to true.

You can configure the document types that the user can choose for the VIZOnlyOnePageFlow with VIZOnlyOnePageFlow.allowedPageTypes. For other flows with Flow.allowedDocumentTypes. The following buttons can be shown (with their MRZ format)

• Passport for ICAO compliant passports (2x44 characters)
• Identity card for ICAO TD1 (3x30 characters) and ICAO TD2 (2x36 characters) compliant identity cards
• Driving licence for EU driving licences (1x30 characters) and non-EU compliant driving licences without MRZ
• Visa for ICAO compliant visas (2x36 and 2x44 characters)
• French identity card for ICAO TD1 compliant identity cards (3x30 characters) and CNIS (French identity cards; 2x36 characters)

Manual input screen

The manual input screen provides a fallback for users for when VIZ capture is unable to scan the MRZ. It allows users to manually input the fields necessary to compute the access key. This screen is only available in NFCWithAccessControlFlow, for ICAO compliant identity documents and for electronic driving licences.

VIZ confirmation screen

The VIZ confirmation screen is shown immediately after the capture of a single page of a document. It provides the user with the option to review the capture, and to repeat the scan of the same page after discarding the result, or to keep the scan and proceed to the next step. This option can be enabled or disabled using shouldShowVIZConfirmation.

Note that the VIZ confirmation screen is never shown when manual input was provided.

NFC reading screen

The NFC reading screen shows the progress of the reading process and includes an instruction carousel with helpful tips for the document type being read. Initially, the instruction carousel is displayed when the user navigates to this screen. Upon clicking the Start Reading button (iOS) or when a supported NFC chip is detected (Android), the screen transitions to show the reading progress. If the reading process fails due to an incorrect access key, the SDK will either prompt the user to verify the access information via a manual input screen or automatically restart the reading process. For the ReadID UI VIZ variant, the manual input screen is available only in the NFCWithAccessControlFlow flow. If the failure is caused by another issue, such as a lost connection, the screen displays an error and allows the user to retry. If NFC reading completes with an access control error and manual input is disabled or unsupported, the SDK returns to the VIZ capture screen. If the ReadID UI VIZ SDK is not in use, the SDK returns control with an NFC access control error.

NFC result screen

The ReadID UI NFC result screen shows chip data and validation results. It is shown by default and can be disabled by setting shouldShowNFCResult: false.

Configuration

This section gives an overview of the configuration options when using the ReadID UI NFC SDK for use with ReadID UI VIZ, for each of the supported flows. For more details and default values read the apidocs delivered with the ReadID UI SDK package.

Be aware that not all identity documents are the same and that ReadID UI NFC will attempt to choose the best configuration regarding access control (BAC or PACE), speed of NFC reading, and user guidance (e.g. how to align the user's device with the document) based on information that is passed from ReadID UI VIZ. If you do not use ReadID UI VIZ (NFCOnlyFlow only), you'll need to provide an instance of NFCAccessKey, as it is required for access control. You should also provide a DocumentInfo object, to give ReadID UI NFC enough information to choose the best NFC configuration.

The SDK will attempt to scan only the requested document type(s), as specified via Flow.allowedDocumentTypes, but we cannot guarantee that the result is of the requested type. The more distinctive features a page has, the higher the chance that the SDK captures the correct page type, and vice versa, but there is always the possibility of a wrong page type. If you rely on the VIZ capture result to be accurate then you must verify the page capture results via some other means.

If you attempt to capture both drivingLicence and euDrivingLicence (or the front of said documents), then VIZ capture will always attempt to scan a EU driving licence containing an MRZ first, to maximize the chances of detecting a document that contains a chip. This may reduce capture speed when the user attempts to scan a driving license without an MRZ.

Configuration options available for all flows

• Flow.baseURL: Sets the base URL of the target ReadID server or reverse proxy. If you change the base URL, you must override the pinning certificates with the (CA) certificate of the used server.
• Flow.accessKey: Sets the ReadID access key for server authentication.
• Flow.opaqueID: This customer-provided identifier can be used to cross-reference a ReadIDSession to an app session identifier.
• Flow.shouldUsePinning: Enables/disables SSL pinning. Should only be set to false for debug purposes.
• Flow.readIDSession: Sets a ReadIDSession. The ReadIDSession is optional and only needs to be set if a previous session should be reused. Note: A ReadIDSession can only be committed once to the server. To prevent a session commit use the following configuration.
• Flow.preventSessionCommit: Sets whether a session commit should be prevented. This is useful if you want to reuse a ReadIDSession, for example if you want to capture both VIZ images, but also interact with your app between.
• Flow.shouldMaskPersonalData: Enables/disables replacing personal data (document number and optional data) with * characters.
• Flow.shouldAllowScreenshots (Android only): If allow screenshots is enabled, it is possible to make screenshots and screen recordings on the screens of the library, and it is possible to see content in the OS recent apps list.
• Flow.dateFormat: Sets the date format in the manual input screen.
• Flow.dateSeparator: Sets the date separator in the manual input screen.
• Flow.language: Sets the language to the given language value. Default or if null is applied, the device language will be used, if supported. Fallback is English.

Configuration options available for all VIZ flows

• Flow.shouldShowVIZConfirmation: Sets whether a VIZ confirmation screen should be shown, where the user can check and confirm the VIZ image quality.
• Flow.vizResultMode: Defines which fields are shown on the VIZ result screen.
• Flow.shouldShowVIZResult: Defines if to show VIZ result screen.
• Flow.shouldShowVIZPerformanceResult: Sets whether the VIZ performance result should be shown. If enabled a "Performance" tab is shown on the VIZ result screen. This is useful for debug purposes.
• Flow.shouldShowMRZFieldImages: Sets show MRZ field images enabled/disabled.
• Flow.shouldShowMRZText: Sets show MRZ text enabled/disabled.
• Flow.shouldShowMRZImage: Sets show MRZ image enabled/disabled.
• Flow.shouldShowVIZImages: Sets show VIZ images enabled/disabled.

Configuration options available for all NFC flows

• Flow.shouldShowNFCResult: Sets whether to show the NFC Result screen.
• Flow.shouldReadImages: Sets whether images should be read from the NFC chip.
• Flow.shouldShowFaceImage: Sets whether the face image should be shown.
• Flow.shouldShowVerificationResult: Sets whether the verification result should be shown.
• Flow.shouldShowSecurityResult: Sets whether the security result should be shown.
• Flow.allowSkipReadingAfterAttempts: Shows a skip-button on the NFC reading screen after a specified number of attempts.
• Flow.cscaMasterLists: Not available in React Native.
• Flow.applicationLevelEncryptionPins: Array of certificate pins for application-level encryption. Pins can be obtained via the ReadID management portal. Each pin must be specified as a base64-encoded sha256 hash of the SubjectPublicKeyInfo. By default, certificate pinning for application-level encryption is disabled.

VIZOnlyOnePageFlow configuration options

• VIZOnlyOnePageFlow.allowedPageTypes: Sets the allowed page types. We recommend to allow only one page type, because allowing multiple page types will reduce the performance.
• VIZOnlyOnePageFlow.manualCaptureAllowedAfterTimeout: Sets after how many milliseconds a manual capture button should be shown. A negative value will never show the button.
• VIZOnlyOnePageFlow.mrzFeatureRequirement: Sets the MRZ feature requirement.
• VIZOnlyOnePageFlow.faceImageFeatureRequirement: Sets the face image feature requirement.
• VIZOnlyOnePageFlow.shouldRequireSharpImage: Sets whether a sharp image is required.
• VIZOnlyOnePageFlow.shouldRequireNoGlareOnDocument: Sets whether no glare on document is required.
• VIZOnlyOnePageFlow.shouldRequireNoFingerOnDocument: Sets whether no finger on document is required.
• VIZOnlyOnePageFlow.shouldAllowLoweringQualityRequirements: Sets whether it is allowed to lower the above 3 quality requirements in time.
• VIZOnlyOnePageFlow.qrCodeFeatureRequirement: Sets the QR code feature requirement.

The SDK will attempt to scan only the requested page type(s), as specified via VIZOnlyOnePageFlow.allowedPageTypes, but we cannot guarantee that the result is of the requested type. The more distinctive features a page has, the higher the chance that the SDK captures the correct page type, and vice versa, but there is always the possibility of a wrong page type. If you rely on the VIZ capture result to be accurate then you must verify the page capture results via some other means. We recommend to always use NFC reading, if possible, and rely on those results instead.

NFCOnlyFlow configuration options

NFCOnlyFlow supports all common configuration options, plus the following:

NFCOnlyFlow.preventChipSupportDialog: Sets whether chip support warning dialogs should be prevented. This is useful when the chip support was already checked by the app before starting the NFC flow and the app allows to try to read the NFC chip anyway.

When combining the VIZOnlyOnePageFlow with this flow, you typically need to pass the existing readIDSession to the NFCOnlyFlow so that it can use the already obtained NFC access key and other information. You need to combine vizResult from VIZOnlyOnePageFlow and nfcResult from NFCOnlyFlow to obtain the full response. See the sample code for more information.

NFCWithAccessControlFlow configuration options

NFCWithAccessControlFlow support all common configuration options, plus the following:

• Flow.shouldShowDocumentSelection: Sets whether the document selection screen should be shown.
• Flow.shouldShowVIZConfirmation: Sets show VIZ confirmation screen enabled/disabled.
• Flow.allowedDocumentTypes: Sets the list of allowed document types that can be captured. Note that if the user doesn't capture their document, but enters the access control manually, then this list does not apply.
• Flow.vizResultMode: Configures what should be shown on the VIZ results screen.
• Flow.shouldShowVIZPerformanceResult: Sets whether the VIZ performance result should should be shown or not.
• Flow.shouldShowMRZFieldImages: Sets show MRZ field images enabled/disabled.
• Flow.shouldShowMRZText: Sets show MRZ text enabled/disabled.
• Flow.shouldShowMRZImage: Sets show MRZ image enabled/disabled.
• Flow.shouldShowVIZImages: Sets show VIZ images enabled/disabled.
• Flow.shouldShowQRCodeImage: Sets show QR code image enabled/disabled.
• Flow.shouldRequirePersonalNumber: Sets whether to retrieve the personal number from the MRZ or from a QR code on the document. The latter occurs on Dutch passports and ID cards from late 2021 or newer. If you enable this option, the SDK will automatically detect Dutch documents with a BSN in the QR, and will require a scan of that QR. Note that this may cause the SDK to ask the user to scan the back of their passport, after scanning the front but before NFC reading starts, as that is where the QR code resides. Also note that this process may fail due to, for example, OCR mistakes that prevent the SDK from detecting that the document is Dutch.

Obtaining the personal number from the scanned MRZ or QR code is unreliable due to the lack of mechanisms to protect the integrity and authenticity of data, unlike for data read from the chip.

The SDK will attempt to scan only the requested page type(s), as specified via Flow.allowedDocumentTypes, but we cannot guarantee that the result is of the requested type. The more distinctive features a page has, the higher the chance that the SDK captures the correct page type, and vice versa, but there is always the possibility of a wrong page type. If you rely on the VIZ capture result to be accurate then you must verify the page capture results via some other means.

Document and device NFC location

ReadID UI VIZ produces a VIZResult which contains, among other results, the location of the NFC antenna on the document and the device. The latter is only available on Android. For iOS, the device NFC antenna is always in the top middle of the device.

The result can be used to implement custom instruction animations. We actively maintain a database that is used as the basis for the document and device NFC location in an attempt to make these locations as accurate as possible. However, the assessment may be incorrect, and is provided as-is.

You can retrieve the document and the device antenna location using VIZResult.documentNFCLocation and VIZResult.deviceNFCLocation.

Please be aware that the document and device NFC location may be sub-optimal. It can even be outdated or wrong, for example when a state suddenly starts issuing identity documents with a different NFC chip location, or when a certain device manufacturer brings out a new device with a different NFC reader location than previous models. We strive to keep our location database as up-to-date as possible.

iProov

Facial verification is an additional service that this native module can provide if it was contractually agreed upon. iProov is a facial verification service that verifies that there is a real, live person doing the identity verification and that their face matches the photo from the NFC chip of their document. It does this by taking a selfie-video and the face image from the document, and sending both to iProov for verification.

iProov facial verification takes place after reading the user's identity document, so that the ReadID Server can enrol the authentic, verified face image from that document to iProov. The face image is used as a reference image for comparison with the selfie video. Once the iProov service has completed the assessment, the verification results are added to the ReadID session and can be retrieved from the ReadID Server.

ReadID is also able to use the face image extracted from the document's Visual Inspection Zone (VIZ) instead of the chip. This is only intended as a fallback scenario for when the chip cannot be read, and should be used with caution.

Using a VIZ face image is considered to be much less reliable than using the image read from the chip, as VIZ images are not subject to the authenticity and clone detection mechanisms that apply to chip data. We cannot guarantee that we have extracted the correct, original face image. A malicious user can trick ReadID VIZ because of bad lightning, poor camera quality, etc. If you decide to use the VIZ face image for iProov, we strongly recommend to do so only in combination with optical orchestration and to perform manual check of the face image. All VIZ images are available via the management portal, the REST API, and in the PDF.

To combine iProov facial verification with ReadID, you will need to configure it on the ReadID server and implement it within your React Native app. To configure it on the server:

1. Enable iProov for the submitter application that you use in your app.
2. Ensure that you have selected the correct profile. This is either Genuine Presence Assurance(GPA) or Liveness Assurance(LA).

To implement orchestration with iProov from within your React Native app, you must add the iProov React Native module to your project. It is available at https://github.com/iProov/react-native, including instructions to add the iProov module. It is required to make a "selfie video" that will be analyzed and compared with the reference face image.

For each iProov orchestration session, implement the following:

1. Make sure that the ReadID session has been committed to the server before starting the iProov process. The session is normally committed automatically by the ReadID SDK, unless you prevent session commits via your Flow configuration.
2. Start an iProov attempt by requesting an iProov token using retrieveIProovVerifyToken method.
3. Launch the iProov SDK to take the user's selfie video:
4. Finalize the attempt and retrieve iProov verification results using validateIProovVerifyToken method.
5. Repeat steps 2-4 until the user passed verification or until there are no more attempts left.

Start an iProov Attempt:

Use the retrieveIProovVerifyToken method to start the iProov process. This is an asynchronous call that does two things:

1. Request the ReadID Server to enrol the reference face image, taken from the already committed session, with iProov.
2. Return a token that can be used to start the iProov SDK.

The retrieveIProovVerifyToken response, successful or not, is always returned via a callback. The ReadID SDK will poll the ReadID server for a response, for at most 10 times with a delay of 1 second between each request.

Start the iProov SDK:

Once you have a valid iProov verifyToken, start the iProov SDK using the IProov.launch() method. A detailed explanation how to configure the iProov SDK is provided on the Github page of iProov React Native Module. The page also contain information on how to handle failures and errors during this step of the process. Once the iProov SDK has reached a final state you must continue to the next step, regardless of the result.

Finalize the iProov attempt:

Use the validateIProovVerifyToken method to finalize the iProov attempt. This step also tells ReadID server that the iProov token was used and that the server should start polling iProov for verification results. If you do not perform this step, then the ReadID server will mark the iProov session as “abandoned” after 30 minutes, regardless of what happened during the previous step. In addition, the next retrieveIProovVerifyToken would return the same token as the one for the previous attempt. As with retrieveIProovVerifyToken, the validateIProovVerifyToken response is always returned via a callback. The ReadID SDK will poll the ReadID server for a result, for at most 10 times with a delay of 1 second after each request.

The results of the iProov check are available in the Management portal, in the iProov section of the ReadID session details.

The main fields to check are:

Passed iProov: If true, then iProov concluded that a real person was present and that their selfie matches the face image from their document. When using iProov Genuine Presence Assurance, iProov also concluded that the authentication was done in real-time (as opposed to, for example, an injected replay). See the iProov website for a more detailed explanation of what their assurances mean. The corresponding ReadID session field is iProovSession.passed (boolean).

Enrolment image source: The source of the image used for the selfie-check. The image can come from the chip or from the optical capture of the Visual Inspection Zone (VIZ). The corresponding ReadID session field is iProovSession.enrolmentImageSource (string).

Any enrolment image source other than NFC is considered to be (much) less reliable. Images that do not come from the chip are not subject to all of ReadID's verification mechanisms that apply to chip data. If the image was sourced from the VIZ, we strongly recommend doing a manual check of the image used for facial verification.

Assurance type: the iProov verification assurance type used during this session, which is either Liveness Assurance or Genuine Presence Assurance. The corresponding ReadID session field is iProovSession.assuranceType (string). See the iProov website for a detailed explanation of what these verification assurances mean.

Optical Orchestration

Not all identity documents have a (readable) NFC chip. To handle documents without a readable chip, you can combine ReadID with an optical document verification solution. ReadID supports multiple flows that allow you to scan the sides of a document required for optical verification. The results of the optical verification are added to the ReadID session that can be retrieved from the ReadID server. ReadID supports two optical verification vendors: "Veriff" and "Onfido". The service is only available for the SaaS SDKs. Optical verification requires that you also use either iProov Enroller (Genuine Presence Assurance) or Basic Face Verifier (Liveness Assurance). If you combine iProov with Veriff, we strongly recommend to use the by Veriff provided cropped face image (if the face image from the chip is not available).

The face image cropped from the VIZ by the ReadID SDK is not a reliable source. The identity document may be manipulated (e.g., face image replaced) or an attacker may feed a different face image to the ReadID server. ReadID does not perform any authenticity checks on the captured image. If you use this option, be sure to verify the results.

Overview

Optical orchestration must be enabled on the ReadID server and implemented within your mobile app.

To enable optical orchestration on the server, login to the Management Portal with a user that is allowed to manage submitter applications and update the following settings:

1. Enable iProov and configure the allowed sources for the face image.
2. Enable and configure Veriff or Onfido.

Consult the ReadID Server- or Management Portal Administration Guide for more information or contact the ReadID support if needed.

Before doing optical orchestration in your mobile app, you should:

1. Implement a ReadID flow that accounts for documents without a readable chip and/or where chip-reading fails. Make sure that the result of the ReadID flow(s) contains one or two VIZ images of the document if you plan to proceed to optical orchestration. You would typically chain one or more VIZOnlyOnePageFlow's and NFCOnlyFlow to achieve this. You can also use the less flexible but easier to use NFCWithVIZFallbackFlow.
2. Ensure all results are submitted to the ReadID server.
3. Proceed to optical orchestration when necessary, for example when there are no NFC results at all, but possibly also when verification (in particular clone detection) failed.

Optical orchestration implementation:

1. Once the ReadID session (including all VIZ data) has been submitted, initiate optical orchestration via retrieveOnfidoResponse for Onfido or retrieveVeriffResponse for Veriff. The ReadID server will not begin the optical orchestration process unless you use that method. If a fatal error is returned, cancel the process or start over by capturing new VIZ images in a new ReadID session.
2. While the optical orchestration process is running on the server, the app can already proceed with iProov (see iProov Facial Verification). However, when using Veriff, you should wait at least 3 seconds in order to confirm that Veriff is able to provide the face image to iProov. See below for more details.

It is typically neither necessary nor good practice to wait more than a few seconds for the optical verification process to finish before going to the next step in your app. Should you choose to wait for a longer period and/or show any status or intermediate results to the user, you can continue to poll the status using the retrieveOnfidoResponse or retrieveVeriffResponse method.

Optical verification can take a long time, typically too long to let users wait for it. At this time, Veriff can take up to 45 minutes to complete and Onfido up to 6 hours.

Note that you must always start optical orchestration first, iProov second. Starting iProov first may cause the ReadID server to finish the session, meaning it is no longer possible to start optical orchestration. This scenario results in a HTTP 409 error response to the retrieveVeriffResponse or retrieveOnfidoResponse call.

Technical implementation details

To start Onfido, call:

ReadID.retrieveOnfidoResponse(sessionId).then(
      (result) => {
        // Handle result
      },
      (error) => {
        // Handle orchestration errors   
      }
    )

To start Veriff, call:

ReadID.retrieveVeriffResponse(sessionId).then(
      (result) => {
        // Handle result
      },
      (error) => {
        // Handle orchestration errors
      }
    )

The app should implement the following polling logic when the cropped face image from Veriff is used for iProov (recommended):

• Veriff needs up to 3 seconds to provide a cropped face image. Therefore the app must poll repeatedly, with at least a 1 second delay, until either 3 seconds have passed or until one of the following conditions occurred:
  • The app received a verifyVeriffResponse.veriffResponse.message with value face_crop_not_found_before_retrieval_timeout. In that case Veriff was unable to extract a face image, usable for iProov verification, and a restart of the entire process starting from a new ReadID session is required.
  • The app received a verifyVeriffResponse.veriffResponse.verification.status. In that case Veriff has reached a verdict. The value status will be either approved, resubmission_requested, or declined. The verification status resubmission_required indicates that a new VIZ capture should be submitted under the same Veriff session. To do so, store the submissionId for later use, perform one or two new VIZ captures in a new ReadID session, then retry optical verification using the saved submissionId as parameter for the verifyVeriff call.
• If there was no verdict or error for at least 3 seconds, you may proceed to iProov verification.

If the face image cropped from the VIZ by the ReadID SDK is used for iProov (not recommended), a single call without error is enough to proceed with iProov.

ReadID React Native Module Data Model Documentation

Flow Objects

Flow objects in TypeScript are write-only, meaning all properties have setters only. Default values for properties can be consulted in our native SDK documentation.

Not available at this current time for NFC/VIZ

• vizConfirmationScreenConfiguration: n/a
• vizResultScreenConfiguration: n/a
• isTouchToFocusEnabled: n/a (Android only)

(Abstract) Flow

Properties:

• applicationLevelEncryptionPins: List
• accessKey: String?
• backgroundTimeout: int (TimeInterval on iOS, long on Android)
• baseUrl: String? (called baseURL on Android)
• dateFormat: DateFormat enum
• dateSeparator: DateSeparator enum
• instructionsPlayCount: int
• isDebugEnabled: n/a (not exposed to React Native yet)
• language: String?
• oAuthToken: String? (oauthToken on iOS)
• opaqueID: String?
• preventSessionCommit: bool
• readIDSession: ReadIDSession? (Map?)
• readIDTracker: n/a (not supported in React Native yet)
• screenOrientation: ScreenOrientation enum (Map)
• shouldAllowScreenshots: bool (Android only)
• shouldAskDismissConfirmation: bool (iOS only)
• shouldMaskPersonalData: bool
• shouldOnlyShowInstructionsOnFirstUse: bool
• shouldUsePinning: bool
• uiResources: n/a (not supported in React Native yet)
• customBundleName: String (iOS only)

VIZOnlyOnePageFlow

Properties:

• allowedPageTypes: List
• allowManualCaptureAfterTimeout: int (Long on iOS)
• faceImageFeatureRequirement: FeatureRequirement enum
• fastCaptureMode: bool
• mrzFeatureRequirement: FeatureRequirement enum
• mrzValidation: MRZValidation enum
• qrCodeFeatureRequirement: FeatureRequirement enum
• shouldAllowLoweringQualityRequirements: bool
• shouldRequireNoFingerOnDocument: bool
• shouldRequireNoGlareOnDocument: bool
• shouldRequireSharpImage: bool
• shouldPlayShutterSound: bool
• shouldShowDocumentSelection: bool
• shouldShowTorchButton: bool
• shouldShowVIZConfirmation: bool
• shouldShowVIZResult: bool

NFCWithAccessControlFlow

Properties:

• manualInputMode: ManualInputMode enum
• shouldCommitSessionWithoutNFC: bool
• accessControlOption: n/a
• allowResumeNFCReading: n/a
• allowSkipReadingAfterAttempts: int
• allowedDataGroupsToRead: List?
• allowedDocumentTypes: List
• extendedLengthAPDUPreference: n/a
• nfcResultScreenConfiguration: n/a
• shouldCommitSessionWithSkipButton: n/a (iOS only)
• shouldPlayShutterSound: bool
• shouldReadImages: bool
• shouldRequirePersonalNumber: bool
• shouldShowDocumentSelection: bool
• shouldShowNFCResult: bool
• shouldShowTorchButton: bool
• shouldShowVIZConfirmation: bool
• shouldShowVIZResult: bool

NFCOnlyFlow

Properties:

• accessControlOption: AccessControlOption enum
• allowedDataGroupsToRead: List?
• allowResumeNFCReading: bool
• allowSkipReadingAfterAttempts: int
• documentInfo: DocumentInfo (Map, used as optional constructor parameter)
• extendedLengthAPDUPreference: ExtendedLengthAPDUPreference enum
• nfcAccessKey: NFCAccessKey (Map, used as required constructor parameter)
• nfcResultScreenConfiguration: NFCResultScreenConfiguration (Map)
• preventChipSupportDialog: bool
• shouldReadImages: bool
• shouldShowInstructionCarousel: bool
• shouldShowNFCResult: bool
• trustedCertStores: n/a (Android only)

Result Objects

Result objects in TypeScript are read-only data objects that contain the VIZ and NFC results from a successful ReadID session.

ReadIDResult

Properties:

• vizResult: VIZResult?
• nfcResult: NFCResult?

(Abstract) BaseResult

An abstract base class that holds properties common in both VIZResult and NFCResult.

NFCResult extends BaseResult

Properties:

• faceImage: string? (base64)
• signatureImage: string? (base64)
• Additional properties detailing the outcomes of the ReadID session.

VIZResult

Properties

• frontCaptureResult: CaptureResult?
• backCaptureResult: CaptureResult?
• nfcAccessKey: NFCAccessKey?
• documentInfo: DocumentInfo?
• nfcChipSupport: NFCChipSupport?
• deviceNFCLocation: DeviceNFCLocation?
• Additional properties detailing the outcomes of the ReadID session.

ReadIDSession

Encapsulated a session where information from a single document is captured. It can contain data read through NFC as well as optically captured data.

class ReadIDSessionState:

Instance Properties:

• var clientConfiguration: ClientConfiguration?
• var clientId: String An identifier that identfies the application that captured this sessions.
• var consolidatedIdentityData: ConsolidatedIdentityData? The consolidated identity data.
• var creationDate: Date? The date the session was stored.
• var customerApplicationReference: String? An opaque value customers can use to store a reference for their own internal use.
• var deviceId: String A unique identifier for the device that captured this sessions
• var documentContent: MRTDDocumentContent? Contents of the document, this data is extracted from the data read from the NFC chip.
• var expiryDate: Date? The date when this session expires.
• var expiryTimestamp: Int64? The Unix timestamp for the moment the session will expire.
• var instanceId: String A unique identifier for the application installation that captured this session.
• var nfcSession: NFCSession Contains data captured from the document using NFC.
• var ocrSession: OCRSession? Contains data captured from the document using OCR.
• var opaqueId: String? This customer-provided identifier can be used by our customer to cross-reference this ReadID Session to an app session identifier.
• var sessionId: String A unique identifier for the session.
• var vizImages: VIZImages? Contains data optically captured from the Visual Inpection Zone (VIZ).
• var vizSession: VIZSession?
• func restoreState(from: ReadIDSessionState) throws Restore state of a ReadIDSession.
• func saveState() -> ReadIDSessionState? Save state of ReadIDSession.

License

Please read the LICENSE file before using this native module. Note that the native Android and iOS ReadID SDKs have a separate license.

Help and support

You may find your question is answered in the documentation of our native SDKs. This documentation is available via our ReadID Documentation portal.

For further help with integration of the react native module, please contact support.

Glossary

Access Control

Security mechanism that controls who or what can read and access the contents of the chip.

Access Control Error

An error that occurs when the NFC reading process fails due to incorrect access keys or insufficient access rights.

ICAO (International Civil Aviation Organization)

International Civil Aviation Organization.

Manual Input Screen

A screen where users can manually enter access information if the NFC reading process fails due to an incorrect access key.

MRTD (Machine Readable Travel Document)

Machine Readable Travel Document that conforms to the ICAO 9303 standard.

NFC (Near-Field Communication)

A technology that enables short-range wireless communication between devices, often used for document reading or payments.

VIZ (Visual Inspection Zone)

The part of a document, such as a passport or ID card, that contains readable personal information without the use of special technology.

MRZ (Machine Readable Zone)

A section on documents like passports that contains personal information in a format that can be read by machines using OCR (Optical Character Recognition).