Android

This guide helps you to integrate the Passbase SDK into your native Android project

General

Before integrating Passbase, you need to sign up on our developer dashboard. The integration of the Passbase Android SDK follows a few simple steps:

  1. Install the SDK

  2. Initialization of the SDK with your API key

  3. Start a new verification process from a button

  4. Handling verifications

  5. UI Customizations

We suggest you follow our best practice how to integrate Passbase in your wider system in the overview section.

1. Install as a Gradle Plugin

Installing the Passbase Android library is as easy as using Android Studio and IntelliJ. You don’t need to clone a repo or download any files. Just add the following to your project’s build.gradle file:

  1. Please use minSdkVersion 21 in your build.gradle (Module:app)

  2. Add maven {url 'https://button.passbase.com/__android'} to your repositories part

  3. Finally, add implementation 'com.passbase:passbase_sdk:2.0.5' to your dependencies.

A complete build.gradlefile would look something like the example below. Now sync your build.gradle file to install the SDK.

android {
// 1. Ensure you have hat least minSdkVersion 21
compileSdkVersion 29
defaultConfig {
applicationId "com.passbase.passbaseexample"
mindSdkVersion 21
targetSdkVersion 29
versionCode 1
versionName "1.0"
}
}
repositories {
// 2. Add line here
maven { url 'https://button.passbase.com/__android' }
}
dependencies {
...
// 3. Add line here
implementation 'com.passbase:passbase_sdk:2.0.3'
}

You have successfully installed the Passbase SDK!🎉

2. Initialize the SDK

Please only 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 to sensitive user data if leaked!

Passbase uses API keys to allow access to the SDK and to route it back to your dashboard. You need to register on our website and use your publishable API key from your developer dashboard's API settings. If you don't have a developer account yet, you can create one here: developer dashboard.

Open your MainActivity in your directory. This was created through the previous step. It will be called something similar to, MainActivity

Add the two import statements to the top of the file:

Kotlin
Java
Kotlin
import com.passbase.passbase_sdk.PassbaseSDK
import com.passbase.passbase_sdk.PassbaseButton
Java
import com.passbase.passbase_sdk.PassbaseSDK;
import com.passbase.passbase_sdk.PassbaseButton;

After that, your need to initialize the SDK. You need to replace YOUR_PUBLISHABLE_API_KEY with your own publishable API key from your developer dashboard's API settings.

You can find a coding example here:

Kotlin
Java
Kotlin
package com.passbase.androiddemoapp
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
// 1. Add import of Passbase SDK and the Passbase Button to the top
import com.passbase.passbase_sdk.PassbaseSDK
import com.passbase.passbase_sdk.PassbaseButton
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// 2. Initialize object here with own API key
val passbaseRef = PassbaseSDK(this)
passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY")
}
}
Java
package com.passbase.androiddemoapp;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
// 1. Add import of Passbase SDK and the Passbase Button to the top
import com.passbase.passbase_sdk.PassbaseSDK;
import com.passbase.passbase_sdk.PassbaseButton;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
// 2. Initialize object here with own API key
final Passbase passbaseRef = new PassbaseSDK(this);
passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
}
}

Prefilling email address

If you want to automatically prefill user email addresses, you can to skip the "Approve your Email" screen. This is possible by simply passing the email address into the initialization method.

Kotlin
Java
Kotlin
package com.passbase.androiddemoapp
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
// 1. Add import of Passbase SDK and the Passbase Button to the top
import com.passbase.passbase_sdk.PassbaseSDK
import com.passbase.passbase_sdk.PassbaseButton
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val passbaseRef = PassbaseSDK(this)
passbaseRef.initialize("YOUR_PUBLISBALE_API_KEY")
// 2. You can add the prefill email option here (optional)
passbaseRef.prefillUserEmail = "testuser@yourproject.com";
}
}
Java
package com.passbase.androiddemoapp;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
// 1. Add import of Passbase SDK and the Passbase Button to the top
import com.passbase.passbase_sdk.Passbase;
import com.passbase.passbase_sdk.PassbaseButton;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
final Passbase passbaseRef = new PassbaseSDK(this);
passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
// 2. You can add the prefill email option here
passbaseRef.prefillUserEmail = "testuser@yourproject.com";
}
}

You have successfully initialized the Passbase SDK in your Android App! 🎉

3. Start the Verification

To start a new verification, you first need to create a verification button. Please ensure that you added both import statements to the top of your file from step 2. You can now do this in two ways:

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. Simulator via Android Studio), you won't be able to get past this step. Therefore please use a real device (e.g. an attached Android phone) to fully test and develop with our SDK.

Add Passbase Button via Layout / XML

You can create a stylized Passbase button via XML layout like this and give it an id in order to find it later.

<com.passbase.passbase_sdk.PassbaseButton
android:id="@+id/passbaseVerificationButton"
android:layout_width="250dp"
android:layout_height="56dp"
android:layout_marginStart="80dp"
android:layout_marginTop="336dp"
app:backgroundColor="@android:color/white"
app:textColor="@android:color/black"
app:layout_constraintStart_toStartOf="parent"
app:layout_constraintTop_toTopOf="parent"/>

Add Passbase Button Programmatically

Or you can create a button programmatically, apply constraints and add it to your view like this.

