Getting started: React Native (Validations plugin)
Introduction
The Truora React Native plugin allows you to integrate identity verification features directly into your React Native mobile applications. The plugin bridges to native implementations on both Android and iOS platforms, handling the complexity of capturing the user’s identity documents, facial recognition, and liveness detection to verify their identity against backend records.
Requirements
Platform Requirements
-
React Native: 0.70.0 or higher (New Architecture supported)
-
TypeScript: 5.0 or higher (recommended)
-
Android: API Level 21 (Android 5.1) or higher
-
iOS: 13.0 or higher
Permissions Required
-
Camera access for document and face capture
-
Internet access for API communication
Expo Compatibility
This plugin requires native code and is not compatible with Expo Go. If your project uses Expo, you can use EAS Build to create development and production builds that include native modules.
Android Setup
The Android SDK uses the Activity Result API to handle native validation flows. This requires initialization in your MainActivity before the activity reaches the STARTED lifecycle state. Without this step, the SDK will reject configuration calls at runtime.
Add the following to your MainActivity.kt:
Note:
TruoraValidationsSdkModule.init(this)must be called insideonCreate(). The underlyingregisterForActivityResult()API requires registration before the activity reachesSTARTED, so calling it later (e.g., inonResume) will not work.
Prerequisites & Authentication
The Key Provider Interface
To prevent hardcoding sensitive logic, you must implement the TruoraAPIKeyGetter interface in your code. This allows you to retrieve the temporary generated API key from a secure location (like a compiled secret, a secure storage enclave, or an obfuscated string). This interface is how the sdk will get access to the api key for the validations, the resulting api key must be of type ‘sdk’ (temporary), any other key type will result in an error.
Sample Typescript Implementation
Configuration Options
Before implementing validations, let’s understand the available configuration options.
Using custom validation config and UI config is optional when building the validation:
- If no
uiConfigis provided then the validation view will show the standard Truora branding, logo and colors - If no
validationConfigis provided then default values will be applied like:- No waiting for validation results before finishing the validation process for the user
autocaptureof face/doc when it’s detected will beon
More indepth information on the validation configuration options, such as similarity threshold, can be found in the official validations api documentation
User ID
The userId parameter is crucial for initializing the Truora SDK. It provides a unique identifier for the user undergoing the validation process.
-
Purpose: The
userIdallows Truora to associate validation attempts and reference data (like previously captured reference faces) with a specific user in your system. It is mandatory for linking the validation results to your user base. -
Best Practice: This ID should be an immutable, non-sensitive identifier from your database (e.g., a UUID or internal user ID) that uniquely identifies the person. Do not use sensitive PII like an email address or national ID number as the
userId.
Language
The language parameter allows you to define the localization of the text and instructions displayed within the validation view.
-
Customization: By setting the language, you ensure a user-friendly experience by presenting instructions and feedback in the user’s preferred language.
-
Available Options: The SDK supports several languages. You should provide the language code as a two-letter string (e.g., “es” for Spanish, “en” for English, “pt” for Portuguese). If no language is provided, the SDK will typically default to English or attempt to use the device’s system language, though providing an explicit language is recommended.
Example in Initialization:
Face Validation Configuration
The FaceValidationConfig allows you to customize face capture and validation behavior:
Configuration Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
| type | ValidationType | - | Always Face for face validation. Required. |
| useAutocapture | bool | true | Automatically capture when face is properly detected |
| similarityThreshold | double | 0.8 | Minimum similarity score required (0.0 - 1.0) |
| timeout | int | 60 | Maximum time in seconds for the validation |
| waitForResults | bool | false | Wait for API response before closing the view and show results to the user |
| referenceFace | ReferenceFace | null | Optional reference image for comparison |
Document Validation Configuration
The DocumentValidationConfig allows you to customize document capture:
Configuration Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
| type | ValidationType | - | Always Document for document validation. Required. |
| country | Country | null | Country code for document validation (if not set, user selects) |
| documentType | DocumentType | null | Type of document (if not set, user selects) |
| useAutocapture | bool | true | Automatically capture when document is detected |
| timeout | int | 90 | Maximum time in seconds for the validation |
| waitForResults | bool | false | Wait for API response before closing the view and show results to the user |
Available Countries and Document Types:
| Country | Code | Supported Document Types |
|---|---|---|
| Argentina | Country.ar | nationalId |
| Brazil | Country.br | cnh, generalRegistration |
| Chile | Country.cl | nationalId, foreignId, driverLicense, passport |
| Colombia | Country.co | nationalId, foreignId, rut, ppt, passport, identityCard, temporaryNationalId |
| Costa Rica | Country.cr | nationalId, foreignId |
| El Salvador | Country.sv | nationalId, foreignId, passport |
| Mexico | Country.mx | nationalId, foreignId, passport |
| Peru | Country.pe | nationalId, foreignId |
| Venezuela | Country.ve | nationalId |
| All | Country.all | passport |
Understanding SDK Results
Before implementing validations, it’s important to understand what results you’ll receive and how to handle them.
The SDK returns a TruoraValidationResult which can be:
- completed: Validation process finished (contains ValidationResult)
- canceled: Validation process canceled by the user (could contain ValidationResult)
- error: SDK error occurred (contains TruoraException)
Validation Result Object
The plugin returns ValidationResult objects with the following structure:
Validation Statuses
| Status | Description | When it occurs |
|---|---|---|
| ValidationStatus.success | Validation passed | User successfully passed the validation |
| ValidationStatus.failure | Validation failed | User did not pass the validation criteria |
| ValidationStatus.pending | Awaiting processing | Validation is being process |
TruoraException Types
When the SDK returns failed, the error can be one of three types:
| Exception Type | Description |
|---|---|
| TruoraException.sdk | Internal SDK error (configuration, permissions, user actions) |
| TruoraException.validationApi | Error from the Truora Validation API |
| TruoraException.network | Network connectivity error |
Common SDK Error Types (SDKErrorType):
| Error Type | Code | Description |
|---|---|---|
| cameraPermissionError | 20011 | Camera permission was denied |
| invalidApiKey | 20017 | API key is invalid or expired |
| invalidConfiguration | 20024 | SDK configuration is invalid |
| networkError | 20025 | Network connection failed |
| uploadFailed | 20026 | Failed to upload captured media |
Handling Example
Implementation
Now that you understand configurations and result handling, let’s implement validations.
Basic Face Validation
Here’s a complete example of implementing face validation in React Native:
Document Validation
For document validation, use the DocumentValidationConfig:
Troubleshooting
Common Issues
-
Camera not working on Android
Solution: Verify that camera permissions are added to AndroidManifest.xml and that the user has granted permission at runtime. -
Build fails on iOS
Solution: Run cd ios && pod install and ensure your iOS deployment target is set to 13.0 or higher in both Podfile and Xcode project settings. -
“API Key Invalid" error
Solution: Verify your API key is correct and has the proper grants (sdk type). Check that it hasn’t expired. -
Validation timeout in completed results
Solution: Increase the timeout value in the config, or ensure the device has a stable internet connection.