web - client-side SDKs
mobile - client-side SDKs
Authentication
Additional Checks
Developer Platform
React Native
This guide helps you to integrate the Passbase SDK into your React Native project
General
Before integrating Passbase, we suggest you read first our best practice on how to integrate Passbase in your system in the overview section and complete the initial setup steps.
You can either follow the integration guide or watch the integration tutorial that shows the same steps. Please be aware that some property or function names might have slightly changed with newer versions. Make sure to compare your implementation with the latest code snippets here in the documentation.
1. Install the Package
At the root level of your project, install the package with yarn or npm inside the terminal:
Copied!
For React Native <0.60
If your React Native version is larger than >= 0.60, you can ignore this step. Otherwise, please run the following command to link the package:
react-native link @passbase/react-native-passbaseiOS Specific Steps
Please follow these steps to complete the installation and integrate the SDK in the iOS project.
Adding Sources to Podfile
Navigate inside your iOS project folder and add the following lines at top of the Podfile. (If you don't have a Podfile yet, please create one by running the command
pod init inside the ios folder)1
source 'https://github.com/CocoaPods/Specs.git'
2
source 'https://github.com/passbase/cocoapods-specs.git'
3
source 'https://github.com/passbase/microblink-cocoapods-specs.git'
Copied!
The minimum iOS version is 11.0. Make sure to include this in the Podfile:
platform :ios, '11.0'Then, navigate inside the terminal into your project folder and run the following command to install the Passbase iOS SDK as a dependency:
pod installpod install can take longer (up to 20 minutes) depending upon the speed of your internet. You can monitor the network activity in the activity monitor.
Example of a complete Podfile
1
# Example of a Podfile
2
# 1. Add this here
3
source 'https://github.com/CocoaPods/Specs.git'
4
source 'https://github.com/passbase/cocoapods-specs.git'
5
source 'https://github.com/passbase/microblink-cocoapods-specs.git'
6
7
# 2. Add the platform requirement to at least iOS 11
8
platform :ios, '11.0'
9
require_relative '../node_modules/@react-native-community/cli-platform-ios/native_modules'
10
11
target 'ReactNativeTest' do
12
13
use_frameworks!
14
15
# Pods for ReactNativeTest
16
# ... (not all listed)
17
18
target 'ReactNativeTestTests' do
19
inherit! :search_paths
20
# Pods for testing
21
end
22
23
use_native_modules!
24
end
25
26
target 'ReactNativeTest-tvOS' do
27
# Pods for ReactNativeTest-tvOS
28
29
target 'ReactNativeTest-tvOSTests' do
30
inherit! :search_paths
31
# Pods for testing
32
end
33
34
end
Copied!
Create Objective-C Bridging if your iOS project is in Objective-C
After the pods are installed, open your project's
.xcworkspace file in Xcode. If you have an Objective-C project, add a blank Swift file to your project (File -> New -> Swift File), with a bridging header (it will prompt you to auto-create one).
1. right click on project's name directory & select new file.
2. select swift file & click next
3. give name to your file & click Create
4. select Create Bridging Header
Adding Camera Permissions in Info.plist
If you made it here, you successfully installed the Passbase SDK for iOS. Now let's adjust your last settings and start your first verification.
Please add the following permissions to your app's
Info.plist, so that the Passbase iOS SDK can access a user's camera to run a verification. You can do this in the property list view or by code.Right-click somewhere outside the table and select
Add Row. Now add the entries like below.
Or if you prefer to do this step with code, right-click on
Info.plist and select Open As -> Source Code. Add the lines below somewhere inside the <dict> </dict> 1
<!-- permission strings to be include in info.plist -->
2
<key>NSCameraUsageDescription</key>
3
<string>Please give us access to your camera, to complete the verification.</string>
4
<key>NSPhotoLibraryUsageDescription</key>
5
<string>Please give us access to your photo library to verify you.</string>
Copied!
You have successfully finished setting up the Passbase iOS SDK! 🎉
Android Specific Steps
After installing the Passbase React Native package with
yarn or npm, please complete the following steps to set up the Android environment correctly: Adding Kotlin, Maven and minSdkVersion
Note: Make sure your Android Studio also supports Kotlin. As of this writing, Android Studio Version 3.5.1 has Kotlin support. If you're using an older version, you can install Kotlin support under Android Studio → Preferences… → Plugins → Browse Repository → Type “Kotlin” in search box → Install
Kotlin support is required in the main Android project. Please add the following lines to your project's
android/build.gradle file:- 1.Set
minSdkVersionto21or higher - 2.Set
kotlin_versionto"1.3.21"or higher - 3.Add in
dependenciesthe lineclasspath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version") - 4.Add in repositories the line
maven { url 'https://button.passbase.com/__android' }
Code Example
1
// In the different lines to your projcet's build.gradle file
2
buildscript {
3
ext {
4
...
5
minSdkVersion = 21 // 1. Add minSdkVersion
6
kotlin_version = "1.3.21" // 2. Add kotlin_version
7
}
8
dependencies {
9
...
10
// 3. Add classpath
11
classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
12
}
13
}
14
15
allprojects {
16
repositories {
17
...
18
// 4. Add maven block
19
maven { url 'https://button.passbase.com/__android' }
20
}
21
}
Copied!
Sync the gradle & run. You've successfully installed the Passbase SDK for Android! 🎉
2. Initialize the SDK
Please use the publishable API key for all integrations. The secret key should never be exposed or used in a web integration or mobile app since it can access sensitive user data if leaked!
First, add the following import statement to the top of the component where you want to render Passbase:
import { PassbaseSDK } from '@passbase/react-native-passbase'Then, initialize Passbase with your own API key. You can do this via a promise like in the code snippet below, and replace
YOUR_PUBLISHABLE_API_KEY for your own publishable API key from your developer dashboard's API settings:1
const res = await PassbaseSDK.initialize('YOUR_PUBLISHABLE_API_KEY')
Copied!
You can initialize the SDK either via a promise or a callback. The methods for these two possibilities slightly differ:
Type
Method
Promise Based
initialize(publishableApiKey)Callback Based
initialize(publishableApiKey, onSuccess, onFailure)You can find an example implementation with both types below:
1
import { PassbaseSDK } from '@passbase/react-native-passbase';
2
3
// 1. promise based implementation
4
const res = await PassbaseSDK.initialize('YOUR_PUBLISHABLE_API_KEY')
5
if (res && res.success) {
6
// Do your stuff here, you have successfully initialized.
7
} else {
8
// check res.message for the error message
9
}
10
11
// 2. Callback based implementation
12
PassbaseSDK.initialize('YOUR_PUBLISHABLE_API_KEY',
13
(res) => { // it is onSuccess callback.
14
// do your stuff here.
15
},
16
(err) => { // it is onError callback
17
// oops! something went wrong. analyze `err`
18
}
19
)
Copied!
You have successfully initialized the Passbase SDK! 🎉
3. Start Verification
Keep in mind that in order to successfully finish a verification, you need to pass our liveness detection. Hence, if you develop on a Simulator (e.g. iPhone Simulator via Xcode), you won't be able to get past this step. Therefore please use a real device (e.g. an attached iPhone) to fully test and develop with our SDK.
There are two ways to start verification.
- 1.Either by using a
PassbaseButtoncomponent - 2.Or by using the
startVerificationmethod
Using a
PassbaseButton component is the simplest way to show a Passbase Button and start the verification process. The following code snippet shows how to use the PassbaseButton component inside your components render method.1
import { PassbaseButton } from '@passbase/react-native-passbase'; // import statement on top
2
3
// ...
4
render() {
5
return (
6
<PassbaseButton style={{ backgroundColor: 'white' }}/>
7
)
8
}
Copied!
If you want to make your own UI or want to start verification programmatically, you can use the
startVerification method. As previously mentioned, you can receive callbacks or you can use a promise based approach. Below are examples of how to start the verification based on promise or callback:Type
Method
Promise Based
startVerification()Callback Based
startVerification(onSuccess, onError)You can find an example implementation using both methods below:
1
import { PassbaseSDK } from '@passbase/react-native-passbase' // at the top import
2
3
// Promise based method call
4
const res = await PassbaseSDK.startVerification();
5
if (res.success) {
6
// successfully started verification.
7
}
8
9
//Callback based call
10
PassbaseSDK.startVerification((res) => {
11
if (res && res.success) {
12
// successfully started verification.
13
}
14
}, (err) => {
15
// ooops! something went wrong. analyze `err`
16
})
Copied!
Prefilling Email Addresses
If you want to automatically prefill user's email address to skip the "Approve your Email" screen. This is available programmatically if you pass the
prefillUserEmail parameter to the SDK like below. 1
PassbaseSDK.setPrefillUserEmail("[email protected]")
Copied!
Prefilling Country
You can automatically prefill user's country in the drop-down list. This is available programmatically if you pass the
prefillCountry parameter to the SDK like below. An ISO-3166 compliant country code, case insensitive. This will not enable skipping the country selection step. 1
PassbaseSDK.setPrefillCountry("de")
Copied!
Prefilling metaData
If you are tracking end users in your backend through an internal UUID, transaction number, stripe ID, etc., you can use the metaData object to securely pass encrypted end user information to identify completed verifications. The metadata object requires an encrypted JSON string via the private key encoded in base64.
Value
metaData
Encrypted JSON string via the private key encoded in base64
1
// Signed and Armored Metadata, which contain {internal_customer_id: "XYZ", "email": "[email protected]", "country": "de", ...}
2
PassbaseSDK.setMetaData("AJIZZDIZJADIOAJDOIZJAOIZJDOIAJIODZJIAJDIOZJAIOZDJALANLIKESJIZZOIZDJAOIZJDOZIAJDOIAZJDAZD")
Copied!
Add Encryption Key to your Project
Encryption should be completed on the server-side. Once you have completed the encryption, please enter the encryption keys for each individual project within the developer dashboard. The metaData object is then returned on the Passbase API.
Retrieve MetaData from Passbase API
After a user completes a verification and you receive the
VERIFICATION_REVIEWED webhook event, it is time to call the Passbase Get Identity endpoint. Using this API endpoint, you will see the new metaData object returned.If the public encryption key is not added to the developer dashboard, you will not see the metaData information returned on the API.
1
{
2
id: "1234-1234-1234-1234",
3
resources: [...],
4
metadata: { internal_customer_id: "XYZ" }
5
}
Copied!
You have successfully started your first verification! 🎉
4. Handling Verifications
Often it is useful to know if a user completes the verification or ca oOur SDK currently supports a set of customization options that will influence the appearance. To customize the verification flow, please navigate to your developer dashboard's successfully completed identity verifications from the callback method and save them to your DB e.g. a user's profilencels it. For this, you can implement the following callback methods:
Method
Description
onStartThis callback method is triggered once a user starts the verification flow.
onSubmittedonFinishonErrorThis callback method is triggered when a user canceled the verification flow or the verification finished with an error. You can use this to find out if people dropped out of your verification flow.
Error codes:
CANCELLED_BY_USER
BIOMETRIC_AUTHENTICATION_FAILEDYou can subscribe to those events like in the code example below.
1
import { NativeEventEmitter } from 'react-native';
2
import { PassbaseSDK } from '@passbase/react-native-passbase';
3
4
// now in your component's componentDidMount lifecycle method
5
componentDidMount () {
6
this.subscription = new NativeEventEmitter(PassbaseSDK);
7
8
this.subscription.addListener('onError', event => {
9
// do your stuff here
10
// event.errorCode
11
});
12
this.subscription.addListener('onFinish', event => {
13
// do your stuff here.
14
// event.identityAccessKey can be used for further interactions with passbase server
15
});
16
this.subscription.addListener('onSubmitted', event => {
17
// do your stuff here.
18
// event.identityAccessKey can be used for further interactions with passbase server
19
});
20
this.subscription.addListener('onStart', event => {
21
// do your stuff here.
22
});
23
}
24
25
// you should removeListeners on componentWillUnmout
26
componentWillUnmount(){
27
if (this.subscription) {
28
this.subscription.removeListener('onError', (event) => {})
29
this.subscription.removeListener('onFinish', (event) => {})
30
this.subscription.removeListener('onSubmitted', (event) => {})
31
this.subscription.removeListener('onStart', (event) => {})
32
}
33
}
Copied!
We recommend the following process for handling identity verifications:
- 1.Obtain the
identityAccessKey - 2.Set up webhooks to be notified once the identity verification has been processed by our system. Also once you have approved or declined the user in your dashboard
- 3.Now you can use your own backend to query the details about this identity verification with e.g. the Get Identity call to obtain the details
Identity Access Key as Reference
In order for your application to interoperate with Passbase, you should reference to your users once the Verification is completed.
For that, you will need to keep track of the identityAccessKey returned by the onFinish or onSubmitted callbacks and associate it in your backend with your end users' id. We recommend to save this key after the onSubmitted method from your user's completed verification, or listen for the incoming webhooks to make a call to the Passbase API linking back the email address of the user.
5. UI Customizations
Appearance
Our SDK currently supports a set of customization options which will influence the appearance. To customize the verification flow, please navigate to your developer dashboard's customization section. Here you can choose amongst a variety of colors, fonts, accepted countries & much more.
Customization Section
We also offer a dark mode, which will be automatically started if a user has activated this in his system settings.
Dark Mode
Language
We support a variety of different languages for the verification flow. As of this writing more than 10 including (English, Spanish, German & many more). If one is missing and you want us to add support for it, please reach out to our customer support.
The SDK automatically detects the language of the user's phone settings. If we support the language, the verification flow will be set to it. Otherwise, the default is English.
6. ProGuard (Android)
If you are using ProGuard you might need to add the following options:
1
-dontwarn okio.**
2
-dontwarn retrofit2.Platform$Java8
3
-dontwarn com.facetec.zoom.sdk.**
Copied!
to ProGuard exceptions
1
buildTypes {
2
release {
3
minifyEnabled true
4
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
5
}
6
}
Copied!
Example & Demo App
You can find a code example of a whole class in the code section below. Also, we have a full example on our Github: React Native Demo App
1
import React from 'react';
2
import { NativeEventEmitter, Platform, View, StyleSheet, TouchableOpacity, Text, Alert, ActivityIndicator } from 'react-native';
3
import { PassbaseSDK, PassbaseButton } from '@passbase/react-native-passbase';
4
class App extends React.Component {
5
constructor(props) {
6
super(props);
7
this.state = {
8
initSucceed: false,
9
loading: false
10
};
11
}
12
async componentDidMount() {
13
this.subscription = new NativeEventEmitter(PassbaseSDK);
14
this.subscription.addListener('onError', (event) => {
15
console.log("##onError##", event)
16
})
17
this.subscription.addListener('onFinish', (event) => {
18
console.log("##onFinish##", event)
19
})
20
this.subscription.addListener('onSubmitted', (event) => {
21
console.log("##onSubmitted##", event)
22
})
23
this.subscription.addListener('onStart', (event) => {
24
console.log("##onStart##", event)
25
})
26
}
27
28
handlePassbaseClick = async () => {
29
const { initSucceed, loading } = this.state
30
if (loading ) {
31
return
32
}
33
this.setState({loading: true}, async () => {
34
if (initSucceed) {
35
// Promise based method call
36
const res = await PassbaseSDK.startVerification();
37
this.setState({loading: false})
38
if (!res.success) {
39
alert('something went wrong. while starting verification.')
40
}
41
} else {
42
// promise based implementation
43
const res = await PassbaseSDK.init('YOUR_PUBLISHABLE_API_KEY')
44
console.log("initRes: ", res)
45
if (res && res.success) {
46
this.setState({initSucceed: true, loading: false})
47
}
48
}
49
})
50
}
51
52
render() {
53
const { initSucceed, loading } = this.state;
54
return (
55
<View style={styles.container}>
56
<TouchableOpacity style={styles.button}
57
onPress={this.handlePassbaseClick}>
58
<Text style={styles.btnText}>
59
{initSucceed ? 'start verification' : 'initialize SDK'}
60
</Text>
61
{
62
loading && <View style={styles.loadingContainer}>
63
<ActivityIndicator size={'large'}/>
64
</View>
65
}
66
</TouchableOpacity>
67
{
68
initSucceed && <PassbaseButton style={{ margin: 10, backgroundColor: 'white' }}/>
69
}
70
</View>
71
);
72
}
73
74
componentWillUnmount(){
75
if (this.subscription)
76
this.subscription.removeListener('onFinish', (event) => {
77
console.log("##removing listener onFinish##", event)
78
})
79
this.subscription.removeListener('onSubmitted', (event) => {
80
console.log("##removing listener onSubmitted##", event)
81
})
82
this.subscription.removeListener('onError', (event) => {
83
console.log("##removing listener onError##", event)
84
})
85
this.subscription.removeListener('onStart', (event) => {
86
console.log("##removing listener onStart##", event)
87
})
88
89
}
90
}
91
export default App;
92
93
const styles = StyleSheet.create({
94
container: {
95
width: '100%',
96
height: '100%',
97
alignItems: 'center',
98
justifyContent: 'center'
99
},
100
button: {
101
width: 250,
102
padding: 10,
103
margin: 10,
104
backgroundColor: 'blue',
105
alignItems: 'center',
106
justifyContent: 'center'
107
},
108
btnText: {
109
color: 'white',
110
fontWeight: 'bold'
111
},
112
component: {
113
width: 100,
114
height: 100,
115
margin: 5
116
},
117
loadingContainer: {
118
position: 'absolute',
119
left: 0, right: 0, top: 0, bottom: 0,
120
alignItems: 'center',
121
justifyContent: 'center'
122
}
123
});
Copied!
You have completed the integration for React Native! 🎉
Troubleshooting
ZoomAuthenticationHybrid.framework, no image present
If you experience a crash with the error, "ZoomAuthenticationHybrid.framework, no image present," please add it manually. Otherwise, skip this step.
Sometimes, there is a bug where we need to add another framework to our iOS Project. Try to build and run your project. If the above bug occurs, please download the
ZoomAuthenticationHybrid.framework from this link.Unzip the file, locate the
ZoomAuthenticationHybrid.framework file in the folder and copy it to your ios directory in the react native project. Next, open your project's xcworkspace file and drag the
ZoomAuthenticationHybrid.framework inside the left pane to your project's dependencies in XCode.
Tick the box for
Copy items if needed
Add a copy file phase to your Xcode project and have
ZoomAuthenticationHybrid.framework copied to destination FrameworksFor Xcode >= 11 only
Go to General -> Frameworks, Libraries, and Embedded Content & Select
Embed & Sign for ZoomAuthenticationHybrid.framework.
Now clean project & build & run.
Gradle sync fails with OneSignal installed
The problem is both OneSignal and Passbase are requiring different versions of some of services from
com.google.firebase & com.google.android.gms groups.Add
resolutionStrategy to the project level build.gradle inside the allProjects block as follows:1
allprojects {
2
repositories {
3
// other repositories ...
4
maven { url 'https://maven.google.com' } // THIS ONE ADDED FOR ONE-SIGNAL
5
google()
6
jcenter()
7
maven { url 'https://jitpack.io' }
8
maven { url 'https://button.passbase.com/__android' }
9
}
10
configurations.all { // THIS BLOCK ADDED FOR ONE-SIGNAL & PASSBASE CONFLICTS
11
resolutionStrategy {
12
eachDependency { DependencyResolveDetails details ->
13
if (details.requested.group == 'com.google.firebase') {
14
details.useVersion "+"
15
}
16
if (details.requested.group == 'com.google.android.gms') {
17
details.useVersion "+"
18
}
19
}
20
}
21
}
22
}
Copied!
sync the project and then build and runGradle sync fails with Intercom installed
If you have a similar error in your project:
1
Could not determine the dependencies of task ':app:lintVitalRelease'.
2
> Could not resolve all artifacts for configuration ':app:releaseAndroidTestRuntimeClasspath'.
3
> Could not resolve io.intercom.android:intercom-sdk-base:5.+.
4
Required by:
5
project :app > project :react-native-intercom
6
> Failed to list versions for io.intercom.android:intercom-sdk-base.
7
> Unable to load Maven meta-data from https://button.passbase.com/__android/io/intercom/android/intercom-sdk-base/maven-metadata.xml.
8
> Could not get resource 'https://button.passbase.com/__android/io/intercom/android/intercom-sdk-base/maven-metadata.xml'.
9
> Could not GET 'https://button.passbase.com/__android/io/intercom/android/intercom-sdk-base/maven-metadata.xml'. Received status code 403 from server: Forbidden
Copied!
A workaround may help:
1
maven {
2
url 'https://button.passbase.com/__android'
3
content {
4
excludeGroupByRegex "io\\.intercom.*"
5
}
6
}
Copied!
sync the project and then build and run Camera is not starting in release build on android
If you experience that camera is not starting in release build make sure you set enableProguardInReleaseBuilds in build.gradle to false. Or add exeptions as described in ProGuard section above.
Last modified 27d ago
Copy link
Contents
General
1. Install the Package
For React Native <0.60
iOS Specific Steps
Android Specific Steps
2. Initialize the SDK
3. Start Verification
Prefilling Email Addresses
Prefilling Country
Prefilling metaData
4. Handling Verifications
Identity Access Key as Reference
5. UI Customizations
Appearance
Language
6. ProGuard (Android)
Example & Demo App
Troubleshooting
ZoomAuthenticationHybrid.framework, no image present
Gradle sync fails with OneSignal installed
Gradle sync fails with Intercom installed
Camera is not starting in release build on android