Android SDK

A simple guide to integrate Fingerprint’s device intelligence platform in your native Android apps.

In this guide, you will learn to

• Include Android SDK in your mobile apps.
• Get a visitorId.
• Read the SDK response.
• Enable location data collection (optional; to start getting additional location-based proximity data).
• Configure the SDK as per your needs.
• Specify additional metadata in your identification request.
• Handle errors.

For a complete example of how to use this SDK in your app, please visit the GitHub repo of our demo app. View our Android quickstart for a step-by-step guide to get started.

Prerequisites

Sign up for an account with Fingerprint to get your API key.

Including the SDK in your app

1. Add the repositories to your Project Settings file. Depending on your build configuration language, this file can either be settings.gradle.kts or settings.gradle.

   settings.gradle.kts (Kotlin DSL)

     ...
     dependencyResolutionManagement {
         repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
         repositories {
             google()
             mavenCentral()
             maven { url = uri("https://maven.fpregistry.io/releases") }
         }
     }
   

   Alternatively, if your project is configured to ignore the repositories declared in the Project Settings file, you can add the repositories to the project-level build file. Depending on your build configuration language, this file can either be build.gradle.kts or build.gradle.

   build.gradle.kts (Kotlin DSL)

     allprojects {
         repositories {
             google()
             mavenCentral()
             maven { url = uri("https://maven.fpregistry.io/releases") }
         }
     }
   

2. Add the dependencies to your module-level build file. Depending on your build configuration language, this file can either be build.gradle.kts or build.gradle.

   build.gradle.kts (Kotlin DSL)

   dependencies {
       implementation("com.fingerprint.android:sdk:4.0.0")
   }
   

3. Perform a Gradle sync to update all the dependencies.

Getting a visitorId

To get a visitorId, you need the public API key that you obtained when signing up for an account with Fingerprint. You can find this API key in the Dashboard > API Keys.

Here is an example that shows you how to get a visitorId:

Kotlin

val factory = FingerprintFactory(applicationContext)
val configuration = Configuration(apiKey = "PUBLIC_API_KEY")
val fpClient = factory.createInstance(configuration)

scope.launch(Dispatchers.IO) {
    try {
        val response = fpClient.getVisitorId()
        val visitorId = response.visitorId
    } catch (e: FingerprintException) {
        // Handle error
    }
}

The getVisitorId() suspend functions perform blocking I/O and should be called from a background dispatcher such as Dispatchers.IO. Cancelling the coroutine does not cancel the underlying signal collection or network request. The coroutine API is Kotlin-only; Java users should use the callback-based API.

Specifying a custom timeout

Default timeout value: null

The identification requests made from an Android SDK do not have a default timeout.

You can use timeoutMillis to provide a custom timeout value of your choice. If the getVisitorId() call does not complete within the specified timeout, you will receive a ClientTimeout error.

Here is an example that shows you how to specify a custom timeout:

Kotlin

scope.launch(Dispatchers.IO) {
    try {
        // Get a visitor ID, will timeout after 5s
        val response = fpClient.getVisitorId(
            timeoutMillis = 5_000
        )
        val visitorId = response.visitorId
    } catch (e: FingerprintException) {
        if (e.error is ClientTimeout) {
            // Handle timeout
        }
    }
}

Using Location Data for Proximity Detection

This is optional. Enable this only if you want to include the additional location-based proximity detection signal in your response.

Starting with Android SDK 2.10.0, you can receive additional location-based signals (proximity ID, confidence, precision radius) by enabling allowUseOfLocationData and declaring the corresponding location permissions.

Location permissions

Declaring permissions

To calculate Proximity ID and related data (confidence score, precision radius), Fingerprint needs the following location permissions in the manifest:

XML

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

At least coarse location permission is required. Please note that accuracy will be lower without fine location permission.

Asking for permissions

Your app is responsible for asking for permissions. Refer to Android documentation or refer to the Fingerprint demo app if you need to implement this flow. If you already have this process set up, skip to the next section.

Enabling location collection

Fingerprint can only collect location data if allowUseOfLocationData is set to true. Optionally, you can control the timeout by setting locationTimeoutMillis to the desired value. Note that the value is 5 seconds by default.

Timeout Recommendation: Because location accuracy and performance can vary based on user settings, device models, and use cases, we do not enforce a fixed default timeout. We recommend that you explicitly configure a timeout value that aligns with the app’s user experience and performance expectations.

Reading the response

The function Fingerprint.getVisitorId() returns the response in a FingerprintResponse object. This object has the following fields, some of which can be empty/invalid when Sealed Client Results is enabled for your account.

Field	Sealed Client Results is disabled	Sealed Client Results is enabled
eventId	String. An identifier that uniquely identifies this particular event to Fingerprint.getVisitorID().	String. An identifier that uniquely identifies this particular request to Fingerprint.getVisitorID().
visitorId	String. An identifier that uniquely identifies the device.	N/A
suspectScore	Int?. A score estimating the likelihood that a device is associated with fraudulent or malicious activity.	N/A
sealedResult	null	String?. An encrypted, binary, Base64-encoded String that contains the same response as you would receive with an /events API request

Configuring the SDK

Using the Configuration object, it is possible to configure the SDK as per your requirements. As of now, the following options are supported:

region

Type: Configuration.Region.

Default value: Configuration.Region.US

This option allows you to specify a region where you want your data to be stored and processed. This region must be the same as the one you specified when registering your app with Fingerprint. See region for more information.

endpointUrl

Type: String

Default value: Configuration.Region.US.getEndpointUrl()

This option allows you to specify a custom endpoint, particularly when you have set up either a custom sub-domain or a proxy integration.

fallbackEndpointUrls

Type: List<String>

Default value: emptyList()

This option allows you to specify alternate, fallback endpoints to redirect failed requests.

allowUseOfLocationData

Type: Boolean

Default value: false

This option allows you to enable the location data collection needed to calculate the location-based proximity detection signal.

locationTimeoutMillis

Type: Long

Default value: 5_000L (5 seconds)

This option allows you to configure the maximum timeout for location collection (controlled by allowUseOfLocationData).

The SDK will delay identification up to the specified timeout to collect the device location. If it cannot collect the location information within the specified time, identification continues without location information.

Specifying linkedID and tags

Like the JavaScript agent, the Android SDK also supports providing custom metadata with your identification request. To learn more about this capability, please visit Linking and tagging information.

Here is an example that shows you how to associate your identification request with an account ID and additional metadata:

Kotlin

scope.launch(Dispatchers.IO) {
    try {
        val response = fpClient.getVisitorId(
            // Associate additional metadata to this request
            tags = mapOf("orderID" to orderId, "zip" to zipCode),
            // Associate an account number to this request
            linkedId = accountID
        )
        val visitorId = response.visitorId
    } catch (e: FingerprintException) {
        // Handle error
    }
}

The metadata you want to include may not be available when making the identification request. For such scenarios, you can update that event later when the required metadata becomes available. A typical workflow is explained in Update linked_id and tags on the server.

Handling errors

The SDK provides an Error class that helps you identify the reasons behind an unsuccessful identification request. Here is an example that shows you how to handle errors in your app:

Kotlin

scope.launch(Dispatchers.IO) {
    try {
        val response = fpClient.getVisitorId()
        val visitorId = response.visitorId
    } catch (e: FingerprintException) {
        when (e.error) {
            is ApiKeyRequired -> {
                val eventId = e.eventId
                // Handle error
            }
            is NetworkError -> {
                // Handle network error
            }
            is ClientTimeout -> {
                // Handle timeout
            }
            else -> {
                Log.e("Fingerprint", "${e.eventId}: ${e.error.description}")
            }
        }
    }
}

Data Classes

Configuration

Kotlin

public class Configuration @JvmOverloads constructor(
    public val apiKey: String,
    public val region: Region = Region.US,
    public val endpointUrl: String = region.endpointUrl,
    public val fallbackEndpointUrls: List<String> = emptyList(),
    public val integrationInfo: List<Pair<String, String>> = emptyList(),
    public val allowUseOfLocationData: Boolean = false,
    public val locationTimeoutMillis: Long = DEFAULT_LOCATION_TIMEOUT_MILLIS,
) {
    public enum class Region(public val endpointUrl: String) {
        US("https://api.fpjs.io"),
        EU("https://eu.api.fpjs.io"),
        AP("https://ap.api.fpjs.io")
    }
}

Error

Error is a sealed class representing the reason an identification request failed. Each subtype carries an eventId and a description.

Kotlin

sealed class Error(
  // The event ID of the identification request
  val eventId: String = UNKNOWN,
  // A self-explanatory description of the error
  val description: String? = UNKNOWN
)

Server API error codes

These subtypes correspond to error codes returned by the Server API. Their description contains the message returned by the server.

• ApiKeyRequired
• ApiKeyNotFound
• SecretApiKeyRequired
• SecretApiKeyNotFound
• RequestCannotBeParsed
• Failed
• RequestTimeout
• TooManyRequest
• WrongRegion
• SubscriptionNotActive
• InstallationMethodRestricted
• InvalidProxyIntegrationHeaders
• InvalidProxyIntegrationSecret
• ProxyIntegrationSecretEnvironmentMismatch
• VisitorNotFound
• SubscriptionRestricted
• ServiceUnavailable
• FeatureNotEnabled
• RequestNotFound
• StateNotReady
• MissingModule
• PayloadTooLarge
• RulesetNotFound
• EnvironmentRestricted
• SubscriptionNotFound

SDK errors

These subtypes are generated by the SDK on the client side and have a fixed description.

Error class	Description
ResponseCannotBeParsed	Null/Invalid Response
NetworkError	Network error. Check your connection or the endpoint URL
NetworkUnavailableError	No network connectivity available.
UnknownError	Unknown
ClientTimeout	The session timed out

FingerprintException

Exception thrown by the coroutine-based getVisitorId() suspend functions when an error occurs. Wraps the Error sealed class and is thrown for use with try/catch.

Kotlin

class FingerprintException(
  // The error that caused the exception
  val error: Error
) : Exception(error.description) {
  // The event ID associated with this error
  val eventId: String get() = error.eventId
}

Check out these related resources:

• Android SDK changelog
• Android Quickstart
• Migrating the Fingerprint Android SDK from v2 to v4