Skip to content

Upgrading to SDK v9.x

Jump to bottom
Braden edited this page Apr 3, 2023 · 5 revisions

⚠️ This document relates to deprecated or obsolete SDK versions. For details regarding upgrading to the latest SDK version, consult the main Upgrade Guide.

Upgrading to v9.5.2

If you are using Carthage to install iProov, you need to update your cartfile to include the following:

binary "https://raw.githubusercontent.com/iProov/ios/9.5.2/carthage/IProov.json" == 9.5.2
github "socketio/socket.io-client-swift" == 16.0.1

Upgrading to v9.5

UI changes

Colors

Some of the default colors have been tweaked in order to meet the color contrast requirements of WCAG 2.1 AA.

If you wish to revert to the old default colors, you can implement the following:

options.ui.genuinePresenceAssurance.notReadyOvalStrokeColor = UIColor(red: 245.0 / 255.0, green: 166.0 / 255.0, blue: 35.0 / 255.0, alpha: 1.0)
options.ui.genuinePresenceAssurance.readyOvalStrokeColor = UIColor(red: 1.0 / 255.0, green: 191.0 / 255.0, blue: 70.0 / 255.0, alpha: 1.0)

However, please note that these colors are not WCAG 2.1 AA compliant.

New default behavior for options.ui.title

In previous SDK versions, setting options.ui.title to nil (the default) would result in an auto-generated title message of the format (Enrol|Verify) to {SP name} as {username}.

In SDK v9.5, when options.ui.title is set to nil, no title is displayed.

Localizable strings changes

With the addition of WCAG 2.1 AA compliance and improved VoiceOver prompts for users with screen readers enabled, the following strings have been added to the SDK and require localization:

  • IProov_AlignFaceVoiceOverPrompt - "Hold the device in front of your face and look at the screen"
  • IProov_CloseButtonAccessibilityLabel - "Close"

With the removal of the auto-generated title message, the following strings have been removed from the SDK, and no longer require localization:

  • IProov_Authenticate
  • IProov_Error
  • IProov_MessageFormatWithUsername

Upgrading to v9.4

New UI customization options

SDK v9.4 introduces various new UI customization options for additional flexibility in the iProov UI:

  • .ui.floatingPromptRoundedCorners - specifies whether the floating prompt should have rounded or square corners (default true)
  • .ui.genuinePresenceAssurance.readyFloatingPromptBackgroundColor - background color used for the floating prompt in the GPA "ready" state
  • .ui.genuinePresenceAssurance.notReadyFloatingPromptBackgroundColor - background color used for the floating prompt in the GPA "not ready" state
  • .ui.genuinePresenceAssurance.readyOverlayStrokeColor - stroke color used for the oval and reticle lines in the GPA "ready" state
  • .ui.genuinePresenceAssurance.notReadyOverlayStrokeColor - stroke color used for the oval and reticle lines in the GPA "not ready" state
  • .ui.livenessAssurance.floatingPromptBackgroundColor - background color used for the floating prompt for LA transactions
  • .ui.livenessAssurance.overlayStrokeColor - stroke color used for the oval and reticle lines for LA transactions

Note that the default for all new colors is nil. When set to nil, the existing pre-9.4 color scheme rules will be automatically applied.

Swift Package Manager

The iProov iOS Biometrics SDK now supports Swift Package Manager. Consult the README for installation instructions.

Please note that we continue to recommend Cocoapods for the easiest and simplest installation.

Example app

The method of specifying credentials for the Example app has changed. Previously, credentials were set directly in ViewController.swift.

Starting in SDK v9.4, the file Credentials.example.swift should be renamed to Credentials.swift and then updated with your API credentials.

API client

The API client was previously hosted separately in the ios-api-client repository.

Starting in SDK v9.4, the API client is now hosted in the iProovAPIClient folder in this repository.

The API client is still v1.1.0 and remains unchanged aside from some minor documentation updates and code formatting.

If you are using the iProov iOS API Client, you should update your Podfile from:

pod 'iProovAPIClient', :git => 'https://github.com/iProov/ios-api-client.git'

to:

pod 'iProovAPIClient', :podspec => 'https://raw.githubusercontent.com/iProov/ios/master/iProovAPIClient/iProovAPIClient.podspec'

Remember that the iProov iOS API Client is for development and debugging only. You should never embed your API secret within a production app.

Upgrading to v9.3

Xcode compatibility

SDK v9.3 requires Xcode 13.0 or above. Users of Xcode 12 should upgrade to Xcode 13, or continue using SDK v9.2.

New option: options.ui.floatingPromptEnabled

The iProov Biometrics SDK now has a new UI which floats the instructions prompt over the user's face instead of containing it within the footer bar. By default, the new UI is disabled. To enable it, you can set options.ui.floatingPromptEnabled = true.

