Skip to content

Upgrade Guide

Jump to bottom
Jonathan Ellis edited this page Jun 13, 2022 · 87 revisions

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 false)
  • .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

Upgrading to v8.4

There are no code changes required to upgrade to v8.3.

Please note that the next major release of the iOS SDK (v9.0) will drop support for iOS 9.

Upgrading to v8.3

There are no code changes required to upgrade to v8.3.

Please note that the next major release of the iOS SDK (v9.0) will drop support for iOS 9.

Upgrading to v8.2

Carthage users

All users of Carthage should take note of the updated installation instructions. Now that Carthage 0.37.0 has been released and offers (limited) support for XCFrameworks, you should choose whether to migrate to XCFrameworks (recommended) or remain with traditional universal (fat) frameworks.

The installation instructions now also include a workaround for those Carthage users remaining with universal frameworks on Xcode 12. Cocoapods installation is entirely unaffected by these changes.

Upgrading to v8.1

The SDK will no longer stream to iProov's EU instance by default. You must now explicitly provide a streaming URL when launching an iProov claim.

Upgrading to v8.0

v8.0 is a major release and provides new APIs with breaking changes.

New connection callback statuses

v8.0 introduces connection callbacks, which means that the iProov UI is not displayed until the connection to iProov's servers has been established. This means that you can keep the user in your app and provide the appropriate UI until the connection has been established.

You must now implement new the .connecting and .connected statuses in the iProov callback. Objective-C users should also implement the relevant blocks.

If you do not wish to implement your own custom UI for connecting and revert to the legacy behavior from v7.5 and earlier, you can opt-out of this new feature by setting options.ui.useLegacyConnectingUI = true which will continue to show the connecting indication within the iProov SDK itself.

⚠️ NOTE: the useLegacyConnectingUI is deprecated, and will be removed in a future version of the SDK. All customers are advised to adopt the new connection callbacks as soon as possible.

Changes to .success & .failure statuses

In v7.0, the .success and .failure cases provided additional contextual information (token/reason/feedbackCode) directly in their associated values:

switch status {
   ...
   case let .success(token):
      ...
   case let .failure(reason, feedbackCode):
      ...
   ...
}

In v8.0, the success and failure cases have been changed to allow for further information to be returned, and allow future extensibility for even more values to be returned in the future.

You should be able to easily move from the v7 API (above) to the equivalent v8 API (below) simply as follows:

switch status {
   ...
   case let .success(result):
      let token = result.token
      ...
   case let .failure(result):
      let reason = result.reason
      let feedbackCode = result.feedbackCode
      ...
   ...
}

Changes to failures & errors

  • streamingError has been renamed to networkError.

  • The user_timeout and network_problem failures are now returned as networkErrors for improved consistency.

Changes to UI customization

There is a new option called options.ui.livenessTintColor. Customers who are using the new Liveness Assurance technology as part of Basic Face Verifier can use this option to set the tint color of the screen during the Liveness Assurance face scan.

Due to the new connection callback statuses, options.ui.loadingTintColor option has also been deprecated, as this only takes effect when the legacy connecting UI is displayed.

Changes to string localization

String key names been updated to align with the Android & Web SDKs. There have also been new strings introduced to support Liveness Assurance. Please consult the updated Localizable.strings file and ensure your localization keys and values match.

Cocoapods users

SwiftyJSON and KeychainAccess dependencies are no longer required. Therefore you can remove these pods from the workaround in your Podfile.

The new workaround is therefore as follows:

post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['iProov', 'Socket.IO-Client-Swift', 'Starscream'].include? target.name
        target.build_configurations.each do |config|
            config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
end

Upgrading to v7.5

Native Bridge users

SDK v7.5 includes Native Bridge 2.0, which provides a far simpler one-line integration between the iOS and Web SDKs, with a richer feature set and more reliable protocol. There are two implications of this:

  1. You must now use Web SDK v2.1.0 or newer, which includes support for Native Bridge 2.0

  2. You must update your WebView integration code to use the new Native Bridge 2.0 integration as follows:

    (i) You should remove the WKNavigationDelegate code, as it is no longer required to intercept URL navigation events.

    (ii) Instead, you should simply call webView.installIProovNativeBridge() as early as possible in your view controller lifecycle (e.g. viewDidLoad) which will add the Native Bridge functionality into the webview.

Please note that the legacy Native Bridge is no longer supported in SDK v7.5, so this is a mandatory upgrade.

Upgrading to v7.4

Cocoapods users

The XCFramework distribution of iProov is now the default for Cocoapods users. There are two implications of this:

  1. You must now use Cocoapods 1.9.0 or newer.

  2. The workaround applied to the bottom of your Podfile should be updated to include the iProov target in the list.

    The new Podfile workaround is therefore as follows:

    post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['iProov', 'KeychainAccess', 'Socket.IO-Client-Swift', 'Starscream', 'SwiftyJSON'].include? target.name
        target.build_configurations.each do |config|
            config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
end

    NOTE: As of Cocoapods 1.10 release (not yet released at the time of writing), this workaround should no longer be required.

Upgrading to v7.3

There are no code changes required to upgrade to v7.3.

Upgrading to v7.2

Cocoapods users

