readid-react-native
v4.122.0
Published
ReadID React Native
Readme

ReadID React Native Module
Table of contents
- Introduction
- Requirements
- Limitations and Known Issues
- Repository Contents
- Installation
- Client-server vs client-only
- Getting Started
- Sample code
- Features
- Advanced
- ReadID React Native Module Data Model Documentation
- 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
Flowconfiguration properties have a setter but no getter, i.e. you can configure all settings but you cannot query configuration settings. vizConfirmationScreenConfiguration,vizResultScreenConfiguration, andisTouchToFocusEnabled(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
- Add repositories to your
build.gradle(root scope):
allprojects {
repositories {
google()
maven {
url "s3://maven-readid-7npn738r9muhb5r6mm97b7pxcck84euw1a-s3alias"
authentication { awsIm(AwsImAuthentication) }
}
}
}- 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.
- 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
}
}- Add AndroidX properties to your gradle.properties (project root). Create if it does not exist:
android.useAndroidX=true- Make sure
enableJetifierisfalseon gradle.properties
android.enableJetifier=false- Add required features for NFC: Add the nfc feature to your
AndroidManifest.xml
<uses-feature
android:name="android.hardware.nfc"
android:required="true"/>- 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/emulatorThen 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:
Add ReadID frameworks: To integrate the ReadID SDK, which consists of two frameworks:
ReadID_UI.xcframework, andReadID_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 toGeneral -> Frameworks, Libraries, and Embedded Content, and drag the frameworks into this section. Make sure theEmbed & Signoption is selected for each framework.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 endIn the
Signing & Capabilitiestab of your app target, click the+ Capabilitybutton and add theNear Field Communication Tag Readingcapability.Add
NSCameraUsageDescriptionto the App's Info.plist file. The camera is needed to scan the document, including the MRZ.Add
NFCReaderUsageDescriptionto 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>On the Apple developer portal create a distribution provisioning profile and enable capability
NFC Tag Reading.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 thecom.apple.developer.nfc.readersession.iso7816.select-identifierskey in yourInfo.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?.faceImageThe faceImage is returned as a string, which you can display using the Image component in React Native.
It's also possible that the SDK fails to start, throwing an error: ReadIDError. This error contains an errorReason which can be reasons like:
| Exception | Description | |----------------------|------------------------------------------------------------------------------| | InvalidConfiguration | A configuration was passed to the native SDK which is currently not handled. | | NfcNotSupported | The device has no NFC or the NFC reading is disabled. | | Exception | Any miscellaneous error throw from the SDK. |
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:
NFCWithAccessControlFlowiOS | 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. SeeFlow.shouldRequirePersonalNumberbelow.VIZOnlyOnePageFlowiOS | 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.NFCOnlyFlowiOS | Android: Only read the identity document's NFC chip. This flow can be combined with theVIZOnlyOnePageFlowin 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.NFCWithVIZFlow: Scan the document's MRZ page, then read the chip. Use this flow when you want to acquire a high quality VIZ image and/or features and read the document's NFC chip.NFCWithVIZBothSidesFlow: Scan both sides of a document, including the MRZ page, then read the chip. Use this flow when you want to acquire high quality VIZ images of both sides of a document as well as read the document's NFC chip.
The VIZ SDK will attempt to scan only the requested page or document type(s), as specified via
VIZOnlyOnePageFlow.allowedPageTypesor.allowedDocumentTypesfor 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:
- Document selection screen
- Instruction animation screen
- VIZ capture screen
- Manual input screen
- VIZ confirmation screen
- VIZ result screen
- NFC instruction animation screen
- NFC reading screen
- 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
FlowpropertyshouldShowDocumentSelectionand 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
FlowpropertyshouldShowVIZResulttofalse.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
NFCWithAccessControlFlowpropertyshouldShowNFCResulttofalse. 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.tlsPins: Defines the set of pins to use.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.
NFC Chip Support
Indicates whether the document contains a chip and if it’s supported by ReadID.
The NFC chip support of the document can be checked with the following code:
With VIZResult (after VIZ flow):
const nfcChipSupport = vizResult.nfcChipSupport;With NFCOnlyFlow (no VIZResult):
const flow: NFCOnlyFlow = {... instance of nfcOnlyFlow };
const nfcOnlyFlow: ReadIDFlow = {flowName: 'NFCOnlyFlow', flow: flow};
try {
const chipSupport = await getNFCChipSupport(nfcOnlyFlow);
console.log('NFC Chip Support:', chipSupport);
} catch (error) {
console.error('Failed to get NFC chip support:', error);
}Note: ReadID UI VIZ produces a VIZResult that includes, among other values, an assessment of whether the scanned document likely contains a supported NFC chip. This determination is based on an actively maintained database, which we strive to keep as accurate and up to date as possible. However, chip support assessments are not guaranteed to be correct. For instance, a country may begin issuing documents with chips unexpectedly, or temporary documents might lack a chip that is normally present. As such, results may occasionally be sub-optimal or incorrect. To ensure the most accurate and current information, always use the latest version of the plugin. Older versions may rely on outdated data.
Document NFC location
Indicates the location of the NFC antenaa on the document.
With VIZResult (after VIZ flow):
const documentNFCLocation = vizResult.documentNFCLocation;With NFCOnlyFlow (no VIZResult):
const flow: NFCOnlyFlow = {... instance of nfcOnlyFlow };
const nfcOnlyFlow: ReadIDFlow = {flowName: 'NFCOnlyFlow', flow: flow};
try {
const documentNFCLocation = await getDocumentNFCLocation(nfcOnlyFlow);
console.log('Document NFC Location:', documentNFCLocation);
} catch (error) {
console.error('Failed to get Document NFC Location:', error);
}Device NFC Location
Indicates the location of the NFC antenna on the device.
With VIZResult (after VIZ flow):
const deviceNFCLocation = vizResult.deviceNFCLocation;With NFCOnlyFlow (no VIZResult):
const flow: NFCOnlyFlow = {... instance of nfcOnlyFlow };
const nfcOnlyFlow: ReadIDFlow = {flowName: 'NFCOnlyFlow', flow: flow};
try {
const deviceNFCLocation = await getDeviceNFCLocation(nfcOnlyFlow);
console.log('Device NFC Location:', deviceNFCLocation);
} catch (error) {
console.error('Failed to get Device NFC Location:', error);
}Note: The document and device NFC locations can be used to implement custom instruction animations. These locations are based on an actively maintained database, which we aim to keep as accurate and current as possible. However, the provided values may occasionally be sub-optimal or outdated. For example, a country might change the chip placement in newly issued documents, or a device manufacturer may alter the NFC reader position in newer models. While we strive to keep the location data up to date, it is provided as-is and may not always reflect the latest changes.
Styling
Android
The ReadID UI SDKs make use of different Android resources like fonts, colors, drawables, dimensions and layouts. To adapt the style of the ReadID UI SDKs to the style of your app it is possible to override these resources.
Fonts
Fonts can be changed by overriding the used font resources.
The fonts are located in /res/font and have the following names and functions:
readid_text_font- By default Roboto regular.
- Used for normal text, labels and values.
readid_title_font- By default Roboto medium.
- Used for screen titles.
readid_button_font- By default Roboto medium.
- Used for primary and secondary buttons.
readid_text_button_font- By default Roboto medium.
- Used for the "Skip reading" button on the NFC read screen.
readid_ocr_b- By default OCR B.
- Used as MRZ placeholder while VIZ scanning and on the result screens for MRZ values.
- Note: should not be overridden, otherwise shown MRZs will look unformatted and comparison from MRZ value and photo crop will be more difficult for the user.
Drawables
The header logo can be changed by overriding:
/res/drawable/readid_header_image.xmlThe VIZ back button image can be changed by overriding:
<!-- Either override each drawable -->
res/drawable/readid_viz_back.xml
res/drawable/readid_viz_back_pressed.xml
<!-- or only the selector drawable and use your own image resources -->
res/drawable/readid_viz_back_selector.xmlNote: the original back button images contain a visible content of 36x36dp with 6dp horizontal padding, 4dp top padding and 8dp bottom padding to archive proper alignment a click area of 48x48dp.
The VIZ torch button image can be changed by overriding:
<!-- Either override each drawable -->
res/drawable/readid_torch_off.xml
res/drawable/readid_torch_off_pressed.xml
res/drawable/readid_torch_on.xml
res/drawable/readid_torch_on_pressed.xml
<!-- or only the selector drawable and use your own image resources -->
res/drawable/readid_torch_selector.xmlThe VIZ manual input button image can be changed by overriding:
<!-- Either override each drawable -->
res/drawable/readid_manual_input.xml
res/drawable/readid_manual_input_pressed.xml
<!-- or only the selector drawable and use your own image resources -->
res/drawable/readid_manual_input_selector.xmlDimensions
Margin:
<!-- will change the default screen padding and margins between
views -->
<dimen name="readid_margin">16dp</dimen>
<!-- will change the vertical margin between values on the result screens -->
<dimen name="readid_margin_small">8dp</dimen>Header:
<!-- will change the header height -->
<dimen name="readid_header_height">60dp</dimen>
<!-- will change the header logo width -->
<dimen name="readid_header_logo_width">
@dimen/readid_wrap_content
</dimen>
<!-- will change the header logo height -->
<dimen name="readid_header_logo_height">
@dimen/readid_match_parent
</dimen>Text:
<!-- will change the default text size -->
<dimen name="readid_text_size">17sp</dimen>
<!-- will change the title text size -->
<dimen name="readid_text_size_title">22sp</dimen>
<!-- will change the section header text size (result screen
section titles) -->
<dimen name="readid_text_size_section_header">18sp</dimen>
<!-- will change the icon button text size -->
<dimen name="readid_button_icon_text_size">12sp</dimen>
<!-- will change the manual input error message text size -->
<dimen name="readid_input_field_error_text_size">12sp</dimen>Primary/secondary button:
<!-- will change the primary and secondary buttons -->
<dimen name="readid_button_height">48dp</dimen>
<dimen name="readid_button_corner_radius">2dp</dimen>
<dimen name="readid_button_text_size">17sp</dimen>
<dimen name="readid_button_stroke_width">1dp</dimen>
<!-- will enable/disable all caps for the primary and
secondary buttons -->
<bool name="readid_button_all_caps">false</bool>Icon buttons:
<!-- will change the icon button size -->
<dimen name="readid_button_icon_size">48dp</dimen>Manual input screen:
<!-- Manual input X button size -->
<dimen name="readid_x_button_size">48dp</dimen>VIZ wireframe:
<!-- will change the MRZ wireframe stroke width and
corner radius -->
<dimen name="readid_wireframe_stroke_width">3dp</dimen>
<dimen name="readid_wireframe_corner_radius">24dp</dimen>Face image:
<!-- will change the face image width on the result screens
(it will keep the aspect ratio) -->
<dimen name="readid_face_image_width">150dp</dimen>QR code image:
<!-- will change the QR code image width on the result screens
(it will keep the aspect ratio) -->
<dimen name="readid_qr_code_image_width">50dp</dimen>Document image:
<!-- will change the document and MRZ image width on the result
screens (it will keep the aspect ratio) -->
<dimen name="readid_document_image_width">
@dimen/readid_match_parent
</dimen>Signature image:
<dimen name="readid_signature_image_width">150dp</dimen>Instruction carousel:
<dimen name="readid_carousel_progress_indicator_size">16dp</dimen>Layouts
The header bar can be changed by overriding:
/res/layout/readid_header.xmlFor example:
<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android"
android:layout_width="match_parent"
android:layout_height="@dimen/readid_header_height"
android:importantForAccessibility="noHideDescendants">
<ImageView
android:id="@+id/ivLogo"
android:layout_width="@dimen/readid_header_logo_width"
android:layout_height="@dimen/readid_header_logo_height"
android:layout_alignParentStart="true"
android:layout_centerVertical="true"
android:layout_marginStart="@dimen/readid_margin"
android:layout_marginTop="@dimen/readid_margin_small"
android:layout_marginEnd="@dimen/readid_margin"
android:layout_marginBottom="@dimen/readid_margin_small"
android:adjustViewBounds="true"
android:scaleType="fitCenter"
android:src="@drawable/readid_header_image"/>
<View
android:layout_width="match_parent"
android:layout_height="1dp"
android:layout_alignParentBottom="true"
android:background="?android:attr/listDivider"/>
</RelativeLayout>It is possible to add a view with android:id="@+id/back", which will get the same functionality as the Android hardware back button, if it exists.
The progress bar can be changed by overriding:
/res/layout/readid_progress_bar.xmlFor example (do not change view type and android:id):
<ProgressBar xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:app="http://schemas.android.com/apk/res-auto"
android:id="@+id/pbWaitProgress"
style="?android:attr/progressBarStyle"
android:layout_width="wrap_content"
android:layout_height="wrap_content"
android:layout_centerInParent="true"
android:indeterminate="true"
android:indeterminateTint="@color/readid_loading_color"
android:saveEnabled="false"
app:layout_constraintBottom_toBottomOf="parent"
app:layout_constraintEnd_toEndOf="parent"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent" />Alert dialog style
The in the SDK shown alert dialogs are using a custom theme called readid_dialog_theme.
This theme can be overridden by adding a style/theme with the same name to your app.
<style name="readid_dialog_theme" parent="your or Android alert dialog theme"/>Alternative it is also possible to only override the following dialog colors:
<color name="readid_dialog_button_text_color">#973189</color>
<color name="readid_dialog_text_color">#333333</color>
<color name="readid_dialog_background_color">#F2F2F2</color>Strings and languages
The SDK provides five languages by default:
- English (UK)
- Dutch
- Spanish
- French
- German
All text in the SDK can be overridden in the app by adding a new strings.xml file to the app's values-<LOCALE> folder.
When customising strings, keep in mind that accessibility settings such as large fonts can have a significant effect on the layout of strings, especially when using large words.
The default set of strings can be found in the String resources.zip on https://docs.readid.com/.
If you intend to use a specific language, regardless of the device language, you can force the SDK to use that language with flow.language.
Examples:
- Use
flow.language = "es"to enforce the usage ofres/values-es/strings.xml - Use
flow.language = "es-AR"to enforce the usage ofres/values-es-rAR/strings.xml(Note: "es-AR" is by default not supported)
iOS
The ReadID UI framework makes use of different resources like colors and images. To adapt the style of the ReadID UI SDK to the style of your app it is possible to override these resources by providing a custom bundle to the Flow property UIResources.
For example, If you need custom colors and/or a custom titleImage, set them in your application's Assets.xcassets.
Then set the bundle in which your .xcassets reside as a custom bundle in ReadID UI.
Below is an example for the common use case where the .xcassets of an app are part of the main bundle:
// Set up your styling
const resources: UIResources = {
customBundleIdentifier: "expo.modules.readidreactnative.example"
}
// Apply it to a flow
flow.uiResources = uiResources;See UIResources in the API documentation for details about the configurable parameters.
Header image
When a readid_header_image image is set in the .xcassets and the bundle is set as above, the SDK will use this image as the titleView for the navigation item of all viewControllers. Make sure the size is correct, otherwise it will be off-center.
Fonts
You can change the font(s) used for various UI elements via UIResources. For example, to set the font for buttons:
const buttonFont: UIFont = {
name: "MarkerFelt-Thin",
size: 24,
}
const resources: UIResources = {
customBundleIdentifier: 'expo.modules.readidreactnative.example',
buttonFont: buttonFont
}
flow.resources = resources;Images
Specific images can be customised statically in the same way as you would change colors. The following images can be customised:
/*
The SDK will use this image as the titleView for the navigation item of all viewControllers. Make sure the size is correct, otherwise it will be off-center.
*/
readid_header_image
/*
Icon on the viz capture screen for when torch is toggled on.
Image has a 1:1 ratio
*/
readid_torch_on
/*
Icon on the viz capture screen for when torch is toggled on. (Pressed state)
Image has a 1:1 ratio
*/
readid_torch_on_pressed
/*
Icon on the viz capture screen for when torch is toggled off.
Image has a 1:1 ratio
*/
readid_torch_off
/*
Icon on the viz capture screen for when torch is toggled off. (Pressed state)
Image has a 1:1 ratio
*/
readid_torch_off_pressed
/*
Icon on the viz capture screen for manual input.
Image has a 1:1 ratio
*/
readid_manual_input
/*
Icon on the viz capture screen for manual input. (Pressed state)
Image has a 1:1 ratio
*/
readid_manual_input_pressedStrings and languages
The SDK provides five languages by default:
- English (UK)
en - Dutch
nl - Spanish
es - French
fr - German
de
All text in the SDK can be overridden in the app by adding them to the app's Localizable.strings. Set Flow.uiResources.customBundle to the bundle in which your Localizable.strings files resides. Example:
const resources: UIResources = {
customStringTableName: 'SomeOtherName'
}
flow.uiResources = uiResources;When customising strings, keep in mind that accessibility settings such as large fonts can have a significant effect on the layout of strings, especially when using large words.
The default set of strings can be found in the String resources.zip on https://docs.readid.com/.
If you intend to use a specific language, regardless of the device language, you can force the SDK to use that language with flow.language.
Examples:
- Use
flow.language = "es"to enforce Spanish language - Use
flow.language = "es-AR"to enforce Spanish as used in Argentina (Note: "es-AR" is by default not supported)
Colors
System colors
SDK colors
Android color customisation
Colors can be statically overriden in the .xml files in the resources folder.
All below listed resources can be changed for light and dark mode:
- The light color resources are located in
/res/values - The dark color resources are located in
/res/values-night
Dark mode can be disabled by adding AppCompatDelegate.setDefaultNightMode(AppCompatDelegate.MODE_NIGHT_NO) to your app.
OS system bars:
<!-- will change the status bar color -->
<color name="readid_os_status_bar_color">#973189</color>
<!-- will tell the OS whether a light status bar color is used and
will give the text more contrast -->
<bool name="readid_os_window_light_status_bar">false</bool>
<!-- will change the OS navigation bar color -->
<color name="readid_os_navigation_bar_color">#000000</color>
<!-- will tell the OS whether a light navigation bar color is used
and will give the symbols more contrast (has no effect on
Android API level < 27) -->
<bool name="readid_os_window_light_navigation_bar">false</bool>
<!-- will change the OS navigation bar divider color (has no effect
on Android API level < 27) -->
<color name="readid_os_navigation_bar_divider_color">#00000000</color>Background and header colors:
<color name="readid_background_color">#FFFFFF</color>
<color name="readid_header_color">#FFFFFF</color>Text:
<!-- will change the title text color -->
<color name="readid_title_color">#000000</color>
<!-- will change the default text color -->
<color name="readid_text_color">#000000</color>
<!-- will change the placeholder text color (manual input screen) -->
<color name="readid_placeholder_text_color">#808080</color>
<!-- will change the microcopy text color (manual input screen) -->
<color name="readid_microcopy_text_color">#666666</color>
<!-- will change the section header text color (result screens) -->
<color name="readid_section_header_text_color">
@color/readid_text_color
</color>
<!-- will change the section header background color (result screens) -->
<color name="readid_section_header_background_color">#EBEBEB</color>Loading views:
<!-- will change the spinner and progress bar color -->
<color name="readid_loading_color">#973189</color>Primary button:
<!-- will change the primary button colors -->
<color name="readid_primary_button_color">#973189</color>
<color name="readid_primary_button_pressed_color">#48074C</color>
<color name="readid_primary_button_disabled_color">#CCCCCC</color>
<color name="readid_primary_button_text_color">#FFFFFF</color>
<color name="readid_primary_button_pressed_text_color">#FFFFFF</color>
<color name="readid_primary_button_disabled_text_color">#666666</color>
<color name="readid_primary_button_border_color">#973189</color>
<color name="readid_primary_button_pressed_border_color">#48074C</color>
<color name="readid_primary_button_disabled_border_color">#CCCCCC</color>Secondary button:
<!-- will change the secondary button colors -->
<color name="readid_secondary_button_color">#FFFFFF</color>
<color name="readid_secondary_button_pressed_color">#EEDEEC</color>
<color name="readid_secondary_button_disabled_color">#FFFFFF</color>
<color name="readid_secondary_button_text_color">#973189</color>
<color name="readid_secondary_button_pressed_text_color">#48074C</color>
<color name="readid_secondary_button_disabled_text_color">#808080</color>
<color name="readid_secondary_button_border_color">#973189</color>
<color name="readid_secondary_button_pressed_border_color">#48074C</color>
<color name="readid_secondary_button_disabled_border_color">#808080</color>Alert dialog:
<color name="readid_dialog_button_text_color">#973189</color>
<color name="readid_dialog_text_color">#333333</color>
<color name="readid_dialog_background_color">#F2F2F2</color>VIZ wireframe:
<!-- will change the VIZ wireframe color -->
<color name="readid_viz_wireframe_color">#FFFFFF</color>
<!-- this will change the VIZ status text color -->
<color name="readid_status_text_color">#FFFFFF</color>
<!-- this will change the VIZ status text background color -->
<color name="readid_status_background_color">#B3000000</color>VIZ icon button:
<!-- will change the icon button text color on the VIZ scan
screen -->
<color name="readid_button_icon_text_color">#FFFFFF</color>Manual input:
<!-- will change the manual input field border color -->
<color name="readid_input_field_border_color">#973189</color>Carousel next and previous icon buttons:
<color name="readid_icon_button_color">#973189</color>
<color name="readid_icon_button_pressed_color">#48074C</color>
<color name="readid_icon_button_disabled_color">#CCCCCC</color>Carousel progress:
<!-- will change the instruction carousel colors -->
<color name="readid_carousel_indicator_selected_color">#973189</color>
<color name="readid_carousel_indicator_color">#CCCCCC</color>Result screen row separator:
<!-- will change the horizontal divider line color on the
result screens -->
<color name="readid_row_separator_color">#D6D6D6</color>Success, error and warning colors:
<!-- will change the success/error/warning text color on the
VIZ capture and result screens -->
<color name="readid_success_color">#077D55</color>
<color name="readid_warning_color">#FF8C00</color>
<color name="readid_error_color">#B00020</color>Result tabs colors:
<!-- will change the tabs on the VIZ and NFC result screens -->
<color name="readid_tab_selected_color">#973189</color>
<color name="readid_tab_selected_text_color">#973189</color>
<color name="readid_tab_text_color">#666666</color>
<color name="readid_tab_background_color">#FFFFFF</color>
<color name="readid_tab_divider_color">#CCCCCC</color>Animation colors:
<!-- will change the color used for the touch point in animations -->
<color name="readid_nfc_touch_point_color">#0070BA</color>
<!-- will change the colors used for the passport in animations -->
<color name="readid_passport_color">#5C2633</color>
<color name="readid_passport_symbol_color">#B59D57</color>
<color name="readid_passport_inner_page_color">#E7CBCA</color>
<color name="readid_passport_inner_page_content_color">#7A5864</color>iOS color customisation
Colors can be configured statically through your .xcassets file. Every iOS app includes at least one asset catalogue by default, which serves as a centralized location for managing assets like images, colors, and data. To add a color to your asset catalogue, simply open the .xcassets file in Xcode, create a new color set, and define your desired color values.
The .xcassets color names are in the format of readid_<lower-case enum value using snake case> for example: readid_background_color.
All above listed resources can be changed for light and dark mode.
Dark mode can be disabled by adding the following property to your app's info.plist:
<key>UIUserInterfaceStyle</key>
<string>Light</string>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:
- Enable iProov for the submitter application that you use in your app.
- 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:
- 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
Flowconfiguration. - Start an iProov attempt by requesting an iProov token using
retrieveIProovVerifyTokenmethod. - Launch the iProov SDK to take the user's selfie video:
- Finalize the attempt and retrieve iProov verification results using
validateIProovVerifyTokenmethod. - 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:
- Request the ReadID Server to enrol the reference face image, taken from the already committed session, with iProov.
- 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:
- Enable iProov and configure the allowed sources for the face image.
- Enable and configure Veriff or Onfido.
Consult the ReadID Server- or Management Portal Administration Guide for more information or contact the ReadID supp
