Android

General
Before you start integrating Passbase, we suggest you read first our Overview & Integration Guide on how to integrate Passbase in your system 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 Gradle Plugin
To install the Passbase Android SDK,  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.9.1' to your dependencies.
A complete build.gradlefile should look similar to the example below. Now sync your build.gradle file to install the SDK.
1
android {
2
  // 1. Ensure you have hat least minSdkVersion 21
3
  compileSdkVersion 30
4
  defaultConfig {
5
    applicationId "com.passbase.passbaseexample"
6
    mindSdkVersion 21
7
    targetSdkVersion 30
8
    versionCode 1
9
    versionName "1.0"
10
  }
11
}
12
​
13
​
14
repositories {
15
  // 2. Add line here
16
  maven { url 'https://button.passbase.com/__android' }
17
}
18
​
19
dependencies {
20
  ... 
21
  // 3. Add line here  
22
  implementation 'com.passbase:passbase_sdk:2.9.1'
23
}
24
​
Copied!
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 sensitive user data if leaked!
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
1
import com.passbase.passbase_sdk.PassbaseSDK
2
import com.passbase.passbase_sdk.PassbaseButton
Copied!
1
import com.passbase.passbase_sdk.PassbaseSDK;
2
import com.passbase.passbase_sdk.PassbaseButton;
Copied!
After that, your need to initialize the SDK with your own publishable API key from your developer dashboard's API settings. See YOUR_PUBLISHABLE_API_KEY in the coding example below:
Kotlin
Java
1
package com.passbase.androiddemoapp
2
​
3
import androidx.appcompat.app.AppCompatActivity
4
import android.os.Bundle
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.PassbaseSDK
8
import com.passbase.passbase_sdk.PassbaseButton
9
​
10
class MainActivity : AppCompatActivity() {
11
​
12
    override fun onCreate(savedInstanceState: Bundle?) {
13
        super.onCreate(savedInstanceState)
14
        setContentView(R.layout.activity_main)
15
​
16
        // 2. Initialize object here with own API key
17
        val passbaseRef = PassbaseSDK(this)
18
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY")
19
    }
20
}
21
​
Copied!
1
package com.passbase.androiddemoapp;
2
​
3
import androidx.appcompat.app.AppCompatActivity;
4
import android.os.Bundle;
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.PassbaseSDK;
8
import com.passbase.passbase_sdk.PassbaseButton;
9
​
10
public class MainActivity extends AppCompatActivity {
11
​
12
    @Override
13
    protected void onCreate(Bundle savedInstanceState) {
14
        super.onCreate(savedInstanceState);
15
        setContentView(R.layout.activity_main);
16
        
17
        // 2. Initialize object here with own API key
18
        PassbaseSDK passbaseRef = new PassbaseSDK(this);
19
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
20
    }
21
}
Copied!
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 will only see the SDK in UI demo mode. Therefore please use a real device (e.g. an attached Android phone) to fully test and develop with our SDK.
Add 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.
1
<com.passbase.passbase_sdk.PassbaseButton
2
   android:id="@+id/passbaseVerificationButton"
3
   android:layout_width="250dp"
4
   android:layout_height="56dp"
5
   android:layout_marginStart="80dp"
6
   android:layout_marginTop="336dp"
7
   app:backgroundColor="@android:color/white"
8
   app:textColor="@android:color/black"
9
   app:layout_constraintStart_toStartOf="parent"
10
   app:layout_constraintTop_toTopOf="parent"/>
Copied!
Add Button Programmatically
Or you can create a button programmatically, apply constraints and add it to your view like this.
Kotlin
Java
1
val verificationButton = PassbaseButton(YOUR_CONTEXT)
Copied!
1
PassbaseButton verificationButton = new PassbaseButton(this);
Copied!
Afterwards a button like this should render in your view.
Start Verification
To start a verification, you can call the startVerification() method. We suggest doing this with an setOnClickListener
Kotlin
Java
1
val verificationButton = findViewById<PassbaseButton>(R.id.passbaseVerificationButton)
2
​
3
verificationButton.setOnClickListener {
4
   passbaseRef.startVerification()
5
}
Copied!
1
PassbaseButton verificationButton = this.findViewById(R.id.passbaseVerificationButton);
2
​
3
verificationButton.setOnClickListener(new View.OnClickListener() {
4
            @Override
5
            public void onClick(View view) {
6
                passbaseRef.startVerification();
7
            }
8
        });