Due to the addition of module stability, you must add the following workaround to the bottom of your Podfile:

post_install do |installer|
    installer.pods_project.targets.each do |target|
      if ['KeychainAccess', 'Socket.IO-Client-Swift', 'Starscream', 'SwiftyJSON'].include? target.name
        target.build_configurations.each do |config|
            config.build_settings['BUILD_LIBRARY_FOR_DISTRIBUTION'] = 'YES'
        end
      end
    end
end

Failure to add this will cause your app to crash on launch. Consult the README for further details.

Carthage users

Due to the addition of module stability, you must now ensure that Carthage builds iProov's dependencies with the "Build Libraries for Distribution" option enabled.

This can be achieved as follows:

echo 'BUILD_LIBRARY_FOR_DISTRIBUTION=YES'>/tmp/iproov.xcconfig; XCODE_XCCONFIG_FILE=/tmp/iproov.xcconfig carthage build; rm /tmp/iproov.xcconfig

Failure to add this will cause your app to crash on launch. Consult the README for further details.

Localization changes

The changes required (if any) depend on your usage of the localizations features:

  • You require the SDK in English only

    • No changes are required.

  • Your app provided custom Localizable.strings translations

    • No changes are required.

  • You were using the options.ui.locale setting to force a given locale

    • This option is no longer available. You should override the Base localization in your app instead to customize/translate the strings.

  • You were using the nl/nn/nb/tr localizations provided with the SDK

    • These translations are no longer provided bundled with the SDK. If you wish to continue offering them, you need to bundle them within your app instead. If you wish to obtain a copy of these files, please contact iProov.

  • You are redistributing the iProov SDK within your own framework, and wish to provide localized strings in your framework

    • You should use the new options.ui.stringsBundle setting to pass your framework's bundle as the source of the strings files.

Fonts changes

options.ui.boldFont and options.ui.regularFont have both been combined into a single option named options.ui.font (which is effectively the same as regularFont, since the bold font is not used).

If you were using custom fonts provided by your app, you now need to specify it in your Info.plist instead of passing it into options.ui.fonts.

Upgrading from v7.2.0-beta1 to v7.2.0

Cocoapods users should add "Starscream" to the list of dependencies for which the module stability workaround is applied. See above (or the README) for further details.

Upgrading to v7.1

There are no code changes required to upgrade to v7.1.

Upgrading to v7.0

iProov v7 is a significant overhaul, and provides many new features, removes old features, and has breaking API changes.

Please consult the changelog for this release for further information about the changes in this release.

Follow the following steps to upgrade your app from v6 to v7:

  1. If you are upgrading from v6.2.1 or earlier: You first need to remove the workaround for Socket.IO-Client-Swift being compiled in Swift 3.x. You should delete the following code from your Podfile:
post_install do |installer|
    installer.pods_project.targets.each do |target|
        if target.name == 'Socket.IO-Client-Swift'
            target.build_configurations.each do |config|
                config.build_settings['SWIFT_VERSION'] = '3.2'
            end
        end
    end
end

  1. If you are currently using verify(withServiceProvider...) or enrol(withServiceProvider...): (...Which you should not be doing in any production apps!) You now need to call the iProov REST API yourself to obtain tokens, rather than relying on the SDK to do this for you. You can use the iOS API Client if you wish to continue with a purely on-device demo.

  2. Upgrade your IProov method calls to use the new public API. All calls should now be changed to IProov.launch(token:callback:). See the README for more information on this.

  3. If you are using any IProovConfig options: Update any use of IProovConfig to use the new Options struct instead. The commonly-used options are still there, however they are now better organised into sub-structs. Consult the README for more information on available options.

  4. If you make use of a custom baseURL: Instead of setting a base URL, you should now pass a streamingURL (for Socket.IO streaming) when launching iProov, with IProov.launch(streamingURL: "https://yoururl.com", token: ...).

  5. Adapt your user interface to handle the asynchronous nature of iProov v7. You can implement your own streaming progress UI, or allow the user to continue with activities whilst the capture streams in the background. Consult the Waterloo Bank sample app to see a simple example of using MBProgressHUD to provide a similar UX to iProov v6.

Upgrading to v6.0

If you are upgrading from a previous version of iProov, please note the following:-

  1. iProov is no longer distributed as a Git submodule, please use Cocoapods instead. Cocoapods allows much easier integration with your project, simpler integration with other libraries, and better distribution and version management.

  2. iProov is only compatible with Swift 4+ and Objective-C in Xcode 8. Please upgrade your project to Swift 4 before upgrading to iProov 6.x.

  3. Before upgrading your project, please remove iProov.framework, GPUImage.framework and SSKeychain.framework from your project, as all dependencies will now be handled automatically by Cocoapods.

  4. Please follow the “Installation” steps in the previous chapter to integrate Cocoapods with your project (if you haven’t already) and install iProov 6.x in your Xcode project.

  5. The public APIs of iProov have changed, and you will need to update your iProov method calls. Please consult the guide below for the new public iProov methods. The new APIs have been designed to be more Swift 3-like, make better use of Swift language features and conventions, as well as being easier to use. We always try and avoid making breaking API changes, however with the release of Swift 4 and iProov 6.0 we have taken this opportunity to fully modernise our API.

Clone this wiki locally