options.ui.footerTextColor renamed to options.ui.promptTextColor

options.ui.footerTextColor is deprecated. You should now use options.ui.promptTextColor instead which will apply the text color to either the floating prompt (new UI) or footer prompt (existing UI) depending on the setting of options.ui.floatingPromptEnabled.

For backwards-compatibility purposes, options.ui.footerTextColor is automatically bridged to option.ui.promptTextColor for both getting and setting.

Carthage improvements

Developers using Carthage are strongly recommended to upgrade to Carthage v0.38.0 which has full support for XCFrameworks. iProov SDK v9.3.1 has full support for XCFrameworks when using Carthage v0.38.0, automatic fallback to universal frameworks for v0.37.0 and earlier and an improved workaround script for Xcode 13. See the updated documentation for details.

Upgrading to v9.2

There are no code changes required to upgrade to v9.2.

Please note that the iOS SDK will soon drop support for Xcode 12. You are advised to upgrade to Xcode 13 at your earliest convenience.

Upgrading to v9.1

Xcode compatibility

Users of Xcode 13 should immediately upgrade to SDK v9.1 or follow the Guidance for Users of Xcode 13.

Users of prior versions of Xcode, please be aware that a future version of the iProov SDK will drop support for Xcode <13. Starting April 2022, all iOS and iPadOS apps submitted to the App Store must be built with Xcode 13.

You are therefore advised to upgrade to Xcode 13 at your earliest convenience.

Changes to certificate pinning

options.network.certificates has changed type from [String] to [Any]. It is now possible to pass a mixed array containing elements of either:

  • String values (existing behaviour) - these will be treated as paths to the certificate (included in the app bundle).
  • Data values (new behaviour) - these will be treated as the certificates themselves.

Upgrading to v9.0

Upgrading to SDK v9 will be very straightforward for most customers, with minimal breaking changes.

Support dropped for iOS 9

Support has been dropped for iOS 9. The SDK now supports iOS 10+ only.

If your app still needs to support iOS 9, you can use the #if canImport(iProov) compiler control statement to conditionally import iProov on iOS 10+ devices only.

Changes to UI customization options

The paths of various UI customization options has been updated to separate the Genuine Presence and Liveness Assurance UI options:

Old name New name
options.ui.autoStartDisabled options.ui.genuinePresenceAssurance.autoStartDisabled
options.ui.notReadyTintColor options.ui.genuinePresenceAssurance.notReadyTintColor
options.ui.readyTintColor options.ui.genuinePresenceAssurance.readyTintColor
options.ui.progressBarColor options.ui.genuinePresenceAssurance.progressBarColor
options.ui.livenessTintColor options.ui.livenessAssurance.primaryTintColor
options.ui.livenessScanningTintColor options.ui.livenessAssurance.secondaryTintColor

Changes to error handling

SDK v9 simplifies error handling by removing the .encoderError, .cameraError and .lightingModelError errors and replaces them with a new .unexpectedError error case which is designed to handle all current and future unexpected and unrecoverable errors.

Updated strings for localization

Due to removal of the above error types, the following strings have been removed from the SDK, and no longer require localizations:

  • IProov_ErrorEncoder
  • IProov_ErrorEncoderUnknownMessage
  • IProov_ErrorEncoderCodeMessage
  • IProov_ErrorLightingModel
  • IProov_ErrorCamera

There is also the introduction of the following new string, along with the default English text:

  • IProov_ErrorUnexpected - "Unexpected error"

Removal of redundant options

  • options.ui.useLegacyConnectingUI and the corresponding options.ui.loadingTintColor were deprecated in v8 and have now been removed from the SDK. If you have not yet migrated to the new connection callback status introduced in v8, you are now required to do so.

  • options.ui.scanLineDisabled has been removed. It is no longer possible to disable the scan-line during flashing in Genuine Presence Assurance claims.

  • options.network.certificatePinningDisabled has been removed. If you wish to disable certificate pinning (which should never be done for production apps!) you can now achieve this by simply passing an empty array to options.network.certificates instead.

Objective-C name changes

To prevent name clashes with classes that may already exist within your app or other dependencies, all iProov SDK Objective-C class names are now prefixed with IP:

Old name New name
IProov IProov
Options IPOptions
UIOptions IPUIOptions
NetworkOptions IPNetworkOptions
CaptureOptions IPCaptureOptions
Filter IPFilter
SuccessResult IPSuccessResult
FailureResult IPFailureResult

Please note that these changes affect Objective-C users only, the Swift class names remain unchanged.

Carthage changes

Carthage users need to upgrade their version of Socket.IO, this will not happen automatically.

Change the following line of your Cartfile:

github "socketio/socket.io-client-swift" == 15.2.0

To:

github "socketio/socket.io-client-swift" == 16.0.1
Clone this wiki locally