React Native SDK Guide
The prembly-react-native-kyc package provides native UI components and modal workflows for integrating identity verification, document scanning, and face liveness checks directly into iOS and Android applications.
Installation
Install the main SDK package alongside its peer dependency react-native-webview:
npm install prembly-react-native-kyc react-native-webview
# or
yarn add prembly-react-native-kyc react-native-webviewFor iOS builds, install CocoaPods dependencies:
cd ios && pod install && cd ..Native Camera Permissions Setup
Because identity verification and liveness challenges require access to the device camera, you must request camera permissions in your native configuration files.
iOS Configuration (ios/Podfile & Info.plist)
Add NSCameraUsageDescription to your ios/YourAppName/Info.plist:
<key>NSCameraUsageDescription</key>
<string>This app requires access to the camera to verify your identity documents and face liveness.</string>Android Configuration (android/app/src/main/AndroidManifest.xml)
Add the camera permission to android/app/src/main/AndroidManifest.xml:
<uses-permission android:name="android.permission.CAMERA" />Android Runtime Permissions (API Level 23+)
On Android devices running API level 23 or higher, ensure your application requests runtime camera permission before launching the SDK modal.
Basic Implementation (PremblyIdentityWidget)
Use the <PremblyIdentityWidget /> component to render the verification flow in a native webview modal:
import React, { useState } from 'react';
import { Button, View, StyleShet, Text } from 'react-native';
import { PremblyIdentityWidget } from 'prembly-react-native-kyc';
export default function IdentityScreen() {
const [visible, setVisible] = useState(false);
const [status, setStatus] = useState<string | null>(null);
return (
<View style={styles.container}>
<Button title="Start Identity Verification" onPress={() => setVisible(true)} />
{status && <Text style={styles.statusText}>Result: {status}</Text>}
<PremblyIdentityWidget
isVisible={visible}
widgetKey="your_public_widget_key_here"
widgetId="your_widget_id_here"
firstName="John"
lastName="Doe"
email="john@example.com"
phone="+2348012345678"
metadata={{
user_id: 'usr_123456',
app_version: '1.0.0'
}}
callback={(response) => {
console.log('React Native Callback:', response);
setStatus(response.status);
if (
response.status === 'success' ||
response.status === 'closed' ||
response.status === 'error_display_closed'
) {
setVisible(false);
}
}}
/>
</View>
);
}
const styles = StyleSheet.create({
container: { flex: 1, justifyContent: 'center', alignItems: 'center', padding: 20 },
statusText: { marginTop: 20, fontSize: 16, fontWeight: 'bold' }
});Component Props Reference
| Prop Name | Type | Required | Description |
|---|---|---|---|
isVisible | Boolean | Yes | Controls the visibility of the native verification modal wrapper. |
widgetKey | String | Yes | Your public API key from the Prembly dashboard. |
widgetId | String | Yes | The verification workflow configuration ID created in your dashboard. |
email | String | No | Pre-fills the user's email address. |
firstName | String | No | Pre-fills the user's first name. |
lastName | String | No | Pre-fills the user's last name. |
phone | String | No | Pre-fills the user's phone number. |
metadata | Object | No | Custom JSON object passed back in verification callbacks & webhooks. |
callback | Function | Yes | Callback function executed when verification completes or closes. |
Face Liveness Biometric Challenge
To require biometric face verification against a stored user photo or reference document image, pass the compare_image property inside your metadata object:
<PremblyIdentityWidget
isVisible={visible}
widgetKey="your_public_widget_key_here"
widgetId="your_widget_id_here"
metadata={{
user_id: 'usr_123',
email: 'john@example.com',
compare_image: 'https://your-server.com/path-to-reference-image.jpg' // Or Base64 string
}}
callback={(response) => {
if (response.status === 'success') {
console.log('Liveness confidence score:', response.data?.liveness_score);
}
setVisible(false);
}}
/>Troubleshooting (React Native)
- Blank White Screen in Modal: Ensure
react-native-webviewis correctly installed and native project files were rebuilt (npx react-native run-android/npx react-native run-ios). - Camera Fails to Open: Check native logs (
adb logcator Xcode Console) to ensureNSCameraUsageDescriptionandandroid.permission.CAMERAare configured.