readid-react-native
Advanced tools
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.
Refer to the native Android and iOS tech guides on the Documentation portal for platform specific requirements.
A subset of the native SDK API is not available in the React Native Module due to technical limitations. This includes:
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 availableREADME.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.You can install this package by running the following command in your React Native
project: npm install readid-react-native
build.gradle (root scope):allprojects {
repositories {
google()
maven {
url "s3://maven-readid-7npn738r9muhb5r6mm97b7pxcck84euw1a-s3alias"
authentication { awsIm(AwsImAuthentication) }
}
}
}
[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 Signicat.
android {
compileOptions {
// Sets Java compatibility to Java 8
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
}
android.useAndroidX=true
enableJetifier is false on gradle.propertiesandroid.enableJetifier=false
AndroidManifest.xml<uses-feature
android:name="android.hardware.nfc"
android:required="true"/>
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
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.
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, 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.
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
In the Signing & Capabilities tab of your app target, click the + Capability button and add the Near Field Communication Tag Reading capability.
Add NSCameraUsageDescription to the App's Info.plist file. The camera is
needed to scan the document, including the MRZ.
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>
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 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>
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'
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.
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. |
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.
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.
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.
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:
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.
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)
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.
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.
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.
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.
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.
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.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.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.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 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 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.
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.
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);
}
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.
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 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
readid_title_font
readid_button_font
readid_text_button_font
readid_ocr_b
The ReadID UI SDK supports customising the font family and styles, but only uniformly across the entire text element. For example, different styles like bold, italics, or underline cannot be applied to individual parts of a paragraph, the entire text element must share the same style.
readid_text_font: by default Roboto regulartextFont: by default SF pro regularreadid_title_font: by default Roboto mediumtitleFont: by default SF pro regularreadid_button_font: by default Roboto mediumbuttonFont: by default SF pro regularreadid_section_header_font, by default default Roboto regular.sectionHeaderFont, by default SF pro regularreadid_row_label_font, by default default Roboto regularrowLabelFont, by default SF pro regularreadid_ocr_b, by default OcrB regularNote: it is not recommended to override the readid_ocr_b as the MRZ placeholder on the VIZ capture screen may no longer evenly align with the MRZ on the identity document and will also affect the alignment of the face image placeholder.
Note: On iOS, font size customisation is only possible if Dynamic Type is disabled (isDynamicTypeEnabled = false). Therefore, it is recommended not to customise font sizes for accessibility. If Dynamic Type is enabled, iOS system font sizes will be applied. Furthermore on iOS, letter spacing or tracking is not customisable. The font sizes for iOS can be found in the typography section.
readid_text_size: the default value is 17sptextSize: the default value is iOS default: Body (17 points)readid_text_size_title: the default value is 22spiOS default: Title 2readid_button_text_size: the default value is 17spiOS default: Bodyreadid_text_size_section_header: the default value is 13spsectionHeaderTextSize: the default value is iOS default: Footnotereadid_row_label_text_size: the default value is 15sprowLabelTextSize: the default value is iOS default: Subheadreadid_input_field_error_text_size: the default value is 12spiOS default: Footnotereadid_button_icon_text_size: the default value is 12spiOS default: caption 1
Rich text attributes are supported for title and body strings in the following screens, allowing further font style customizations:
Important: Using inline HTML styling will override the default font families, sizes, and colors applied by UIResources.
Supported HTML attributes:
<b>, <strong>)<i>, <em>)<u>)<s>, <del>)<h1> to <h6>)<ul>)<ol>) (only supported on iOS)Unsupported features:
<a> tags) are not supported<table>), forms (<form>), buttons (<button>), and input fields (<input>) are not supportedKnown limitations:
<ol> tags will not work on AndroidThe header logo can be changed by overriding:
/res/drawable/readid_header_image.xml
The 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.xml
Note: 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.xml
The 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.xml
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>
The header bar can be changed by overriding:
/res/layout/readid_header.xml
For 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.xml
For 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" />
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>
The SDK provides five languages by default:
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:
flow.language = "es" to enforce the usage of res/values-es/strings.xmlflow.language = "es-AR" to enforce the usage of res/values-es-rAR/strings.xml (Note: "es-AR" is by default not supported)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.
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.
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;
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_pressed
The SDK provides five languages by default:
ennlesfrdeAll 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:
flow.language = "es" to enforce Spanish languageflow.language = "es-AR" to enforce Spanish as used in Argentina (Note: "es-AR" is by default not supported)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:
/res/values/res/values-nightDark 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>
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>
To read more about advanced UI customisation, please refer to the UI guide on the ReadID Documentation portal.
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:
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:
Flow configuration.retrieveIProovVerifyToken method.validateIProovVerifyToken
method.Start an iProov Attempt:
Use the retrieveIProovVerifyToken method to start the iProov process. This is an asynchronous call that does two things:
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.
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.
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:
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:
VIZOnlyOnePageFlow's and NFCOnlyFlow to achieve this. You can also use the less flexible but easier to use NFCWithVIZFallbackFlow.Optical orchestration implementation:
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.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.
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):
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.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 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.
After orchestration, call the finish(sessionId:) method. You will receive a FinishResult or an error. From the finish result, you can check the succeeded property to see if the session was successfully finished.
By default, the SDK uses TLS certificate pinning to further limit the set of trusted servers. If you use our SDK in combination with a reverse proxy, using Flow.setBaseURL, you will either need to configure the appropriate pins for your proxy, or disable certificate pinning entirely.
We recommend leaving pinning to its default settings if you are not using a proxy server. Signicat performs timely maintenance on these pins when needed.
Read our Architecture and Security White paper for more information on when and how to pin. More background information can be found in Apple's developer documentation.
To configure a custom set of certificate pins, create and then activate them using Flow.tlsPins before starting the Flow. Using Flow.tlsPins will completely replace the previous set of pins. Pins configured in the ReadID SDK apply to all connections made by the SDK to the ReadID Server, but not to any other connections.
The SDK expects each pin to be a base64-encoded SHA256 hash of the Subject Public Key Info (SPKI). You can obtain such a hash using openssl:
openssl x509 -pubkey -noout | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | openssl enc -base64
The command line above expects you to paste a PEM-encoded certificate into the console.
The default set of pins embedded in the UI SDK is:
| Subject | Base64(SHA256(SubjectPublicKeyInfo)) |
|---|---|
| C=US/O=Amazon/CN=Amazon Root CA 1 | ++MBgDH5WGvL9Bcn5Be30cRcL0f5O+NyoXuWtQdX1aI= |
| C=US/ST=New Jersey/L=Jersey City/O=The USERTRUST Network/CN=USERTrust RSA Certification Authority | x4QzPSC810K5/cMjb05Qm4k3Bw5zBn4lTdO/nEW/Td4= |
| C=US/O=Amazon/CN=Amazon Root CA 2 | f0KW/FtqTjs108NpYj42SrGvOB2PpxIVM8nWxjPqJGE= |
| C=US/O=Amazon/CN=Amazon Root CA 3 | NqvDJlas/GRcYbcWE8S/IceH9cq77kg0jVhZeAPXq8k= |
| C=US/O=Amazon/CN=Amazon Root CA 4 | 9+ze1cZgR9KO1kZrVDxA4HQ6voHRCSVNz4RdTCx4U8U= |
| C=US/ST=Arizona/L=Scottsdale/O=Starfield Technologies, Inc./CN=Starfield Services Root Certificate Authority - G2 | KwccWaCgrnaw6tsrrSO61FgLacNgG2MMLq8GE6+oP5I= |
| C=US/O=Internet Security Research Group/CN=ISRG Root X1 | C5+lpZ7tcVwmwQIMcRtPbsQtWLABXhQzejna0wHFr8M= |
| C=US/O=Internet Security Research Group/CN=ISRG Root X2 | diGVwiVYbubAI3RW4hB9xU8e/CH2GnkuvVFZE8zmgzI= |
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.
vizConfirmationScreenConfiguration: n/avizResultScreenConfiguration: n/aisTouchToFocusEnabled: n/a (Android only)Properties:
applicationLevelEncryptionPins: ListaccessKey: String?backgroundTimeout: int (TimeInterval on iOS, long on Android)baseUrl: String? (called baseURL on Android)dateFormat: DateFormat enumdateSeparator: DateSeparator enuminstructionsPlayCount: intisDebugEnabled: n/a (not exposed to React Native yet)language: String?oAuthToken: String? (oauthToken on iOS)opaqueID: String?preventSessionCommit: boolreadIDSession: ReadIDSession? (Map?)readIDTracker: n/a (not supported in React Native yet)screenOrientation: ScreenOrientation enum (Map)shouldAllowScreenshots: bool (Android only)shouldAskDismissConfirmation: bool (iOS only)shouldMaskPersonalData: boolshouldOnlyShowInstructionsOnFirstUse: boolshouldUsePinning: boolcustomBundleName: String (iOS only)Properties:
allowedPageTypes: ListallowManualCaptureAfterTimeout: int (Long on iOS)faceImageFeatureRequirement: FeatureRequirement enumfastCaptureMode: boolmrzFeatureRequirement: FeatureRequirement enummrzValidation: MRZValidation enumqrCodeFeatureRequirement: FeatureRequirement enumshouldAllowLoweringQualityRequirements: boolshouldRequireNoFingerOnDocument: boolshouldRequireNoGlareOnDocument: boolshouldRequireSharpImage: boolshouldPlayShutterSound: boolshouldShowDocumentSelection: boolshouldShowTorchButton: boolshouldShowVIZConfirmation: boolshouldShowVIZResult: boolProperties:
manualInputMode: ManualInputMode enumshouldCommitSessionWithoutNFC: boolaccessControlOption: n/aallowResumeNFCReading: n/aallowSkipReadingAfterAttempts: intallowedDataGroupsToRead: List?allowedDocumentTypes: ListextendedLengthAPDUPreference: n/anfcResultScreenConfiguration: n/ashouldCommitSessionWithSkipButton: n/a (iOS only)shouldPlayShutterSound: boolshouldReadImages: boolshouldRequirePersonalNumber: boolshouldShowDocumentSelection: boolshouldShowNFCResult: boolshouldShowTorchButton: boolshouldShowVIZConfirmation: boolshouldShowVIZResult: boolProperties:
accessControlOption: AccessControlOption enumallowedDataGroupsToRead: List?allowResumeNFCReading: boolallowSkipReadingAfterAttempts: intdocumentInfo: DocumentInfo (Map, used as optional constructor parameter)extendedLengthAPDUPreference: ExtendedLengthAPDUPreference enumnfcAccessKey: NFCAccessKey (Map, used as required constructor parameter)nfcResultScreenConfiguration: NFCResultScreenConfiguration (Map)preventChipSupportDialog: boolshouldReadImages: boolshouldShowInstructionCarousel: boolshouldShowNFCResult: booltrustedCertStores: n/a (Android only)Result objects in TypeScript are read-only data objects that contain the VIZ and NFC results from a successful ReadID session.
Properties:
vizResult: VIZResult?nfcResult: NFCResult?An abstract base class that holds properties common in both VIZResult and NFCResult.
Properties:
faceImage: string? (base64)signatureImage: string? (base64)Properties
frontCaptureResult: CaptureResult?backCaptureResult: CaptureResult?nfcAccessKey: NFCAccessKey?documentInfo: DocumentInfo?nfcChipSupport: NFCChipSupport?deviceNFCLocation: DeviceNFCLocation?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 sessionsvar 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.Please read the LICENSE file before using this native module. Note that the native Android and iOS ReadID SDKs have a separate license.
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.
Security mechanism that controls who or what can read and access the contents of the chip.
An error that occurs when the NFC reading process fails due to incorrect access keys or insufficient access rights.
International Civil Aviation Organization.
A screen where users can manually enter access information if the NFC reading process fails due to an incorrect access key.
Machine Readable Travel Document that conforms to the ICAO 9303 standard.
A technology that enables short-range wireless communication between devices, often used for document reading or payments.
The part of a document, such as a passport or ID card, that contains readable personal information without the use of special technology.
A section on documents like passports that contains personal information in a format that can be read by machines using OCR (Optical Character Recognition).
FAQs
ReadID React Native
We found that readid-react-native demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 2 open source maintainers collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.