Copied!
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.
Prefilling Email Address
If you want to prefill a user's email address, to skip the "Approve your Email" screen, you can simply pass the email address into the initialization method.
Kotlin
Java
1
package com.passbase.androiddemoapp
2
​
3
import androidx.appcompat.app.AppCompatActivity
4
import android.os.Bundle
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.PassbaseSDK
8
import com.passbase.passbase_sdk.PassbaseButton
9
​
10
class MainActivity : AppCompatActivity() {
11
​
12
    override fun onCreate(savedInstanceState: Bundle?) {
13
        super.onCreate(savedInstanceState)
14
        setContentView(R.layout.activity_main)
15
​
16
        val passbaseRef = PassbaseSDK(this)
17
        passbaseRef.initialize("YOUR_PUBLISBALE_API_KEY")
18
        // 2. You can add the prefill email option here (optional)
19
        passbaseRef.prefillUserEmail = "[email protected]";
20
    }
21
}
22
​
Copied!
1
package com.passbase.androiddemoapp;
2
​
3
import androidx.appcompat.app.AppCompatActivity;
4
import android.os.Bundle;
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.Passbase;
8
import com.passbase.passbase_sdk.PassbaseButton;
9
​
10
public class MainActivity extends AppCompatActivity {
11
​
12
    @Override
13
    protected void onCreate(Bundle savedInstanceState) {
14
        super.onCreate(savedInstanceState);
15
        setContentView(R.layout.activity_main);
16
​
17
        PassbaseSDK passbaseRef = new PassbaseSDK(this);
18
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
19
        
20
        // 2. You can add the prefill email option here
21
        passbaseRef.setPrefillUserEmail("[email protected]"); 
22
    }
23
}
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 button like below. An ISO-3166 compliant country code, case insensitive. This will not enable skipping the country selection step. 
Kotlin
Java
1
package com.passbase.androiddemoapp
2
​
3
import androidx.appcompat.app.AppCompatActivity
4
import android.os.Bundle
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.PassbaseSDK
8
import com.passbase.passbase_sdk.PassbaseButton
9
​
10
class MainActivity : AppCompatActivity() {
11
​
12
    override fun onCreate(savedInstanceState: Bundle?) {
13
        super.onCreate(savedInstanceState)
14
        setContentView(R.layout.activity_main)
15
​
16
        val passbaseRef = PassbaseSDK(this)
17
        passbaseRef.initialize("YOUR_PUBLISBALE_API_KEY")
18
        // 2. You can add the prefill email option here (optional)
19
        passbaseRef.prefillCountry = "de";
20
    }
21
​
Copied!
1
package com.passbase.androiddemoapp;
2
​
3
import androidx.appcompat.app.AppCompatActivity;
4
import android.os.Bundle;
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.Passbase;
8
import com.passbase.passbase_sdk.PassbaseButton;
9
​
10
public class MainActivity extends AppCompatActivity {
11
​
12
    @Override
13
    protected void onCreate(Bundle savedInstanceState) {
14
        super.onCreate(savedInstanceState);
15
        setContentView(R.layout.activity_main);
16
​
17
        PassbaseSDK passbaseRef = new PassbaseSDK(this);
18
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
19
        
20
        // 2. You can add the prefill email option here
21
        passbaseRef.setPrefillCountry("de"); 
22
    }
23
}
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
Kotlin
Java
1
package com.passbase.androiddemoapp
2
​
3
import androidx.appcompat.app.AppCompatActivity
4
import android.os.Bundle
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.PassbaseSDK
8
import com.passbase.passbase_sdk.PassbaseButton
9
​
10
class MainActivity : AppCompatActivity() {
11
​
12
    override fun onCreate(savedInstanceState: Bundle?) {
13
        super.onCreate(savedInstanceState)
14
        setContentView(R.layout.activity_main)
15
​
16
        val passbaseRef = PassbaseSDK(this)
17
        passbaseRef.initialize("YOUR_PUBLISBALE_API_KEY")
18
        
19
        // Signed and Armored Metadata, which contain {internal_customer_id: "XYZ", "email": "[email protected]", "country": "de", ...}
20
        passbaseRef.metaData = "AJIZZDIZJADIOAJDOIZJAOIZJDOIAJIODZJIAJDIOZJAIOZDJALANLIKESJIZZOIZDJAOIZJDOZIAJDOIAZJDAZD"
21
    }
22
​
Copied!
1
package com.passbase.androiddemoapp;
2
​
3
import androidx.appcompat.app.AppCompatActivity;
4
import android.os.Bundle;
5
​
6
// 1. Add import of Passbase SDK and the Passbase Button to the top
7
import com.passbase.passbase_sdk.Passbase;
8
import com.passbase.passbase_sdk.PassbaseButton;
9
​
10
public class MainActivity extends AppCompatActivity {
11
​
12
    @Override
13
    protected void onCreate(Bundle savedInstanceState) {
14
        super.onCreate(savedInstanceState);
15
        setContentView(R.layout.activity_main);
16
​
17
        PassbaseSDK passbaseRef = new PassbaseSDK(this);
18
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
19
        
20
        // Signed and Armored Metadata, which contain {internal_customer_id: "XYZ", "email": "[email protected]", "country": "de", ...}
21
        passbaseRef.setMetaData("AJIZZDIZJADIOAJDOIZJAOIZJDOIAJIODZJIAJDIOZJAIOZDJALANLIKESJIZZOIZDJAOIZJDOZIAJDOIAZJDAZD");
22
    }
23
}
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.
​Click here to view metaData encryption documentation.
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
In some cases it's useful to know if a user has completed the verification flow or canceled it. For this, you can implement the following delegate/callback methods:
Method
Description
onStart
This callback method is triggered once a user starts the verification flow. 
onSubmitted
Method that is being called once verification data is submitted to Passbase.
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.
onFinish
Method that is being called once a user clicks the "Finish" button. 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 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_FAILED
We also recommend adding this to your setOnClickListener method.
Kotlin
Java
1
val passbaseRef = PassbaseSDK(this)
2
​
3
// Add here the callbacks
4
passbaseRef.callback(object : PassbaseSDKListener {
5
        override fun onStart() {
6
            println("MainActivity onStart")
7
        }
8
​
9
        override fun onFinish(identityAccessKey: String) {
10
            println("MainActivity onFinish $identityAccessKey")
11
        }
12
        
13
        override fun onSubmitted(identityAccessKey: String) {
14
            println("MainActivity onSubmitted $identityAccessKey")
15
        }
16
​
17
        override fun onError(errorCode: String) {
18
            println("MainActivity onError $errorCode")
19
        }
20
    })
Copied!
1
PassbaseSDK passbaseRef = new PassbaseSDK(this);
2
​
3
// Add here the callbacks
4
passbaseRef.callback(new PassbaseSDKListener() {
5
            @Override
6
            public void onStart() {
7
                System.out.println("MainActivity onStart");
8
            }
9
​
10
            @Override
11
            public void onFinish(@Nullable String identityAccessKey) {
12
                System.out.println("MainActivity onFinish: " + identityAccessKey);
13
            }
14
            
15
            @Override
16
            public void onSubmitted(@Nullable String identityAccessKey) {
17
                System.out.println("MainActivity onSubmitted: " + identityAccessKey);
18
            }
19
​
20
            @Override
21
            public void onError(@NotNull String errorCode) {
22
                System.out.println("MainActivity onError: " + errorCode);
23
            }
24
        });
25
​
Copied!
We recommend the following process for handling identity verifications:
1.Obtain the authKey of a successfully completed identity verification from the callback method and save it to your DB to the user's profile
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 triggered if a user has activated this in his system settings.
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
If you are using ProGuard you might need to add the following options:
1
-dontwarn okio.**
2
-dontwarn retrofit2.Platform$Java8
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
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
1
package com.passbase.androiddemoapp
2
​
3
import androidx.appcompat.app.AppCompatActivity
4
import android.os.Bundle
5
import com.passbase.passbase_sdk.Passbase
6
import com.passbase.passbase_sdk.PassbaseButton
7
import android.graphics.Color
8
​
9
class MainActivity : AppCompatActivity() {
10
​
11
    override fun onCreate(savedInstanceState: Bundle?) {
12
        super.onCreate(savedInstanceState)
13
        setContentView(R.layout.activity_main)
14
​
15
        val passbaseRef = PassbaseSDK(this)
16
​
17
        // Initialization and prefilled email
18
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY")
19
        passbaseRef.prefillUserEmail = "[email protected]";
20
        // Handling verifications via callbacks
21
        passbaseRef.callback(object : PassbaseSDKListener {
22
                override fun onStart() {
23
                    println("MainActivity onStart")
24
                }
25
        
26
                override fun onFinish(identityAccessKey: String?) {
27
                    println("MainActivity onFinish $identityAccessKey")
28
                }
29
                
30
                override fun onSubmitted(identityAccessKey: String?) {
31
                    println("MainActivity onSubmitted $identityAccessKey")
32
                }
33
        
34
                override fun onError(errorCode: String) {
35
                    println("MainActivity onError $errorCode")
36
                }
37
            })       
38
​
39
        val verificationButton = findViewById<PassbaseButton>(R.id.passbaseVerificationButton)
40
        verificationButton.setOnClickListener {
41
            passbaseRef.startVerification()
42
        }
43
    }
44
}
45
​
Copied!
1
package com.passbase.androiddemoapp;
2
​
3
import androidx.appcompat.app.AppCompatActivity;
4
import android.os.Bundle;
5
import com.passbase.passbase_sdk.PassbaseSDK;
6
import com.passbase.passbase_sdk.PassbaseButton;
7
import android.graphics.Color;
8
​
9
public class MainActivity extends AppCompatActivity {
10
​
11
    @Override
12
    protected void onCreate(Bundle savedInstanceState) {
13
        super.onCreate(savedInstanceState);
14
        setContentView(R.layout.activity_main);
15
​
16
        PassbaseSDK passbaseRef = new PassbaseSDK(this);
17
​
18
        // Initialization and prefilled email
19
        passbaseRef.initialize("YOUR_PUBLISHABLE_API_KEY");
20
        passbaseRef.setPrefillUserEmail("[email protected]");
21
        // Handling verifications via callbacks
22
        passbaseRef.callback(new PassbaseSDKListener() {
23
            @Override
24
            public void onStart() {
25
                System.out.println("MainActivity onStart");
26
            }
27
​
28
            @Override
29
            public void onFinish(@Nullable String identityAccessKey) {
30
                System.out.println("MainActivity onFinish: " + identityAccessKey);
31
            }
32
            
33
            @Override
34
            public void onSubmitted(@Nullable String identityAccessKey) {
35
                System.out.println("MainActivity onSubmitted: " + identityAccessKey);
36
            }
37
​
38
            @Override
39
            public void onError(@NotNull String errorCode) {
40
                System.out.println("MainActivity onError: " + errorCode);
41
            }
42
        });
43
         
44
        PassbaseButton verificationButton = this.findViewById(R.id.passbaseVerificationButton);
45
        verificationButton.setOnClickListener(new View.OnClickListener() {
46
            @Override
47
            public void onClick(View view) {
48
                passbaseRef.startVerification();
49
            }
50
        });
51
    }
52
}
53
​
Copied!
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.