Android SDK

The SDK provides a set of screens for capturing identity documents, face photos, profile data, and for performing the liveness check. It can also read the NFC chip embedded in biometric documents (e.g. passports and electronic ID cards). After capturing the data the SDK uploads it to the server.

The SDK does not provide methods for obtaining verification results. Use API on your backend to get ones.

This document describes how to use the version 4.2.2 or newer. The documentation for older versions is here.

Getting started

Requirements

• Android Studio Giraffe | 2022.3.1
• Android sdk version 21+

Obtaining an SDK key

In order to start using SDK, you will need an SDK KEY and API URL. Both can be found and modified either through your Dashboard or via contacting our integration support.

Note: In your Dashboard, you can get and set API KEY and SDK KEY. API KEY grants you access to public API calls and SDK API calls. SDK KEY grants you access to SDK API calls only. For security reasons, strongly recommended using the SDK KEY in your SDK.

Installation

In the build.gradle of project you want to use this package:

repositories {
    mavenCentral()
    maven { url "https://jitpack.io" }
    maven { url "https://cdn.getid.cloud/sdk/android" }
}

dependencies {
    implementation "ee.getid:getidlib:4.2.2"
}

NFC document reading

From version 4.2.2 onward, the Android SDK can read the RFID/NFC chip embedded in biometric documents (e.g. passports and electronic ID cards) to capture and verify chip data such as the document holder's photo and personal details.

NFC is enabled and configured per flow in your Dashboard. When a flow includes the NFC step and the captured document contains a readable chip, the SDK automatically presents the NFC reading screens — no additional code is required when starting the flow. If the device has no NFC hardware or NFC is turned off, the SDK handles this gracefully and guides the user accordingly.

Requirements

• A physical device with NFC hardware (NFC cannot be tested on an emulator).
• NFC enabled in the device settings.
• Android SDK 4.2.2 or newer (latest recommended: 4.2.2).

Installation

The NFC functionality is shipped as a separate nfc artifact and is resolved automatically as a transitive dependency of getidlib. Make sure the CDN Maven repository (https://cdn.getid.cloud/sdk/android) is declared in your build (see Installation) and that you use SDK version 4.2.2 or newer.

Permissions

If your flow uses NFC, add the NFC permission to your app's AndroidManifest.xml:

<uses-permission android:name="android.permission.NFC" />

Optionally, declare the NFC hardware feature as not required so your app remains installable on devices without NFC (the SDK detects unsupported devices at runtime):

<uses-feature android:name="android.hardware.nfc" android:required="false" />

No NFC intent filters are required in your manifest — the SDK manages NFC tag discovery internally while the verification flow is in the foreground.

Usage

Before you start please go to Admin Panel and create a flow (Flows > Add new flow).

Starting the flow

There are two ways to start the verification flow: using the SDK KEY or using a JWT. We recommend using JWT in the production environment. But during the development, you can use SDK KEY, because it's a little bit more convenient.

Then call GetIDSDK().startVerificationFlow() method from the place in your code that responds to starting the verification flow. For example, it can be a handler of a button touch event.

Kotlin

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Key("SDK_KEY"),
    flowName = "FLOW_NAME"
)

or

Java

new GetIDSDK().startVerificationFlow(
                getApplicationContext(),
                "API_URL",
                new Key("SDK_KEY", null),
                "FLOW_NAME",
                null,
                null,
                null,
                null
        );

To start the verification flow using a JWT, your app should obtain the token from your backend. Your backend should have the SDK KEY to request the token from server. Don't store SDK KEY inside the app in the production environment.

To test starting the flow using a JWT, you can obtain one. To obtain a JWT make a POST request on your API URL with SDK KEY in the header:

$ curl -H "Content-Type: application/json" -H "x-sdk-key: SDK_KEY" -X POST API_URL/sdk/v2/token

Then pass the received token to GetIDSDK().startVerificationFlow() method:

Kotlin

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Token("JWT"),
    flowName = "FLOW_NAME"
)

or

Java

new GetIDSDK().startVerificationFlow(
                getApplicationContext(),
                "API_URL",
                new Token("JWT"),
                "FLOW_NAME",
                null,
                null,
                null,
                null
        );

External IDs

There are two different external IDs that can be used to link a verification with a user in your system: customerId and externalId. See the details in this document.

