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

Maven source was changed on the 15th of April. Make sure you are using the latest one.

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. Inside the build.gradle of Module:app level add minSdkVersion 21

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

  3. Finally, add implementation 'com.passbase:passbase_sdk:1.7.12' 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:1.7.12'
}

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.Passbase
import com.passbase.passbase_sdk.PassbaseButton
Java
import com.passbase.passbase_sdk.Passbase;
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.Passbase
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 = Passbase(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.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);
// 2. Initialize object here with own API key
final Passbase passbaseRef = new Passbase(this);
// 2. You can add the prefill email option here
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"",
new Pair[]{}
);
}
}

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.Passbase
import com.passbase.passbase_sdk.PassbaseButton
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val passbaseRef = Passbase(this)
// 2. You can add the prefill email option here (optional)
passbaseRef.initialize("YOUR_PUBLISBALE_API_KEY",
"testuser@yourdomain.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 Passbase(this);
// 2. You can add the prefill email option here
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"testuser@yourdomain.com",
new Pair[]{}
);
}
}

Sending AdditionalAttributes

You can pass additional attributes with the additionalAttributes object (e.g.

Kotlin
Java
Kotlin
additionalAttributes = arrayOf(Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x"))
Java
Pair<String, String>[] additionalAttributes = new Pair[]{new Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x")};
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.Passbase
import com.passbase.passbase_sdk.PassbaseButton
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
// 2. Initialize with own API key, prefill & additional attributes
val passbaseRef = Passbase(this)
additionalAttributes = arrayOf(Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x"))
passbaseRef.initialize(
"YOUR_API_KEY",
prefillUserEmail = "testuser@passbasecom", // optional
additionalAttributes = additionalAttributes) // optional
}
}
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 Passbase(this);
final Pair<String, String>[] additionalAttributes = new Pair[]{new Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x")};
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"testuser@yourdomain.com",
additionalAttributes
);
}
}

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 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 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 the two delegate/callback methods:

Method

Description

onCompletePassbase

This callback method activates once a user completes the full verification flow. You receive an object called authKey in order to track the status of this verification. Please see our section about Webhooks and API for that.

onCancelPassbase

This callback method activates if a user cancels the verification flow. You can use this to see if people drop out of your verification flow.

We also recommend adding this to your setOnClickListener method.

