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, open the pubspec.yaml file and add the following line in your dependencies section:

passbase_flutter: ^2.5.0 //for Flutter v.1
//or
passbase_flutter: ^2.5.0-nullsafety.0 //for Flutter v.2

After that press Packages get

iOS 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.

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/passbase/zoomauthentication-cocoapods-specs.git'
source 'https://github.com/passbase/cocoapods-specs.git'
source 'https://github.com/passbase/microblink-cocoapods-specs.git'

Then, navigate inside the terminal into your project folder and run the following command to install the Passbase iOS SDK as a dependency: pod install

Example of a complete Podfile

# Example of a Podfile
# 1. Add this here
source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/passbase/zoomauthentication-cocoapods-specs.git'
source 'https://github.com/passbase/cocoapods-specs.git'
source 'https://github.com/passbase/microblink-cocoapods-specs.git'
​
# 2. Add the platform requirement to at least iOS 11
platform :ios, '11.0' 
​
# Flutter related code
# ... 
​
target 'Runner' do
  # 3. Add use_frameworks! because of Sentry pod
  use_frameworks!
  
  # Flutter related code
  # ... 
end

Adding Camera Permissions in Info.plist

You need to adjust your iOS project's settings now. Open the workspace file inside your ios folder. It should have the name Runner.xcworkspace. Then open in the left project navigator your app's Info.plistfile. Here we have to adjust the App's permission so that we can access the users' camera to run a verification. You can do it 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>

<!-- permission strings to be include in info.plist -->
<key>NSCameraUsageDescription</key>
<string>Please give us access to your camera, to complete the verification.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Please give us access to your photo library to verify you.</string>

Allow using embedded views

To use PassbaseButton on iOS, you need to opt-in for the preview of the embedded view by adding a boolean property to the app's Info.plist file, with the key io.flutter.embedded_views_preview and the value YES.

Android Specific Steps

After installing the Passbase Flutter package, please complete the following steps to set up the Android environment correctly:

Adding Kotlin, Maven and minSdkVersion

Kotlin support is required in the main Android project. Please add the following lines to your project'sandroid/build.gradle file:

1. Set kotlin_version to "1.3.21" or higher

2. Add the line classpath("org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version")to dependencies

Code Example

// In the different lines to your projcet's build.gradle file
buildscript {
    ext.kotlin_version = '1.3.21' // 2. Add kotlin_version
    
    dependencies {
       ...
       // 3. Add classpath
       classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version" 
    }
}

Set minSdkVersion to 21 or higher in android/app/build.gradle file:

android {
    ...
    defaultConfig {
        ...
        // Change minSdkVersion
        minSdkVersion 21
        ...
  }
  ...
}

2. Initialize the SDK

First, add the following import statement to the top of the main.dart file:

import 'package:passbase_flutter/passbase_flutter.dart';

Then, initialize the SDK with your own publishable API key which you can get from your developer dashoard's API settings.

PassbaseSDK.initialize(publishableApiKey: "YOUR_PUBLISHABLE_API_KEY");

3. Start Verification

Use PassbaseButtonPassbaseButton component provided by the SDK

import 'package:passbase_flutter/passbase_flutter.dart';
​
...
PassbaseButton(
  onFinish: (identityAccessKey) { 
    // do stuff in case of success
  },
  onSubmitted: (identityAccessKey) { 
    // do stuff in case of success
  },
  onError: (errorCode) {
    // do stuff in case of cancel
  },
  onStart: () {
    // do stuff in case of start
  },
),
...

This will render the Passbase Button on UI and will automatically start verification on its press.

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 button like below.

import 'package:passbase_flutter/passbase_flutter.dart';
​
...
PassbaseSDK.prefillUserEmail = "[email protected]"; //optional
...

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.

import 'package:passbase_flutter/passbase_flutter.dart';
​
...
PassbaseSDK.prefillCountry = "de"; //optional
...

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.

import 'package:passbase_flutter/passbase_flutter.dart';
​
...
// Signed and Armored Metadata, which contain {internal_customer_id: "XYZ", "email": "[email protected]", "country": "de", ...}
PassbaseSDK.metaData = "AJIZZDIZJADIOAJDOIZJAOIZJDOIAJIODZJIAJDIOZJAIOZDJALANLIKESJIZZOIZDJAOIZJDOZIAJDOIAZJDAZD"
...

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.

{
   id: "1234-1234-1234-1234",
   resources: [...],
   metadata: { internal_customer_id: "XYZ" }
}

4. Handling Verifications

Often it is useful to know if a user has completed the verification or canceled it. For this, we can implement the following delegate/callback methods:

import 'package:passbase_flutter/passbase_flutter.dart';
​
...
PassbaseButton(
  onFinish: (identityAccessKey) { 
    // do stuff in case of success
  },
  onSubmitted: (identityAccessKey) { 
    // do stuff in case of success
  },
  onError: (errorCode) {
    // do stuff in case of cancel
  },
  onStart: () {
    // do stuff in case of start
  },
),
...

We recommend the following process for handling identity verifications:

1. Obtain the identityAccessKey of successfully completed identity verifications from the callback method and save them to your DB e.g. a 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 that 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.

We also offer a dark mode, which will be automatically started 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 (Android)

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

You can find an example of a whole class in the code section below. Also we have a full example app on our Github: ​Flutter Demo App​

import 'package:flutter/material.dart';
import 'package:passbase_flutter/passbase_flutter.dart';
void main() => runApp(PassbaseFlutterDemoApp());
class PassbaseFlutterDemoApp extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primarySwatch: Colors.blue,
      ),
      home: PassbaseDemoHomePage(),
    );
  }
}
class PassbaseDemoHomePage extends StatefulWidget {
  PassbaseDemoHomePage({Key key}) : super(key: key);
  @override
  _PassbaseDemoHomePageState createState() {
    PassbaseSDK.initialize(publishableApiKey: "YOUR_PUBLISHABLE_API_KEY");
    PassbaseSDK.prefillUserEmail = "[email protected]"; //optional
    return _PassbaseDemoHomePageState();
  }
}
class _PassbaseDemoHomePageState extends State<PassbaseDemoHomePage> {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: <Widget>[
            PassbaseButton(
              onFinish: (identityAccessKey) {
// do stuff in case of success
                print(identityAccessKey);
              },
              onSubmitted: (identityAccessKey) {
// do stuff in case of success
                print(identityAccessKey);
              },
              onError: (errorCode) {
// do stuff in case of cancel
                print(errorCode);
              },
              onStart: () {
// do stuff in case of start
                print("start");
              },
              width: 300,
              height: 70,
            ),
          ],
        ),
      ),
    );
  }
}

Troubleshooting

App is crashing when verification is started

If you experience a crash on Android when verification is started you can try to add this to your android/build.gradle file:

subprojects {
    project.configurations.all {
        resolutionStrategy.eachDependency { details ->
            if (details.requested.group == 'androidx.core' &&
                    !details.requested.name.contains('androidx')) {
                details.useVersion "1.1.0"
            }
        }
    }
}

Camera is not starting in release build on android