# Android SDK

# Getting started

Latest release: Version 1.12.3 (Changelog)

# Requirements

# Resources

# Installation

It's always a good idea to be using the latest version

Add the SumSub maven repository to the repositories section in your build.gradle file:

repositories {
  maven { url "https://maven.sumsub.com/repository/maven-public/" }

Add the following dependencies to your build.gradle file:

dependencies {
    // SumSub core
    implementation "com.sumsub.sns:idensic-mobile-sdk:$latestVersion"

    // optional
    // if you want to use Liveness3D module
    implementation "com.sumsub.sns:idensic-mobile-sdk-liveness3d:$latestVersion"

# Basic Usage

Make sure you completed the Backend routines before initializing the SDK

# Initialization

// NOTE: make sure to change to 'https://api.sumsub.com' when going live
val apiUrl = "https://test-api.sumsub.com"

// use the 'accessToken' that you generated on your backend
val accessToken = "..."
val flowName = "..."
val modules = listOf(SNSLiveness3d())

val tokenExpirationHandler = object : TokenExpirationHandler {
    override fun onTokenExpired(): String? {
        val newToken = ....
        return newToken

val snsSdk = SNSMobileSDK.Builder(this, apiUrl, flowName)
    .withAccessToken(accessToken, onTokenExpiration = tokenExpirationHandler)


If you don't intend to use the liveness module just make sure that the modules are set as an empty list

# Handlers

# Token Expiration Handler

Because of the limited lifespan of the accessToken, it's important to handle the situation correctly when the token expires and needs to be refreshed. In order to do this provide tokenHandler for the SDK Builder. The handler should make a call to your backend, obtain a new access token and then pass it back to the SDK by returning its value.

val tokenHandler = object : TokenExpirationHandler {
    override fun onTokenExpired(): String? {
        val newToken = ....
        return newToken

onTokenExpired is called on a non-UI thread

# Callbacks

# On SDK State changes

Use withHandlers(onStateChanged=onSDKStateChangedHandler) in the SDK builder to get notified about changed in the flow of the verification process. The callback takes two parameters:

  • newState is the current SDK State
  • prevState is the previous state value

The following example lists all the possible states:

val onSDKStateChangedHandler: (SNSSDKState, SNSSDKState) -> Unit = { newState, prevState ->
    Timber.d("onSDKStateChangedHandler: $prevState -> $newState")

    when (newState) {
        is SNSSDKState.Ready -> Timber.d("SDK is ready")
        is SNSSDKState.Failed -> {
            when (newState) {
                is SNSSDKState.Failed.ApplicantNotFound -> Timber.e(newState.message)
                is SNSSDKState.Failed.ApplicantMisconfigured -> Timber.e(newState.message)
                is SNSSDKState.Failed.InitialLoadingFailed -> Timber.e(newState.exception,"Initial loading error")
                is SNSSDKState.Failed.InvalidParameters -> Timber.e(newState.message)
                is SNSSDKState.Failed.NetworkError -> Timber.e(newState.exception,newState.message)
                is SNSSDKState.Failed.Unauthorized -> Timber.e(newState.exception,"Invalid token or a token can't be refreshed by the SDK. Please, check your token expiration handler")
                is SNSSDKState.Failed.Unknown -> Timber.e(newState.exception, "Unknown error")
        is SNSSDKState.Initial -> Timber.d("No verification steps are passed yet")
        is SNSSDKState.Incomplete -> Timber.d("Some but not all verification steps are passed over")
        is SNSSDKState.Pending -> Timber.d("Verification is in pending state")
        is SNSSDKState.FinallyRejected -> Timber.d("Applicant has been finally rejected")
        is SNSSDKState.TemporarilyDeclined -> Timber.d("Applicant has been declined temporarily")
        is SNSSDKState.Approved -> Timber.d("Applicant has been approved")

val snsSdkBuilder = SNSMobileSDK.Builder(this, apiUrl).withHandlers(onStateChanged = onSDKStateChangedHandler)

# On SDK Errors

Use withHandlers(onError=onSDKErrorHandler) in the SDK builder to know about errors that occur within the SDK. Refer to the example below to see how:

val onSDKErrorHandler: (SNSException) -> Unit = { exception ->
    Timber.d("The SDK throws an exception. Exception: $exception")

    when (exception) {
        is SNSException.Api -> Timber.d("Api exception. ${exception.description}")
        is SNSException.Network -> Timber.d(exception, "Network exception.")
        is SNSException.Unknown -> Timber.d(exception, "Unknown exception.")

val snsSdkBuilder = SNSMobileSDK.Builder(this, apiUrl).withHandlers(onError = onSDKErrorHandler)

# On SDK completion

An optional callback to get notified when the SDK is closed:

val onSDKCompletedHandler: (SNSCompletionResult, SNSSDKState) -> Unit = { (reason, state) ->
    when (result) {
        is SNSCompletionResult.SuccessTermination -> Timber.d("The SDK finished successfully")
        is SNSCompletionResult.AbnormalTermination -> Timber.e(reason.exception, "The SDK got closed because of errors")

val snsSdkBuilder = SNSMobileSDK.Builder(this, apiUrl).withHandlers(onCompleted = onSDKCompletedHandler)

The callback takes two parameters:

  • reason:
    • SNSCompletionResult.SuccessTermination - A user clicks on the cancel button.
    • SNSCompletionResult.AbnormalTermination - an error occurred. Look at the exception object if you want to get more information
  • state: The state at which the SDK was closed. For possible states refer to the following Section

# Debugging

# Logs

If you want to see the logs within the SDK, please, use the following code:

// default is 'false'
val snsSdkBuilder = SNSMobileSDK.Builder(this, apiUrl).withDebug(true)

Don't forget to disable the flag for the release build.

# Custom Logger

By default the SDK uses Timber for logging purposes. If, for some reason, it doesn't work or you want to implement your own tree for Timber, you should extend from SNSLogTree and implement the log function, for example:

class CustomTree: SNSLogTree() {
    override fun log(priority: Int, tag: String?, message: String, t: Throwable?) {
        Log.println(priority, tag, message)

Right now you can use your custom log tree:

val snsSdkBuilder = SNSMobileSDK.Builder(this, apiUrl).withLogTree(CustomTree())

# Customization

The SDK can be customized: you can change styles, colors, typefaces, etc.

# Localization

You can customize or localize the texts used within the SDK through the MSDK Translations tool in the dashboard.

For more information refer to the official documentation)

Last Updated: 9/22/2020, 4:23:34 PM