Skip to content

Upgrade Guide

Jump to bottom
Will Morgan edited this page Feb 2, 2022 · 26 revisions

This guide lists practical steps to ensure your app can smoothly upgrade from release to release, accounting for any breaking or incremental changes.

Upgrading from v3.3.x to v3.4.x

We have changed the order that events fire:

  • If enable_camera_selector is enabled, the multiple_cameras event now runs before ready and runs only once.

In Liveness, we've introduced another error code to help distinguish "invalid or non-existent sensor data" from "permission denied":

  • Added error_device_motion_denied feedback code and language string, along with error_device_motion_denied_message language string.

There have been some changes to how we message errors, and we have added some new language strings:

  • Language strings for the ready slot and event:
    • iproov_ready_title to allow internationalisation of "Ready to iProov" on the ready callback
    • iproov_ready_button to allow internationalisation of "Scan face" for the ready callback button
  • Language strings for error messages - if your integration customises language strings, we advise you to update those strings to implement the new message format described below:
    • Error messaging and language - We have increased the level of detail, see iproov-en.json for the new strings:
    • When the SDK runs any of the following callbacks: error, cancelled, interrupted, permission_denied, no_camera or unsupported:
      • The language string mapping to the feedback event property is now displayed as the heading.
      • A new language string has been added for each feedback code, suffixed with _message.
      • Example: error_no_camera is the heading term, defaulting to "We couldn't find a camera connected to your device"
      • Example: error_no_camera_message is the text term displayed beneath the heading, defaulting to "A camera must be available to use iProov"
  • If your integration specifies language strings but doesn't implement the new _message suffix, then we fall back to the old behaviour:
    • Heading using the "error" language term, and text using the corresponding feedback code's language term.

Please see the iproov-en.json base file as shipped in 3.4.0 for a full and comprehensive reference of all language strings.

Upgrading from v3.2.x to v3.3.x

We don't require any integration changes between these versions.

Upgrading from v3.1.x to v3.2.x

You'll need to implement the following language strings, if desired:

  • error_network - error code emitted if we don't receive a response from our backend in time

Rename:

  • user_timeout to failure_user_timeout in the failed event

Upgrading from v3.0.x to v3.1.x

Support Checker

  • The iProovSupport checker:
    • In 3.1.0, we ship a separate entrypoint which contains iProovSupport only. This has virtually no size impact on your page, meaning you can split your JavaScript payload to only load the full iProov Web SDK when you need it. This saves precious bytes.
    • This means that using a module bundler like Webpack, you can now import { iProovSupport } from "@iproov/web/iProovSupport"
    • Script tag integrations can still access window.IProov.IProovSupport for the time being.

Assets and CDN

  • assets_url:
    • If you have specified an assets_url, you will need to remove the /assets suffix from the URL, i.e.: https://mycdnproxy.com/assets becomes https://mycdnproxy.com
    • In production we recommend you to self-host assets.

Customisation

  • streaming and streamed events:
    • Our streamed event now reflects our documentation. If you were previously relying on this to do something in your app's UI, simply change it to streaming. The payload remains identical.

i18n / Multilang

  • Language strings:
    • Some strings have been renamed, redundant ones have been removed and others added. Review your language strings and compare to iproov-en.json.

Webviews, PWAs, etc

  • Progressive Web Apps, Webview Apps and Native Bridge
    • iOS 14.3 now supports Webview based apps that implement WKWebView, which means that we can now bring you iProov Web on popular iOS alternative browsers such as Chrome, Edge, Firefox and Brave, without the use of Native Bridge. For the time being, these are the only WKWebview browsers which appear to work well, so we need to allowlist these in our support checker pending further review.
    • Android and iOS Native Bridge are still available for consumption, and we'll continue developing and improving the crossover product as it still delivers a great boost for integrators already building webview based apps, especially for lower end devices where native performance is needed.

Upgrading from v2.2.x to v3.0.x

Assets and CDN

NB: For integrators upgrading straight from 2.x to 3.1.x, please skip straight to the 3.1.x assets section - this section can be skipped.

Apart from fonts, usage of the CDN is no longer necessary to load our dependencies. Fonts are still loaded through the CDN for the best browser performance and to avoid blocking downloads. This method also avoids penalising integrations that override any fonts in our default interface.

Customisation

  • Rename the "aborted" slot and event handlers to "cancelled".
  • Optionally implement a slot and event handler for "interrupted".

Internationalisation

Ensure that any language customisation needed for iProov Liveness is applied to the new Liveness strings: - progress_assessing_liveness - prompt_liveness_align_face - prompt_liveness_no_face - prompt_liveness_scan_completed

Native Bridge

If you haven't already, ensure that you have migrated from the legacy Native Bridge implementation described in the v2.0 -> v2.1 section.

Upgrading from v2.1.x to v2.2.x

Slots integration

Ensure that .iproov-lang-heading and .iproov-lang-term classes are added, as the deprecated behaviour of searching for h3 and div tags has been removed in this release line.

Upgrading from v2.0.x to v2.1.x

Native Bridge

To upgrade to the new Native Bridge functionality:

  1. Upgrade to @iproov/web@^2.1.
  2. Remove the prefer_app setting.
  3. If in use, rename prefer_app_options to native_sdk_options.

To support webview based apps that don't yet contain the Native Bridge 2.0 compatible iOS and Android SDKs ("legacy webview apps"):

When the integrator detects a legacy webview app, when instantiating iProov Web:

  1. Set the legacy_native_bridge option to true.
  • This would look something like: if (isLegacyWebViewApp) { element.setAttribute("legacy_native_bridge", "true"); }
  • If this is not set, then in the case of old SDKs, the unsupported event would fire rather than fail silently. This is the current scenario in Web SDK 2.0.x.
  • Note that enabling legacy mode means the SDK must be present, so it cannot be set for all user sessions (eg: desktop.)
  1. If using the standalone support checker, it must be instantiated with the legacyNativeBridge option: new IProovSupport(logger, { legacyNativeBridge: true });
  • The logger option can be null to fall back to console. Otherwise, any logger implementing the standard NodeJS or browser console logger levels will suffice.

Note that the above steps must only be taken when the integrator detects an old webview app.

To effectively support legacy cases, control is handed to the integrator to enable as they see fit. Legacy Native Bridge doesn't have any fine-grained mechanism to check whether a native SDK is available or not, and experience with customers implementing the Web SDK has shown that the integrator themselves have far better knowledge of when legacy mode would need to be invoked than the Web SDK could determine.

As Native Bridge legacy mode overrides the default Web functionality and forces traffic to the Native SDK, this means that legacy mode must only be switched on by the integrator on a per-user basis where they are able to detect the requirement for native (i.e. iOS in a Webview), while versions of their app are in the wild that still have the Native Bridge 1.0 capability.

The presence of a detected Native Bridge 2.0 installation takes precedence over legacy mode. So a given webview app could upgrade their iProov Native SDK with no immediately required action from the iProov Web integrator. In other words, until legacy mode is removed, this is a "set and forget" solution.

Clone this wiki locally