-
Notifications
You must be signed in to change notification settings - Fork 9
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.
In order for Native Bridge to function correctly with version 6.0.0, iOS version 13.0.0 and Android version 11.0.0 are required for proper SDK operability.
With version 6.0.0, we're now allowing the Failed event to provide back up to 3 failure reasons. This means a total overhaul of how we provide feedback codes and plaintext descriptions of events to the user to accomodate this new change.
In prior SDK versions, a failed event looked like the following:
{
heading: Failed,
passed: false,
feedback: "failure_multiple_faces",
reason: "Ensure only one person is visible",
type: undefined,
}Whereas in the new SDK version, it will look like the following instead
{
heading: Failed,
passed: false,
reasons: [
{ localized_description: "Make sure your whole face is visible and remove any accessories that might cover your face", feedback_code: "failure_obscured_face" },
{ localized_description: "Make sure your eyes are open", feedback_code: "failure_eyes_closed" },
{ localized_description: "Move to a different location with a neutral background", feedback_code: "failure_background_issue" },
],
type: undefined,
frame: {},
}This change to the Failure event structure will also carry over to all other events: events that contain just a reason will now return a list of reasons with only a single attribute localized_description, other events such as Error will contain a reasons attribute with a single reason consisting of both localized_description and feedback_code. All non-Failed events will still only contain a single reason - if any at all - only the Failed event can return more than a single reason.
In addition to the Failed event being able to display multiple feedback codes at the same time, the feedback codes the event can return have also changed significantly. Below is the full list of changes to the language files:
- Added:
failure_background_issue - Added:
failure_eyewear - Added:
failure_face_not_found - Added:
failure_frames_blurry - Added:
failure_lighting_issues - Added:
failure_rejected - Added:
failure_system_error - Added:
failure_timeout - Added:
failure_user_not_found - Added:
failure_device_issue - Added:
failure_motion_issue - Added:
failure_device_restart - Added:
failure_processing_fault - Added:
prompt_genuine_presence_too_bright - Added:
prompt_genuine_presence_too_dark - Added:
error_do_not_rotate - Added:
error_do_not_rotate_message
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.
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.
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.
- New failure code:
failure_multiple_faces - Changed:
user_cancelledtocanceled_user - Changed:
client_errortoerror_client - Changed:
failure_user_timeouttoerror_user_timeout. See explanation - Removed:
failure_not_supported, please use current keyerror_not_supported. See explanation
The following failure reasons are now treated as errors:
- failure code
user_timeoutnow corresponds toerror_user_timeout - failure code
not_supportednow corresponds toerror_not_supported
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
}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.
Occasional single frame flickers on devices that can support high FPS mode
See the full list of known issues here.
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.
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.
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
| 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 |
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_faceeyes_closedface_too_farface_too_closesunglassesobscured_face
ambiguous_outcome has been replaced with unknown which translates to Try Again.
| 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 |
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>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.
We have changed the order that events fire:
- If
enable_camera_selectoris set, themultiple_camerasevent now runs beforereadyand 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_deniedfeedback code and language string, along witherror_device_motion_denied_messagelanguage string.
There have been some changes to how we message errors, and we have added some new language strings:
-
Language strings for the
readyslot and event:-
iproov_ready_titleto allow internationalisation of "Ready to iProov" on the ready callback -
iproov_ready_buttonto 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.jsonfor the new strings: - When the SDK runs any of the following callbacks:
error,cancelled,interrupted,permission_denied,no_cameraorunsupported:- The language string mapping to the
feedbackevent property is now displayed as the heading. - A new language string has been added for each
feedbackcode, suffixed with_message. - Example:
error_no_camerais the heading term, defaulting to "We couldn't find a camera connected to your device" - Example:
error_no_camera_messageis the text term displayed beneath the heading, defaulting to "A camera must be available to use iProov"
- The language string mapping to the
-
Error messaging and language - We have increased the level of detail, see
- If your integration specifies language strings but doesn't implement the new
_messagesuffix, 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.
We don't require any integration changes between these versions.
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_timeouttofailure_user_timeoutin the failed event
- The
iProovSupportchecker:- In 3.1.0, we ship a separate entrypoint which contains
iProovSupportonly. 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.IProovSupportfor the time being.
- In 3.1.0, we ship a separate entrypoint which contains
-
assets_url:- If you have specified an assets_url, you will need to remove the
/assetssuffix from the URL, i.e.:https://mycdnproxy.com/assetsbecomeshttps://mycdnproxy.com - In production we recommend you to self-host assets.
- If you have specified an assets_url, you will need to remove the
-
streamingandstreamedevents:- Our
streamedevent now reflects our documentation. If you were previously relying on this to do something in your app's UI, simply change it tostreaming. The payload remains identical.
- Our
- 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.
- Some strings have been renamed, redundant ones have been removed and others added. Review your language strings and compare to
- 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.
- iOS 14.3 now supports Webview based apps that implement
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.
- Rename the
"aborted"slot and event handlers to"cancelled". - Optionally implement a slot and event handler for
"interrupted".
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
If you haven't already, ensure that you have migrated from the legacy Native Bridge implementation described in the v2.0 -> v2.1 section.
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.
To upgrade to the new Native Bridge functionality:
- Upgrade to
@iproov/web@^2.1. - Remove the
prefer_appsetting. - If in use, rename
prefer_app_optionstonative_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:
- Set the
legacy_native_bridgeoption totrue.
- 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
unsupportedevent 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.)
- If using the standalone support checker, it must be instantiated with the
legacyNativeBridgeoption:new IProovSupport(logger, { legacyNativeBridge: true });
- The
loggeroption can benullto fall back toconsole. 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.