Kotlin
Java
Kotlin
val passbaseRef = Passbase(this)
// Add here the callbacks
passbaseRef.onCompletePassbaseVerification { authKey ->
println("MainActivity onCompletePassbase $authKey")
}
passbaseRef.onCancelPassbaseVerification {
println("MainActivity onCancelPassbase")
}
Java
final Passbase passbaseRef = new Passbase(this);
// Add here the callbacks
passbaseRef.onCancelPassbaseVerification(new Function0<Unit>() {
@Override
public Unit invoke() {
println("MainActivity onCancelPassbase");
return null;
}
});
passbaseRef.onCompletePassbaseVerification(new Function1<String, Unit>() {
@Override
public Unit invoke(String authKey) {
println("MainActivity onCompletePassbase: " + 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

We offer a variety of UI customizations for the button and other elements. For example, you can customize the color of the progress bar, button and different fonts. You can set these customizations either in the XML or call them on the button object itself.

UI Changes to the Button's Appearance

This customizations need to be called on the button object. verificationButton or the XML in our example.

If you want to change the appearance of the button itself, you either directly set changes in the XML with app:backgroundColor="@android:color/white" and app:textColor="@android:color/black". Compare line 5 and 6 of the example below.

Attribute

Description

backgroundColor

This is the background color of the button. The default is set to white.

textColor

This is the text color of the button. The default is set to black.

Example:

<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" />

Or, you can change it programmatically on the button object. We recommend doing this at the top, after the initialization.

Attribute

Description

setBackgroundColor

This is the background color of the button. The default is set to white.

setTextColor

This is the text color of the button. The default is set to black.

Kotlin
Java
Kotlin
// ...
class MainActivity : AppCompatActivity() {
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
setContentView(R.layout.activity_main)
val passbaseRef = Passbase(this)
passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY")
// Finds the button and applies changes to it
val verificationButton = findViewById<PassbaseButton>(R.id.passbaseVerificationButton)
verificationButton.setBackgroundColor(Color.WHITE)
verificationButton.setTextColor(Color.BLACK)
// ...
}
}
Java
// ...
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
final Passbase passbaseRef = new Passbase(this);
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"",
new Pair[]{}
);
// Finds the button and applies changes to it
PassbaseButton verificationButton = this.findViewById(R.id.passbaseVerificationButton);
verificationButton.setBackgroundColor(Color.WHITE);
verificationButton.setTextColor(Color.BLACK);
// ...
}

UI Changes within the flow

This customizations need to be called on the passbase reference. passbaseRef in our example.

Attribute

Description

setLoadingIndicatorColor

This is the background color of the loading animation. The default is set to blue.

setActionButtonBgColor

This is the background color of the action button. The default is set to blue.

setActionButtonDeactivatedBgColor

This is the background color of the deactivated action button. The default is set to a lighter blue or lighter color from setActionButtonBgColor.

setActionButtonTextColor

This is the text color of the action button. The default is set to a lighter white.

setDisclaimerTextColor

This is the text color of the disclaimer, that the users agree to. The default is set to gray.

setTitleTextColor

This is the text color of the title. The default is set to black.

setSubtitleTextColor

This is the text color of the sub title. The default is set to black.

setTheme

This is the color scheme setting. The default is set to Passbase.THEME_DARK_OFF. To enable dark theme use Passbase.THEME_DARK_ON

Customizations must be set before calling startVerification()

If you'd like to change the color of the progress bar and action button, or the font of the flow, you can use the example code below before starting the flow:

Kotlin
Java
Kotlin
// 1. You initialized it somewhere
val passbaseRef = Passbase(this)
passbaseRef.initialize("YOUR_API_KEY")
// 2. You call customizations on it
passbaseRef.setLoadingIndicatorColor(Color.RED)
passbaseRef.setActionButtonBgColor(Color.BLACK)
passbaseRef.setActionButtonDeactivatedBgColor(Color.DKGRAY)
passbaseRef.setActionButtonTextColor(Color.WHITE)
passbaseRef.setTitleTextColor(Color.GRAY)
passbaseRef.setSubtitleTextColor(Color.LTGRAY)
passbaseRef.setDisclaimerTextColor(Color.GRAY)
//2.1 Enable dark theme
pasbaseRef.setTheme(Passbase.THEME_DARK_ON)
// 3. Later call start verification on a button
val verificationButton = findViewById<PassbaseButton>(R.id.passbaseVerificationButton)
verificationButton.setOnClickListener {
passbaseRef.startVerification()
}
Java
// 1. You initialized it somewhere
final Passbase passbaseRef = new Passbase(this);
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"",
new Pair[]{}
);
// 2. You call customizations on it
passbaseRef.setLoadingIndicatorColor(Color.RED);
passbaseRef.setActionButtonBgColor(Color.BLACK);
passbaseRef.setActionButtonDeactivatedBgColor(Color.DKGRAY);
passbaseRef.setActionButtonTextColor(Color.WHITE);
passbaseRef.setTitleTextColor(Color.GRAY);
passbaseRef.setSubtitleTextColor(Color.LTGRAY);
passbaseRef.setDisclaimerTextColor(Color.GRAY);
//2.1 Enable dark theme
pasbaseRef.setTheme(Passbase.THEME_DARK_ON);
// 3. Later call start verification on a button
PassbaseButton verificationButton = this.findViewById(R.id.passbaseVerificationButton);
verificationButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
passbaseRef.startVerification();
}
});

Customization Example

