> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fingerprint.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrating the Fingerprint iOS SDK from v2 to v4

> This guide covers all breaking changes introduced in version `4.0.0` of the Fingerprint iOS SDK and outlines the steps required to migrate an existing v2 integration.

We have released a new major version of the [Fingerprint iOS SDK v4.0.0](https://docs.fingerprint.com/docs/changelog-ios-sdk#august-2026), 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.

<Warning>
  * 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](https://docs.fingerprint.com/reference/migrating-from-v3-to-v4#client-sdk-compatibility-for-javascript-agent-v4) 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.
</Warning>

# 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:

1. Remove the existing `fingerprintjs-pro-ios` package from your project.
2. 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"`.
3. Resolve packages.

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

<CodeGroup>
  ```swift Package.swift theme={"theme":"github-dark-dimmed"}
  .package(url: "https://github.com/fingerprintjs/fingerprintjs-pro-ios", from: "2.0.0"), // [!code --]
  .package(url: "https://github.com/fingerprintjs/fingerprint-ios", from: "4.0.0"), // [!code ++]
  ```
</CodeGroup>

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

### 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`:

<CodeGroup>
  ```ruby Podfile theme={"theme":"github-dark-dimmed"}
  pod 'FingerprintPro', '~> 2.0' # [!code --]
  pod 'Fingerprint-iOS', '~> 4.0' # [!code ++]
  ```
</CodeGroup>

<Warning>
  Following the [CocoaPods project's own shutdown plans](https://blog.cocoapods.org/CocoaPods-Specs-Repo/), 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.
</Warning>

## 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.

<CodeGroup>
  ```swift Rename the import theme={"theme":"github-dark-dimmed"}
  import FingerprintPro // [!code --]
  import Fingerprint // [!code ++]
  ```
</CodeGroup>

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

<CodeGroup>
  ```swift Rename the factory theme={"theme":"github-dark-dimmed"}
  let client = FingerprintProFactory.getInstance(configuration) // [!code --]
  let client = FingerprintFactory.getInstance(configuration) // [!code ++]
  ```
</CodeGroup>

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

<CodeGroup>
  ```swift Rename the error type theme={"theme":"github-dark-dimmed"}
  } catch let error as FPJSError { // [!code --]
  } catch let error as FPError { // [!code ++]
  ```
</CodeGroup>

## `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](https://docs.fingerprint.com/docs/smart-signals-reference#ip-geolocation) for a replacement available in our Smart Signals product. Indicates the location as deduced from the IP address.

<CodeGroup>
  ```swift FingerprintResponse field changes theme={"theme":"github-dark-dimmed"}
  let response = try await fingerprintClient.getVisitorIdResponse()

  print(response.requestId) // [!code --]
  print(response.visitorFound) // [!code --]
  print(response.confidence) // [!code --]
  print(response.ipAddress) // [!code --]
  print(response.firstSeenAt) // [!code --]
  print(response.eventId) // [!code ++]
  print(response.visitorId) // [!code ++]
  print(response.suspectScore) // [!code ++]
  // ipAddress, confidence, firstSeenAt, and similar fields are no longer available // [!code ++]
  ```
</CodeGroup>

## `Configuration` changes

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

<CodeGroup>
  ```swift Remove extendedResponseFormat theme={"theme":"github-dark-dimmed"}
  let configuration = Configuration(
      apiKey: "your_api_key",
      // ...
      extendedResponseFormat: true // [!code --]
  )
  ```
</CodeGroup>

## 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.

### Check out these related resources:

* [iOS SDK changelog](/docs/changelog-ios-sdk#august-2026)
* [iOS SDK reference](/docs/ios-sdk)
* [iOS Quickstart](/docs/ios-quickstart)
* Download our [**iOS demo app**](https://apps.apple.com/us/app/fingerprint-pro/id1644105278) from App Store to see Fingerprint in action.