Kotlin
Java
Kotlin
val verificationButton = PassbaseButton(YOUR_CONTEXT)
Java
PassbaseButton verificationButton = new PassbaseButton(this);

Afterwards a button like this should render in your view.

Start

To start a verification, you can call the startVerification() method. We suggest doing this with an setOnClickListener

Kotlin
Java
Kotlin
val verificationButton = findViewById<PassbaseButton>(R.id.passbaseVerificationButton)
verificationButton.setOnClickListener {
passbaseRef.startVerification()
}
Java
PassbaseButton verificationButton = this.findViewById(R.id.passbaseVerificationButton);
verificationButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
passbaseRef.startVerification();
}
});

PassbaseButton inherits from LinearLayout and you can use all the methods that you would usually use for that. Don't forget to add import android.widget.LinearLayout to the top then.

You have successfully started your first verification. 🎉

4. Handling Verifications

In some cases it's useful to know if a users completes the verification or cancels it. For this, we can implement following delegate/callback methods:

Method

Description

onStart

This callback method activates once a user starts the verification flow.

onFinish

This callback method activates once a user completes the full verification flow. You receive an object called identityAccessKey which can be used to access the identity. Please see our section about Webhooks and API for more information.

onError

This callback method activates when a user cancels the verification flow or verification finish with an error. You can use this to find out if people who drop out of your verification flow.

Error codes:

CANCELLED_BY_USER REAUTHENTICATION_FAILED

We also recommend adding this to your setOnClickListener method.

Kotlin
Java
Kotlin
val passbaseRef = PassbaseSDK(this)
// Add here the callbacks
passbaseRef.onFinish { identityAccessKey ->
println("MainActivity onFinish $identityAccessKey")
}
passbaseRef.onError { errorCode ->
println("MainActivity onError $errorCode")
}
passbaseRef.onStart {
println("MainActivity onStart")
}
Java
final Passbase passbaseRef = new PassbaseSDK(this);
// Add here the callbacks
passbaseRef.onError(new Function0<String, Unit>() {
@Override
public Unit invoke(String errorCode) {
println("MainActivity onError: " + errorCode);
return null;
}
});
passbaseRef.onFinish(new Function1<String, Unit>() {
@Override
public Unit invoke(String identityAccessKey) {
println("MainActivity onFinish: " + identityAccessKey);
return null;
}
});
passbaseRef.onStart(new Function2<String, Unit>() {
@Override
public Unit invoke(String authKey) {
println("MainActivity onStart: " + authKey);
return null;
}
});

We recommend the following process for handling identity verifications:

  1. Obtain the authKey of a successful identity verifications from the call back and save them to e.g. a user profile

  2. Set up webhooks to be notified once the identity verification has been processed by our system. Also once your have approved or rejected the user in our dashboard

  3. Now you can use your own backend to query the details about this identity verification with e.g. the authentication by key call to obtain the details

5. UI Customizations

No code solution allows you to change font and colors online without rebuilding your app.

6. ProGuard

If you are using ProGuard you might need to add the following options:

-dontwarn okio.**
-dontwarn retrofit2.Platform$Java8
-dontwarn com.facetec.zoom.sdk.**

to ProGuard exceptions

buildTypes {
release {
minifyEnabled true
proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
}
}

Example & Demo App

A full code example for a basic integration can be found below. You can find a demo integration showing how to integrate the Passbase SDK for Android on our Github page.

Android Demo App

Kotlin
Java
Kotlin
package com.passbase.androiddemoapp
import androidx.appcompat.app.AppCompatActivity
import android.os.Bundle
import com.passbase.passbase_sdk.Passbase
import com.passbase.passbase_sdk.PassbaseButton
import android.graphics.Color
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val passbaseRef = PassbaseSDK(this)
// Initialization and prefilled email
passbaseRef.onFinish { identityAccessKey ->
println("MainActivity onFinish $identityAccessKey")
}
passbaseRef.onError { errorCode ->
println("MainActivity onError $errorCode")
}
passbaseRef.onStart {
println("MainActivity onStart")
}
verificationButton.setOnClickListener {
passbaseRef.startVerification()
}
}
}
Java
package com.passbase.androiddemoapp;
import androidx.appcompat.app.AppCompatActivity;
import android.os.Bundle;
import com.passbase.passbase_sdk.PassbaseSDK;
import com.passbase.passbase_sdk.PassbaseButton;
import android.graphics.Color;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
final Passbase passbaseRef = new PassbaseSDK(this);
// Initialization
passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
//prefilled email (optional)
passbaseRef.prefillUserEmail = "testuser@yourproject.com";
// Handling verifications via callbacks
passbaseRef.onError(new Function0<String, Unit>() {
@Override
public Unit invoke(String errorCode) {
println("MainActivity onError: " + errorCode);
return null;
}
});
passbaseRef.onFinish(new Function1<String, Unit>() {
@Override
public Unit invoke(String identityAccessKey) {
println("MainActivity onFinish: " + identityAccessKey);
return null;
}
});
passbaseRef.onStart(new Function2<String, Unit>() {
@Override
public Unit invoke(String authKey) {
println("MainActivity onStart: " + authKey);
return null;
}
});
verificationButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
passbaseRef.startVerification();
}
});
}
}

You have finished the integration of Passbase for Android! 🎉

Troubleshooting

Camera is not starting in release build

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.