Both customizations (the verification flow and the button appearance) are implemented in the code below:

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 = Passbase(this)
passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY")
// Handling verifications via callbacks
passbaseRef.onCompletePassbaseVerification { authKey ->
println("MainActivity onCompletePassbase $authKey")
}
passbaseRef.onCancelPassbaseVerification {
println("MainActivity onCancelPassbase")
}
// UI changes of the button flow
passbaseRef.setLoadingIndicatorColor(Color.RED)
passbaseRef.setActionButtonBgColor(Color.BLACK)
passbaseRef.setActionButtonDeactivatedBgColor(Color.DKGRAY)
passbaseRef.setActionButtonTextColor(Color.WHITE)
passbaseRef.setTitleTextColor(Color.GRAY)
passbaseRef.setSubtitleTextColor(Color.LTGRAY)
passbaseRef.setDisclaimerTextColor(Color.GRAY)
passbaseRef.setTheme(Passabase.THEME_DARK_ON)
// UI Button Appearances Changes
val verificationButton = findViewById<PassbaseButton>(R.id.passbaseVerificationButton)
verificationButton.setBackgroundColor(Color.BLUE)
verificationButton.setTextColor(Color.WHITE)
verificationButton.setOnClickListener {
passbaseRef.startVerification()
}
}
}
Java
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;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
final Passbase passbaseRef = new Passbase(this);
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"",
new Pair[]{}
);
// Handling verifications via callbacks
passbaseRef.onCancelPassbaseVerification(new Function0<Unit>() {
@Override
public Unit invoke() {
println("MainActivity onCancelPassbase");
return null;
}
});
passbaseRef.onCompletePassbaseVerification(new Function1<String, Unit>() {
@Override
public Unit invoke(String authKey) {
println("MainActivity onCompletePassbase: " + authKey);
return null;
}
});
// UI changes of the button flow
passbaseRef.setLoadingIndicatorColor(Color.RED);
passbaseRef.setActionButtonBgColor(Color.BLACK);
passbaseRef.setActionButtonDeactivatedBgColor(Color.DKGRAY);
passbaseRef.setActionButtonTextColor(Color.WHITE);
passbaseRef.setTitleTextColor(Color.GRAY);
passbaseRef.setSubtitleTextColor(Color.LTGRAY);
passbaseRef.setDisclaimerTextColor(Color.GRAY);
passbaseRef.setTheme(Passbase.THEME_DARK_ON);
// UI Button Appearances Changes
PassbaseButton verificationButton = this.findViewById(R.id.passbaseVerificationButton);
verificationButton.setBackgroundColor(Color.BLUE);
verificationButton.setTextColor(Color.WHITE);
verificationButton.setOnClickListener(new View.OnClickListener() {
@Override
public void onClick(View view) {
passbaseRef.startVerification();
}
});
}
}

Example & Demo App

A full code example for a basic integration can be found below. It has the following additions:

  • Passes an additional attribute in line 19

You can also 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 = Passbase(this)
// Additional attributes set
val additionalAttributes = arrayOf(
Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x")
)
// Initialization, prefilled email & additional attributes
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"testuser@yourdomain.com"
additionalAttributes = additionalAttributes) // optional parameter
// Handling verifications via callbacks
passbaseRef.onCompletePassbaseVerification { authKey ->
println("MainActivity onCompletePassbase $authKey")
}
passbaseRef.onCancelPassbaseVerification {
println("MainActivity onCancelPassbase")
}
verificationButton.setOnClickListener {
passbaseRef.startVerification()
}
}
}
Java
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;
public class MainActivity extends AppCompatActivity {
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
final Passbase passbaseRef = new Passbase(this);
// Additional attributes set
final Pair<String, String>[] additionalAttributes = new Pair[]{
new Pair("userId", "a2ab4-f2jc4-k2dd4-1fa3x")
};
// Initialization, prefilled email & additional attributes
passbaseRef.initialize(
"YOUR_PUBLISHABLE_API_KEY",
"testuser@yourdomain.com",
additionalAttributes);
// Handling verifications via callbacks
passbaseRef.onCancelPassbaseVerification(new Function0<Unit>() {
@Override
public Unit invoke() {
println("MainActivity onCancelPassbase");
return null;
}
});
passbaseRef.onCompletePassbaseVerification(new Function1<String, Unit>() {
@Override
public Unit invoke(String authKey) {
println("MainActivity onCompletePassbase: " + 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.