1.1 -> 2.0 Migration Guide

Although we tried to keep the API as stable as possible, we’ve made some changes in the name of simplification and new feature support. This guide should help with an effortless migration from previous version (1.1) to 2.0.

Dependency Management

We started to distribute the library as a XCFramework binary instead of source code. Although that translates to a significant change under the hood, the upgrade should be as easy as with any other major version. Following our branding change, we have also renamed the library to FingerprintPro instead of the old FingerprintJSPro. The name change has to be reflected when using package management tools.

// Example dependency in Package.swift
let package = Package(
  // ...
  dependencies: [
        .package(url: "https://github.com/fingerprintjs/fingerprintjs-pro-ios", from: "2.0.0")
  ],
  // ...
)
# Podfile
pod 'FingerprintPro', '~> 2.0' # Do not forget about the name change

Naming Changes

Following our company branding change, we’ve renamed all references to the library itself and everything else we could in our codebase to reflect the new brand name.

  • Factory class FingerprintJSProFactory has been renamed to FingerprintProFactory.
  • The main client protocol FingerprintJSProClient has been renamed to FingerprintClientProviding
  • Library/Module is now FingerprintPro (was FingerprintJSPro before)

Region and Custom Domains

Region configuration in the factory has been refactored into an enum. The enum now includes specific case for custom domains. Because there are now more options, a Configuration object was added as a parameter to the factory API.

Setting a Region

let client = FingerprintJSProFactory.getInstance(
  token: "<apiKey>",
  url: nil,
  region: "eu"
)
let configuration = Configuration(apiKey: "apiKey", region: .eu)
let client = FingerprintProFactory.getInstance(configuration)

Setting a Custom Domain

let client = FingerprintJSProFactory.getInstance(
  token: "<apiKey>",
  url: "https://customdomain.com/",
  region: nil
)
let customDomain: Region = .custom(domain: "https://customdomain.com")
let configuration = Configuration(apiKey: "<apiKey>", region: customDomain)
let client = FingerprintProFactory.getInstance(configuration)

Sending Tags

The tags object has been reworked and moved to a new Metadata structure. The API for tags is also now limited to support only objects that can be encoded into JSON. The API had looser type restrictions before that allowed the programmer to send objects that weren’t encodable into JSON, leading to an exception. That should be impossible now and should be caught during compilation.

let tags: Tags = ["sessionCount": 10, "sessionId": "abcefgh"] 
client.getVisitorId(tags) { result in
	// process result
}
var metadata = Metadata()
metadata.setTag(10, forKey: "sessionCount")
metadata.setTag("abcdefgh", forKey: "sessionId")

client.getVisitorId(metadata) { result in
	// process result
}

Optional: Start Using the async/await API

The library now has async/await support, further simplifying the usage of the API. Instead of processing a result, the async/await API throws an error instead, letting the programmer to handle the exception in a do/catch block.

client.getVisitorId() { result in
  switch(result) {
	case .success(let visitorId):
		// process visitorId
	case .failure(let error):
		// process error
	}
}
do {
   let visitorId = try await client.getVisitorId()
} catch {
 // process FPJSError
}

New Features

We have introduced several new features that weren’t included in the previous version. Most notably:

  • Linked id support
  • Extended result contains confidence score and other useful information