We have released a new major version of the Fingerprint iOS SDK v4.0.0, which allowed us to introduce breaking changes and requires you to manually migrate. The new iOS SDK aligns with the v4 event format. This includes a flattened response format, removed types, and a revised set of error codes. None of these changes affect the underlying identification 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 library and module were renamed from FingerprintPro to Fingerprint. Update your imports from import FingerprintPro to import Fingerprint.
The FingerprintProFactory type was renamed to FingerprintFactory. Update calls such as FingerprintProFactory.getInstance(...) to FingerprintFactory.getInstance(...).
The SDK is now distributed from a new Swift Package Manager repository, https://github.com/fingerprintjs/fingerprint-ios. Because this is a new package rather than a rename, you must remove the old package and add the new one.
The CocoaPods pod was renamed from FingerprintPro to Fingerprint-iOS. CocoaPods is still supported for now but is deprecated, see the CocoaPods section below.
The FPJSError error type was renamed to FPError.
The response object FingerprintResponse changed from a deeply nested shape to a flat one. Several legacy fields (confidence, ipLocation, firstSeenAt, and similar) have been removed, along with their supporting types (IPLocation, IPLocationSubdivision, IPGeoInfo, and SeenAt).
requestId is renamed to eventId on the response.
A new suspectScore field of type Int? is added to the response.
The extendedResponseFormat configuration flag has been removed as v4 always returns the flat format.
The APIError.Code enum has been revised, with some cases removed, some renamed, and new ones added to reflect new server-side error codes.
Swift upgraded from 5.9 to 6.
Dropped support for iOS 13.

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 iOS SDK to the latest v4 version.

Swift Package Manager

v4 is distributed from a new repository, https://github.com/fingerprintjs/fingerprint-ios. Because a new repository URL is a new package for Swift Package Manager, you can’t simply bump the version:

Remove the existing fingerprintjs-pro-ios package from your project.
Add the new package https://github.com/fingerprintjs/fingerprint-ios, and set the dependency rule to Up to Next Major Version starting from: "4.0.0".
Resolve packages.

For projects that declare dependencies in Package.swift, update the package URL and version:

.package(url: "https://github.com/fingerprintjs/fingerprintjs-pro-ios", from: "2.0.0"), 
.package(url: "https://github.com/fingerprintjs/fingerprint-ios", from: "4.0.0"), 

To keep using a previous (v2) version, continue using the old repository https://github.com/fingerprintjs/fingerprintjs-pro-ios.

CocoaPods

CocoaPods is still supported in v4, but the pod was renamed from FingerprintPro to Fingerprint-iOS (the Swift Package Manager product, as mentioned above, stays Fingerprint). Update your Podfile, then run pod update:

pod 'FingerprintPro', '~> 2.0'
pod 'Fingerprint-iOS', '~> 4.0'

Following the CocoaPods project’s own shutdown plans, it will stop accepting new versions in December 2026. Existing versions will keep working, but we recommend migrating to Swift Package Manager, which is the preferred installation method.

Update imports, factory, and error type

The library and module were renamed from FingerprintPro to Fingerprint. Update every import across your project. A project-wide Replace All in your IDE is the quickest way to do this.

import FingerprintPro
import Fingerprint

The FingerprintProFactory type was renamed to FingerprintFactory. Update any calls that create a client instance.

let client = FingerprintProFactory.getInstance(configuration) 
let client = FingerprintFactory.getInstance(configuration) 

The FPJSError error type was renamed to FPError. Update any typed error handling that references it.

} catch let error as FPJSError { 
} catch let error as FPError { 

`FingerprintResponse` field changes

The response object is now flat and no longer exposes the nested fields that came from the v3 response format.

Renamed

iOS SDK v2	iOS 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`	`Bool`
`confidence`	`Float`
`ipAddress`	`String?`
`ipLocation`	`IPLocation?`
`firstSeenAt`	`SeenAt?`
`lastSeenAt`	`SeenAt?`

The IPLocation, IPLocationSubdivision, IPGeoInfo, and SeenAt structs have been removed from the SDK entirely. See IP Geolocation for a replacement available in our Smart Signals product. Indicates the location as deduced from the IP address.

let response = try await fingerprintClient.getVisitorIdResponse()

print(response.requestId) 
print(response.visitorFound) 
print(response.confidence) 
print(response.ipAddress) 
print(response.firstSeenAt) 
print(response.eventId) 
print(response.visitorId) 
print(response.suspectScore) 
// ipAddress, confidence, firstSeenAt, and similar fields are no longer available

`Configuration` changes

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

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

Error handling changes

The APIError.Code enum has been revised for v4. Some cases were removed, some renamed, and new ones added to reflect new server-side error codes. Update any exhaustive switch statements over APIError.Code to handle the current set of cases. The complete set of APIError.Code cases in v4:

Case	Raw value
`requestCannotBeParsed`	`request_cannot_be_parsed`
`requestReadTimeout`	`request_read_timeout`
`secretApiKeyRequired`	`secret_api_key_required`
`secretApiKeyNotFound`	`secret_api_key_not_found`
`publicApiKeyRequired`	`public_api_key_required`
`publicApiKeyNotFound`	`public_api_key_not_found`
`subscriptionNotActive`	`subscription_not_active`
`wrongRegion`	`wrong_region`
`featureNotEnabled`	`feature_not_enabled`
`visitorNotFound`	`visitor_not_found`
`tooManyRequests`	`too_many_requests`
`stateNotReady`	`state_not_ready`
`failed`	`failed`
`eventNotFound`	`event_not_found`
`missingModule`	`missing_module`
`payloadTooLarge`	`payload_too_large`
`serviceUnavailable`	`service_unavailable`
`rulesetNotFound`	`ruleset_not_found`
`invalidProxyIntegrationSecret`	`invalid_proxy_integration_secret`
`proxyIntegrationSecretEnvironmentMismatch`	`proxy_integration_secret_environment_mismatch`
`invalidProxyIntegrationHeaders`	`invalid_proxy_integration_headers`
`subscriptionRestricted`	`subscription_restricted`
`environmentRestricted`	`environment_restricted`
`subscriptionNotFound`	`subscription_not_found`
`installationMethodRestricted`	`installation_method_restricted`

If you have an exhaustive switch on APIError.Code, add a default branch (or handle the new cases explicitly) to avoid compile errors.

iOS SDK changelog
iOS SDK reference
iOS Quickstart
Download our iOS demo app from App Store 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 iOS SDK from v2 to v4

What’s new

Migration steps

Upgrade the MAJOR package version

Swift Package Manager

CocoaPods

Update imports, factory, and error type

`FingerprintResponse` field changes

Renamed

Added

Removed

`Configuration` changes

Error handling changes

​What’s new

​Migration steps

​Upgrade the MAJOR package version

​Swift Package Manager

​CocoaPods

​Update imports, factory, and error type

​FingerprintResponse field changes

​Renamed

​Added

​Removed

​Configuration changes

​Error handling changes

​Check out these related resources:

What’s new

Migration steps

Upgrade the MAJOR package version

Swift Package Manager

CocoaPods

Update imports, factory, and error type

`FingerprintResponse` field changes

Renamed

Added

Removed

`Configuration` changes

Error handling changes

Check out these related resources: