We have released a new major version of the Fingerprint Android SDK (version 4.0.0), which allowed us to introduce breaking changes and requires you to manually migrate. The new Android SDK aligns with the v4 event format. This includes renamed classes and interfaces, a flattened response format, and a revised set of error types. None of these changes affect the underlying identification and and smart signals accuracy; these are structural/API changes only.

Native mobile SDKs v2.x will continue to work after v4.0.0 is released - you won’t be forced to upgrade right away.
During this period, critical client-side hotfixes will still be issued for v2.x if needed, and backend-side improvements (including smart signals detection logic) can continue to benefit v2.x integrations, as long as the required signals are already collected by that SDK version.
However, iOS and Android SDKs v2.x support is tied to our overall API v3 deprecation timeline: once the one-year deprecation period begins (which starts only after the full ecosystem, including Flutter and React Native SDKs, supports Server API v4), mobile SDKs v2.x will no longer receive client-side hotfixes once that period ends. Backend-side improvements will still apply to v2.x wherever the SDK already collects the necessary signals.

What’s new

The dependency coordinate changed from com.fingerprint.android:pro to com.fingerprint.android:sdk, and the public API types moved from the com.fingerprintjs.android.fpjs_pro package to com.fingerprint.android, dropping the legacy js/pro naming.
FingerprintJSFactory and the FingerprintJS interface are renamed to FingerprintFactory and Fingerprint, dropping the legacy “JS” naming.
The response object is renamed from FingerprintJSProResponse to FingerprintResponse, and several nested/legacy fields (confidenceScore, ipLocation, firstSeenAt, and similar) have been removed in favor of a flat response shape, along with their supporting types (ConfidenceScore, Timestamp, and IpLocation).
requestId is renamed to eventId across responses, errors, and exceptions.
The extendedResponseFormat configuration flag has been removed as v4 always returns the flat format.
Several error classes have been removed or replaced, and new error classes have been added to reflect new server-side error codes.
Kotlin upgraded from v1.9.25 to v2.3.20.

Migration steps

The following section outlines the necessary migration steps to complete the transition from v2 to v4.

Upgrade the MAJOR package version

Update the Fingerprint Android SDK dependency to the latest v4 version in your module’s build.gradle (or build.gradle.kts) dependencies block. The artifact coordinate also changed from com.fingerprint.android:pro to com.fingerprint.android:sdk:

implementation("com.fingerprint.android:sdk:4.0.0")

implementation "com.fingerprint.android:sdk:4.0.0"

Update imports

The public API types moved to the com.fingerprint.android package. Update every import com.fingerprintjs.android.fpjs_pro.* statement to com.fingerprint.android.*. A project-wide Replace All in your IDE is the quickest way to do this.

import com.fingerprintjs.android.fpjs_pro.Configuration 
import com.fingerprintjs.android.fpjs_pro.FingerprintFactory 
import com.fingerprintjs.android.fpjs_pro.FingerprintException 
import com.fingerprint.android.Configuration 
import com.fingerprint.android.FingerprintFactory 
import com.fingerprint.android.FingerprintException 

Class and interface renames

Several classes and interfaces were renamed to drop the legacy JS naming.

Android SDK v2	Android SDK v4
`FingerprintJSFactory`	`FingerprintFactory`
`FingerprintJS` (interface)	`Fingerprint` (interface)
`FingerprintJSProResponse`	`FingerprintResponse`

val client: FingerprintJS = FingerprintJSFactory(context).createInstance(config) 
val client: Fingerprint = FingerprintFactory(context).createInstance(config) 

client.getVisitorId { response: FingerprintJSProResponse -> ... } 
client.getVisitorId { response: FingerprintResponse -> ... } 

`FingerprintResponse` field changes

The response object is now flat and no longer exposes the nested fields that came from the old /products/identification/data/result response format.

Renamed

Android SDK v2	Android SDK v4
`response.requestId`	`response.eventId`

Added

Field	Type	Notes
`eventId`	`String`	Replaces `requestId`
`suspectScore`	`Int?`	Risk score from the server; `null` if not present

Removed

The following fields are no longer part of the response:

Removed field	Type
`requestId`	`String`
`visitorFound`	`Boolean`
`confidenceScore`	`ConfidenceScore`
`ipAddress`	`String`
`ipLocation`	`IpLocation?`
`osName`	`String`
`osVersion`	`String`
`firstSeenAt`	`Timestamp`
`lastSeenAt`	`Timestamp`

The data classes ConfidenceScore, Timestamp, and IpLocation (including the nested City, Country, Continent, and Subdivisions types) have been removed from the SDK entirely. See IP Geolocation for a replacement available in our Smart Signals product.

client.getVisitorId { response ->
    println(response.requestId) 
    println(response.visitorFound) 
    println(response.confidenceScore) 
    println(response.ipAddress) 
    println(response.firstSeenAt) 
    println(response.eventId) 
    println(response.visitorId) 
    println(response.suspectScore) 
    // ipAddress, confidenceScore, firstSeenAt, and similar fields are no longer available
}

`Configuration` changes

extendedResponseFormat: Boolean has been removed. The v4 API always returns a flat response, so the extended format toggle no longer exists.

Configuration(
    apiKey = "your_api_key",
    // ...
    extendedResponseFormat = true, 
)

Rename `requestId` to `eventId` on `Error` and `FingerprintException`

The requestId property on both Error and FingerprintException has been renamed to eventId.

client.getVisitorId(
    listener = { response -> ... },
    errorListener = { error ->
        println(error.requestId) 
        println(error.eventId) 
    }
)

try {
    val response = client.getVisitorId()
} catch (e: FingerprintException) {
    println(e.requestId) 
    println(e.eventId) 
}

Error class changes

Removed error classes

These error classes no longer exist in v4. Remove any when branches or isErrorType<T>() checks that reference them.

ApiKeyExpired
UnsupportedVersion
OriginNotAvailable
PackageNotAuthorized
HeaderRestricted
NotAvailableForCrawlBots
NotAvailableWithoutUA

New error classes

The following error classes are new in v4 and map to new server-side error codes.

New class	When it occurs
`SecretApiKeyRequired`	Secret API key header is missing
`SecretApiKeyNotFound`	No workspace found for the provided secret key
`VisitorNotFound`	Requested visitor does not exist
`ServiceUnavailable`	Server-side service unavailable
`SubscriptionRestricted`	Subscription is restricted
`FeatureNotEnabled`	Feature is not enabled for this workspace
`RequestNotFound`	Event or request not found
`StateNotReady`	Resource is not yet mutable, retry later
`MissingModule`	A required server module is missing
`PayloadTooLarge`	Request payload exceeded the size limit
`RulesetNotFound`	Specified ruleset not found
`EnvironmentRestricted`	Environment is restricted
`SubscriptionNotFound`	Subscription not found

If you have an exhaustive when on Error subtypes, add an else branch (or handle the new types explicitly) to avoid compile errors.

errorListener = { error ->
    when (error) {
        is ApiKeyExpired -> handleExpired() 
        is ApiKeyNotFound -> handleNotFound()
        is NetworkError -> handleNetwork()
        is ClientTimeout -> handleTimeout()
        is VisitorNotFound -> handleVisitorNotFound() 
        is ServiceUnavailable -> handleServiceUnavailable() 
        else -> logUnknown(error.requestId) 
        else -> logUnknown(error.eventId) 
    }
}

Android SDK changelog
Android SDK reference
Android Quickstart
Download our Android demo app from Google Play to see Fingerprint in action.

JavaScript Agent

Server API

Automation Intelligence API

Policy and Upgrades

Device Reputation Network API

Management API

Server SDKs

Migrating the Fingerprint Android SDK from v2 to v4

What’s new

Migration steps

Upgrade the MAJOR package version

Update imports

Class and interface renames

`FingerprintResponse` field changes

Renamed

Added

Removed

`Configuration` changes

Rename `requestId` to `eventId` on `Error` and `FingerprintException`

Error class changes

Removed error classes

New error classes

​What’s new

​Migration steps

​Upgrade the MAJOR package version

​Update imports

​Class and interface renames

​FingerprintResponse field changes

​Renamed

​Added

​Removed

​Configuration changes

​Rename requestId to eventId on Error and FingerprintException

​Error class changes

​Removed error classes

​New error classes

​Check out these related resources:

What’s new

Migration steps

Upgrade the MAJOR package version

Update imports

Class and interface renames

`FingerprintResponse` field changes

Renamed

Added

Removed

`Configuration` changes

Rename `requestId` to `eventId` on `Error` and `FingerprintException`

Error class changes

Removed error classes

New error classes

Check out these related resources: