Upgrade Guide

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 v4.2.1 to v5.0.0

Iframe Bridge Removal

We no longer support integrations using iframes on iOS 14 and lower due lack of support on motion sensor data which we require. The iframe bridge feature has been removed from the SDK, you should remove the iframe_bridge event handler and any associated code.

All devices attempting to make a claim will be marked as unsupported.

Incorrect Failure Reasons

In previous versions we treated failure_user_timeout and failure_not_supported errors as failures which were incorrect. We've fixed this, if this error occurs you'll receive this in the error event as error_user_timeout and error_not_supported.

Motion Permission in GPA

We've included motion data as part of a GPA claim. This change has introduced a new permission prompt which appears only on iOS and iPadOS devices after clicking the start button.

As with any other permission request, this is not compatible with using JavaScript to click buttons due to user gesture limitations browsers enforce.

Language and Feedback Code Changes

• New failure code: failure_multiple_faces
• Changed: user_cancelled to canceled_user
• Changed: client_error to error_client
• Changed: failure_user_timeout to error_user_timeout. See explanation
• Removed: failure_not_supported, please use current key error_not_supported. See explanation

The following failure reasons are now treated as errors:

• failure code user_timeout now corresponds to error_user_timeout
• failure code not_supported now corresponds to error_not_supported

Upgrading from v4.x.x to v4.2.0

Options

We've introduced color customization for the header bar background. By default, the header is transparent and you can change this by adding header_background_color option to your color config, i.e.

{
  header_background_color: "rgba(255, 0, 0, 0.8)",
  //... other color options
}

Motion Permissions

On iOS and iPad devices, we have moved the motion permissions request to the permission event. This isn't a breaking change as current functionality works as expected. This change has been made to cater for limitations with how permissions are managed in iOS and iPads.

The noticeable difference here is due to iOS and iPads not having the ability to test if motion permission has been granted previously, we instead need to request again on each transaction.

We are actively looking at ways of improving this and will release updates as and when we can.

Upgrading from v3.6.x to v4.0.0

Known Issues

Occasional single frame flickers on devices that can support high FPS mode

See the full list of known issues here.

Events

The main flow of events has not been changed in 4.0.0 except for the removal of interrupted, the only change that needs to be made is to switch the handlers logic over to the cancelled event.

Options

With a brand new UI, there has been a large amount of UI, Language strings and Color option changes. You can view the full list of removals, additions and changes here.

We've also added two new filters: clear and blur.

Native SDK

The schema for Native SDK integrations has been updated. Here are a couple of examples of the new schema:

Example 1:

	{\"filter\":{\"type\":\"line_drawing\",\"style\":\"shaded\"},\"prompt_text_color\":\"#98049B\"}",

Example 2:

	{\"filter\":{\"style\":\"vibrant\"},\"title\":\"NB Test\"}",

For more information, please refer to the following documentation for iOS and Android

Version Comparison Table

Web SDK v3.6.1	Web SDK v4.0.0
Options
network_timeout	network_timeout
base_url	base_url
assets_url	assets_url
logo	logo
close_button	close_button
custom_title	custom_title
aria_live	aria_live
filter	filter (added clear and blur)
floating_prompt_rounded_corners	prompt_rounded_corners
enable_floating_prompt	removed
csp_nonce	csp_nonce
allow_landscape	allow_landscape
show_countdown	show_countdown
enable_camera_selector	enable_camera_selector
debug	debug
kiosk_mode	kiosk_mode
Color Options (when kiosk mode is disabled)
background_color	removed
header_background_color	removed
header_text_color	removed
line_color	removed
loading_tint_color	removed
no_face_found_color	removed
not_ready_tint_color	removed
oval_scanning_color	removed
ready_tint_color	removed
footer_background_color	footer_background_color
footer_text_color	footer_text_color
progress_bar_color	progress_bar_color
loading_tint_color	loading_tint_color
gpa_not_ready_overlay_stroke_color	removed
gpa_ready_overlay_stroke_color	removed
gpa_not_ready_floating_prompt_background_color	removed
gpa_ready_floating_prompt_background_color	removed
liveness_tint_color	removed
liveness_scanning_tint_color	removed
liveness_overlay_stroke_color	removed
liveness_floating_prompt_background_color	prompt_background_color
n/a	liveness_oval_stroke_color
n/a	liveness_completed_oval_stroke_color

User Feedback Codes

Several new user feedback codes were added to provide more granular instructions to users on failures. You can find the full list of available language strings here.

• misaligned_face
• eyes_closed
• face_too_far
• face_too_close
• sunglasses
• obscured_face

ambiguous_outcome has been replaced with unknown which translates to Try Again.

Version Comparison Table

Web SDK v3.6.1	Web SDK v4.0.0
camera_next_button_aria	camera_next_button_aria
camera_next_loader_aria	removed
client_camera	client_camera
client_error	client_error
close_button_aria	close_button_aria
enrol	removed
error	error
error_asset_fetch	error_asset_fetch
error_asset_fetch_message	error_asset_fetch_message
error_camera	error_camera
error_camera_message	error_camera_message
error_camera_in_use	error_camera_in_use
error_camera_in_use_message	error_camera_in_use_message
error_camera_not_supported	error_camera_not_supported
error_camera_not_supported_message	error_camera_not_supported_message
error_camera_permission_denied	error_camera_permission_denied
error_camera_permission_denied_message	error_camera_permission_denied_message
error_device_motion_denied	error_device_motion_denied
error_device_motion_denied_message	error_device_motion_denied_message
error_device_motion_unsupported	error_device_motion_unsupported
error_device_motion_unsupported_message	error_device_motion_unsupported_message
error_fullscreen_change	error_fullscreen_change
error_fullscreen_change_message	error_fullscreen_change_message
integration_unloaded	error_integration_unloaded
error_invalid_token	error_invalid_token
error_invalid_token_message	error_invalid_token_message
error_network	error_network
error_network_message	error_network_message
error_no_camera	error_no_camera
error_no_camera_message	error_no_camera_message
error_no_face_found	error_no_face_found
error_no_face_found_message	error_no_face_found_message
error_not_supported	error_not_supported
error_not_supported_message	error_not_supported_message
error_server	error_server
error_server_message	error_server_message
error_token_timeout	error_token_timeout
error_token_timeout_message	error_token_timeout_message
error_too_many_requests	error_too_many_requests
error_too_many_requests_message	error_too_many_requests_message
error_transaction_cancelled	error_transaction_cancelled
failed	failed
failure_ufc_open_eyes	failure_eyes_closed
failure_ufc_move_away	failure_face_too_close
failure_ufc_move_closer	failure_face_too_far
failure_ambiguous_outcome	failure_unknown
failure_lighting_backlit	removed
failure_lighting_face_too_bright	removed
failure_lighting_flash_reflection_too_low	removed
failure_lighting_too_dark	removed
failure_motion_too_much_mouth_movement	removed
failure_motion_too_much_movement	failure_too_much_movement
failure_user_timeout	failure_user_timeout
failure_ufc_unknown	failure_unknown
failure_ufc_keep_still	removed
failure_ufc_too_bright	failure_too_bright
failure_ufc_too_dark	failure_too_dark
failure_ufc_line_up_face	failure_misaligned_face
n/a	failure_network_problem
n/a	failure_not_supported
failure_ufc_sunglasses	failure_sunglasses
failure_ufc_obscured_face	failure_obscured_face
iframe_bridge_title	iframe_bridge_title
iframe_bridge_button	iframe_bridge_button
iproov_ready_title	iproov_ready_button
iproov_ready_button	iproov_ready_title
iproov_success	iproov_success
label_camera_selector	label_camera_selector
n/a	label_secured_by_iproov_aria
language_file	language_file
logo_aria	logo_aria
passed	passed
progress_assessing_genuine_presence	progress_assessing_genuine_presence
progress_assessing_liveness	progress_assessing_liveness
progress_confirming_identity	progress_confirming_identity
progress_creating_identity	progress_creating_identity
progress_finding_face	progress_finding_face
progress_identifying_face	progress_identifying_face
progress_loading	progress_loading
progress_streaming	progress_streaming
prompt_align_face_accessibility	prompt_align_face_accessibility
prompt_align_face_accessibility_desktop	prompt_align_face_accessibility_desktop
prompt_connecting	prompt_connecting
prompt_genuine_presence_align_face	prompt_genuine_presence_align_face
prompt_kiosk_align_face	prompt_kiosk_align_face
prompt_kiosk_keep_still	prompt_kiosk_keep_still
prompt_liveness_align_face	prompt_liveness_align_face
prompt_liveness_no_target	prompt_liveness_no_target
prompt_liveness_scan_completed	prompt_liveness_scan_completed
prompt_loading	prompt_loading
prompt_rotate_portrait	prompt_rotate_portrait
prompt_rotate_portrait_short	prompt_rotate_portrait_short
prompt_scanning	prompt_scanning
prompt_too_close	prompt_too_close
prompt_too_far	prompt_too_far
prompt_too_high	prompt_too_high
prompt_too_left	prompt_too_left
prompt_too_low	prompt_too_low
prompt_too_right	prompt_too_right
prompt_increase_screen_brightness	removed
prompt_poor_lighting_conditions	removed
sdk_unsupported	removed
user_cancelled	user_cancelled

Upgrading from v3.5.x to v3.6.*

Color Options

To ensure the Web SDK is WCAG 2.1 AA compliant out of the box, we have changed the default colors (see CHANGELOG.md for list).

If you wish to still use the previous colors, you can implement the same as below. Please note, that these colours aren't WCAG 2.1 AA compliant.

<iproov-me 
token="YOUR_TOKEN" 
not_ready_tint_color="#f5a623" 
ready_tint_color="#01bf46" 
gpa_not_ready_overlay_stroke_color="#f5a623" 
gpa_ready_overlay_stroke_color="#01bf46">
</iproov-me>

Upgrading from v3.4.0 to v3.5.x

Event notice:

We now exit the SDK with the integration_unloaded error message if it is unloaded from the DOM before the user has completed. This will mean that the SDK will emit an error event this feedback code if the user doesn't start a transaction and the component is unloaded, or if your own integration unloads the web component before the user completes due to implementing your own timeout logic.

Deprecation:

If you are customising colors, please rename footer_text_color to prompt_text_color.

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

We have changed the order that events fire:

• If enable_camera_selector is set, 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.)

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