Profile data

If you have some information about the user before the verification flow started, you can pass it to the SDK as profileData.

The SDK can use this data to prefill the form if the flow contains the Profile Data step. The user can edit this information while filling out the form.

If the form does not contain a profileData field (or there is no Profile Data step in the flow) then this field will be sent to the server without the user's edit.

Kotlin

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Token("JWT"),
    flowName = "FLOW_NAME",
    profileData = mapOf("first-name" to "John", "gender" to "male")
)

or

Java

Map<String,String> profileData = new HashMap<>();
     profileData.put("first-name", "John");
     profileData.put("gender", "male");

new GetIDSDK().startVerificationFlow(
                getApplicationContext(),
                "API_URL",
                new Token("JWT"),
                "FLOW_NAME",
                null,
                null,
                profileData,
                null
        );

You can find more details on field names and their format in this document.

Acceptable documents

It's possible to limit the list of acceptable documents and issuing countries. In order to do that pass acceptableDocuments parameter to GetIDSDK().startVerificationFlow() method.

GetIDSDK().startVerificationFlow(
  context = applicationContext,
  apiUrl = "API_URL",
  auth = Token("JWT"),
  flowName = "FLOW_NAME",
  acceptableDocuments = mapOf("EST" to listOf(DocumentEnum.PASSPORT, DocumentEnum.ID_CARD), "default" to listOf(DocumentEnum.PASSPORT))
)

See more details on setting acceptable document types and countries in this document.

Metadata

You can attach some metadata to a verification.

Kotlin

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Token("JWT"),
    flowName = "FLOW_NAME",
    metadata = Metadata(labels = mapOf("department" to "EST"))
)

or

Java

Map<String,String> metadata = new HashMap<>();
profileData.put("department", "EST");

new GetIDSDK().startVerificationFlow(
                getApplicationContext(),
                "API_URL",
                new Token("JWT"),
                "FLOW_NAME",
                new Metadata(null, metadata),
                null,
                null,
                null
        );

Locale

By default, the SDK gets the list of device's preferred languages and chooses the best match from the list of supported languages. So you don't have to set up the language of the verification flow's UI.

But if you want to override the default behavior by some reason, then pass locale to GetIDSDK().startVerificationFlow() method.

Kotlin

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Token("JWT"),
    flowName = "FLOW_NAME",
    locale = "et"
)

or

Java

new GetIDSDK().startVerificationFlow(
                getApplicationContext(),
                "API_URL",
                new Token("JWT"),
                "FLOW_NAME",
                null,
                "et",
                null,
                null
        );

Custom dictionary

If you want to change some texts in the UI, then you have to upload one or more dictionaries to our backend. Our API documentation describes how to do that on this page. Once a dictionary is uploaded, pass its name as the dictionary parameter to the SDK initializer.

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Token("JWT"),
    flowName = "FLOW_NAME",
    dictionary = "custom-dictionary-name"
)

Handling callbacks

If you want to handle the verification process completion then pass eventListener to GetIDSDK().startVerificationFlow() method.

Here is an example of handling SDK callbacks:

Kotlin

GetIDSDK().startVerificationFlow(
    context = applicationContext,
    apiUrl = "API_URL",
    auth = Token("JWT"),
    flowName = "FLOW_NAME",
    locale = "et"
)

private fun initEventListeners() = object : BroadcastReceiverListener {
        override fun verificationFlowStart() {
            Log.d("GetIdTag", "GetID flow has been started.")
        }

        override fun verificationFlowCancel() {
            Log.d("GetIdTag", "GetID flow has been cancelled.")
        }

        override fun verificationFlowFail(error: GetIDError) {
            Log.d("GetIdTag", "GetID flow has been completed with error:" + error.name)
        }

        override fun verificationFlowComplete(application: GetIDApplication) {
            Log.d("GetIdTag", "GetID flow has been completed, applicationId:" + application.applicationId)
        }
    }

Possible errors

Errors that can occur in SDK are GetIDError enum, see the list of all possible cases in the tables below.

Localisation

Android SDK loads translations from the server at launch. The SDK also gets the user's preferred languages list from the operating system. Then the SDK compares this list with available translations and picks the best match.

It works automatically and doesn't require any additional configuration.