diff --git a/CHANGELOG.md b/CHANGELOG.md index 6782980..0c59c38 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,7 +5,40 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## 23.05.2023 4.2.1 +## 27.09.2023 5.0.0 + +## Added + +- **User Feedback Codes**: New User Feedback codes for Liveness Assurance, see upgrade guide for details. +- **UI** + - **LA Background Cropping** LA with the clear or blur filter has a new cropping animation applied, in order to provide a more pleasing UX. Note the size/extent of this effect varies based on the claim. + - **GPA animation** New get ready and progress animation for GPA. + - **Alternate Camera Button** Now customizable. See readme for details. +- **Imagery Quality** In LA, higher quality imagery can be collected and returned via the validate frame. This feature can be toggled on - please reach out to Customer Success to enable this. + +## Fixed + +- **UI** + - **Full screen failure** Layout issue when full screen fails has been fixed. + - **Viewport resize** Video display issue when viewport is resized has been fixed. + - **Liveness animation** Liveness Assurance complete animation on iOS/iPadOS has been fixed to align with other platforms. +- **Imagery** + - **Imagery on rotation** Fix frames overlaying each other when device is rotated while scanning. +- **Error** + - **Error code** Error codes are now correctly reported to the backend. + +## Changed + +- **Motion permission on GPA** Motion will be required on GPA. +- **Feedback codes** `user_timeout` and `not_supported` are now reported as errors (they were reported as failures before). +- **Security** The security of the SDK has been enhanced. +- **US Spelling** Changed API to U.S. English spelling of "Canceled". + +## Removed + +- **Iframe Bridge**: iOS/iPadOS 14 and lower are no longer supported within iframe integrations. The minimum supported version is now iOS 15.1. As a consequence Iframe Bridge has been removed from the SDK. + +## 22.05.2023 4.2.1 ## Fixed diff --git a/LICENSE.md b/LICENSE.md index 930df9a..3082262 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -105,17 +105,29 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI Icons made by [Roundicons](https://www.flaticon.com/authors/roundicons) from [Flaticon](https://www.flaticon.com) -# lottie-web +# InversifyJS The MIT License (MIT) -Copyright (c) 2015 Bodymovin +Copyright (c) 2015-2017 Remo H. Jansen -Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: -The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. # scream @@ -337,6 +349,8 @@ the conditions stated in this License. 10. The MIT License +# Tween.js + Copyright (c) 2010-2012 Tween.js authors. Easing equations Copyright (c) 2001 Robert Penner http://robertpenner.com/easing/ @@ -359,30 +373,6 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. -# three - -The MIT License - -Copyright © 2010-2021 three.js authors - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. - # ua-parser-js MIT License diff --git a/README.md b/README.md index f36a80f..80968dc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ ![iProov: Biometric Face Verification for Remote Identity Assurance](https://github.com/iProov/web/raw/master/images/banner.png) -# iProov Biometrics Web SDK v4.2.1 +# iProov Biometrics Web SDK v5.0.0 ## 📖 Table of contents @@ -16,9 +16,9 @@ - [Browser support](#-browser-support) - [WebViews](#-webviews) - [Native bridge](#-native-bridge) -- [Iframe Bridge](#-iframe-integrations) - - [Mobile Safari](#iframe-bridge-for-mobile-safari) +- [Iframe Integrations](#-iframe-integrations) - [Accessibility](#-accessibility) +- [Image Quality Enhancement](#-image-quality-enhancement) - [Help & support](#-help--support) ## 🤳 Introduction @@ -46,7 +46,7 @@ The NPM package [@iproov/web-sdk](https://www.npmjs.com/package/@iproov/web-sdk) Using the `@iproov/web-sdk` package is the recommended way of using the iProov Web SDK in production, and works best with a bundler like Webpack, Parcel or Rollup. The iProov Web SDK is held in a private NPM registry, to gain access, please contact [support@iproov.com](mailto:support@iproov.com) sharing your NPM username and you will be given instructions on usage. -> ⚠️When you have been granted access, to use the `@iproov/web-sdk` via your CLI, you will need to authenticate with [NPM Login](https://docs.npmjs.com/cli/v9/commands/npm-login) or [YARN login](https://classic.yarnpkg.com/lang/en/docs/cli/login/). +> ⚠️ When you have been granted access, to use the `@iproov/web-sdk` via your CLI, you will need to authenticate with [NPM Login](https://docs.npmjs.com/cli/v9/commands/npm-login) or [YARN login](https://classic.yarnpkg.com/lang/en/docs/cli/login/). #### Setup @@ -148,7 +148,7 @@ Setting this option lower than the defaults may increase error rates, so please #### Base URL -You can change the backend server you are attempting to iProov against by passing the `base_url` property. This needs to point to the same platform used for generating tokens (defaults to the EU platform if not defined). Reverse proxies are supported and a custom path to the WebSocket endpoint can be used, for example: `https://custom.domain.com/custom-path/socket.io/v2/` +You can change the backend server you are attempting to iProov against by passing the `base_url` property. This needs to point to the same platform used for generating tokens (defaults to the EU platform if not defined). Reverse proxies are supported and a custom path to the WebSocket endpoint can be used, for example: `https://custom.domain.com/custom-path/ws/v2/` ```html @@ -156,7 +156,7 @@ You can change the backend server you are attempting to iProov against by passin #### Assets URL -Dependencies such as fonts and web workers are loaded from our CDN at cdn.iproov.app. We recommend in production that you self-host these, and set the assets_url to reflect this: +Critical dependencies are loaded from our CDN at cdn.iproov.app. We recommend in production that you self-host these, and set the assets_url to reflect this: ```html @@ -174,7 +174,7 @@ You can use a custom logo by simply passing a relative link, absolute path or da #### Close Button -You can set a custom close button by setting a valid URI as below: +You can use a custom button image by simply passing a relative link, an absolute path or a data URI to your image. We recommend providing an image in SVG format, but any web format is supported. If you don't pass an image, the default close button image will be shown. ```html +``` + + #### Custom Title Specify a custom title to be shown. Defaults to empty string "" - hide the message entirely. You can also pass in `%@` characters which will be mapped in this order to `type` (Enrol or Verify), `user_name` (the user_name you passed when generating the token), `sp_name` (the service provider you used to generate the token). @@ -224,9 +236,9 @@ You can customize the look and feel of the main layout by changing the following Color option changes introduced in [v4.0.0](https://github.com/iProov/web/releases/tag/v4.0.0): | Color Option | Description | -| ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| ---------------------------------------- |------------------------------------------------------------------------------------------------------------------------------------------------------| | **title_text_color** | Adjusts the color of the text that can be added above the oval (by default there is no text here - see the custom_title option for more information) | -| **surround_color** | Adjusts the color of the surroundings to the centre oval. | +| **surround_color** | Adjusts the color of the surroundings to the centre oval. It also affects the color of the mask in Liveness with `clear` or `blur` filter. | | **prompt_text_color** | Adjusts the color of the text visible in the centre prompt of the screen | | **prompt_background_color** | Adjusts the color of the background visible in the centre prompt of the screen | | **header_background_color** | Adjusts the color of the background visible in the top bar of the application (transparent by default) | @@ -249,12 +261,15 @@ Control screen reader priority of messages being read out. By default, this is s This setting controls the filter for camera preview. Can be `classic`, `shaded` (additional detail, the default), `vibrant` (full color). -For Liveness, two additional filters are provided: `clear` (no filter) and `blur` (starts blurred, this filter is removed when the claim progresses). +For Liveness Assurance, two additional filters are provided: `clear` (no filter) and `blur` (starts blurred, this filter is removed when the claim progresses). ```html ``` +For filters `clear` and `blur`, if the camera feed does not cover the full screen, an opaque "mask" with rounded corners will be applied around the camera preview. +The mask takes the color except transparency (it will always be opaque) from `surround_color` (see above). + #### Floating Prompt Rounded Corners The floating prompt has an option to control rounded corners. Rounded corners are enabled by default (set to `true`); to disable rounded corners set `prompt_rounded_corners` to `false`. @@ -279,8 +294,8 @@ When `allow_landscape` is set to `true`, handheld devices will be able to start Here is the behavior: -- For GPA and Liveness, landscape orientation is blocked in most handheld devices. -- For Liveness, no handheld device will be able to start in landscape mode, regardless of this setting. +- For GPA and Liveness Assurance, landscape orientation is blocked in most handheld devices. +- For Liveness Assurance, no handheld device will be able to start in landscape mode, regardless of this setting. - This blocking behavior is not enforced on Android tablets due to the varying position of their camera. - When in landscape mode in an affected UX, the iProov component will display the `rotate_portrait` slot. - Desktop devices are unaffected by `allow_landscape`. @@ -293,6 +308,8 @@ See [slots](#-slots) for details on how to override the `rotate_portrait` slot. #### Show Countdown +This option only works with kiosk mode. + By setting `show_countdown` to `true`, a countdown will be shown to the user before scanning actually starts. If this is set to `false`, when the users face becomes properly aligned the scanner will start in 2 seconds as long as the users face is still properly aligned. By default, `show_countdown` is `false`. The example below shows how to enable the countdown. ```html @@ -431,27 +448,28 @@ To integrate with our localization feature, use special class names in your slot The following is the complete list of slots can be used with the `` web component and have associated [events](#-events): | Slot | Description | -| ------------------------ |------------------------------------------------------------------------------------------------------------| -| **button** | Element that a user taps or clicks on to launch into fullscreen and start iProov | -| **camera_selector** \* | Label and dropdown populated with available cameras, if multiple cameras are detected. | -| **cancelled** | State displayed to the user when they exit fullscreen before iProoving | +| ------------------------ | ---------------------------------------------------------------------------------------------------------- | +| **button** \* | Element that a user taps or clicks on to launch into fullscreen and start iProov | +| **camera_selector** \*\* | Label and dropdown populated with available cameras, if multiple cameras are detected. | +| **canceled** | State displayed to the user when they exit fullscreen before iProoving | | **error** | State displayed to the user in the event of an error | | **failed** | State displayed to the user when the user failed iProov | -| **grant_button** | Element that user taps or clicks to grant camera permission | +| **grant_button** \* | Element that user taps or clicks to grant camera permission | | **grant_permission** | State displayed to the user when camera or motion permission is unknown and not blocked | -| **iframe_bridge_title** | State displayed to the user if [iframe bridge](#-iframe-integrations) is enabled | -| **iframe_bridge_button** | Element that user taps or clicks to open a new window if [iframe bridge](#-iframe-integrations) is enabled | | **no_camera** | State displayed to the user when there is no camera | | **passed** | State displayed to the user when the user passed iProov | | **permission_denied** | State displayed to the user when camera permission has been blocked | | **progress** | State displayed to the user when streaming has completed and iProov is processing the result | | **ready** | State displayed to the user when the component is ready to start the main iProov user journey | -| **rotate_portrait** \*\* | State displayed to the user when a handheld device is not in portrait orientation | +| **rotate_portrait** \*\*\* | State displayed to the user when a handheld device is not in portrait orientation | | **unsupported** | State displayed to the user when their browser is not supported | -> \* Visible and managed when [camera selection](#enable-camera-selector) is enabled. A select menu with the class `iproov-camera-selector` must be present within your slots markup. An error will be thrown if this cannot be found. +> \* Interactive elements such as buttons that start full screen and cameras require a user gesture enforced by the browser. Using JavaScript to apply clicks is not recommended within your user journey and may cause unexpected errors or performance degradation. +> See our [User Gestures Wiki](https://github.com/iProov/web/wiki/User-Gestures) for more details. -> \*\* See [allow landscape](#allow-landscape) option which controls the behaviour of the `rotate_portrait` slot and details on how to override. +> \*\* Visible and managed when [camera selection](#enable-camera-selector) is enabled. A select menu with the class `iproov-camera-selector` must be present within your slots markup. An error will be thrown if this cannot be found. + +> \*\*\* See [allow landscape](#allow-landscape) option which controls the behaviour of the `rotate_portrait` slot and details on how to override. ## 📆 Events @@ -470,23 +488,23 @@ Every event has a [detail](https://developer.mozilla.org/en-US/docs/Web/API/Cust The available events are detailed below with any extra properties that are supplied: -| Event | Extra Properties | Description | -| ----------------------- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| **cancelled** | _feedback, reason_ | User has cancelled iProov by exiting fullscreen | -| **connecting** | None | The SDK is connecting to the server. You should provide an indeterminate progress indicator to let the user know that the connection is taking place. | -| **connected** | None | The SDK has connected. You should hide any progress indication at this point. | -| **error** | _feedback, reason_ | iProov encountered an error while processing the authentication | -| **failed** | _type, passed, feedback, reason_ | Authentication was unsuccessful, the user needs to try again | -| **multiple_cameras** \* | _devices, device\_selector, slot, label_ | If `enable_camera_selector` is `true` returns an array of devices if more than 1 video device is detected | -| **passed** | _type, feedback, reason, passed_ | Authentication was successful, the result can now be validated | -| **permission** | _reason_ | Camera permission is unknown & not blocked, show permission | -| **permission_denied** | _feedback, reason_ | User has blocked access to the camera | -| **progress** | _progress, message_ | iProov has published a progress update for the authentication | -| **ready** | None | iProov has initialized successfully and has camera permission | -| **started** | None | User has started iProov by launching into fullscreen | -| **streaming** | None | User has started streaming. The client remains in fullscreen. | -| **streamed** | None | User has finished streaming and the client has exited fullscreen _(Not guaranteed to fire every time due to a possible fast failure or any errors that can occur and should be handled within your event handlers accordingly)_ | -| **unsupported** | _feedback, reason_ | Browser does not support using iProov | +| Event | Extra Properties | Description | +| ----------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| **canceled** | _feedback, reason_ | User has canceled iProov by exiting fullscreen | +| **connecting** | None | The SDK is connecting to the server. You should provide an indeterminate progress indicator to let the user know that the connection is taking place. | +| **connected** | None | The SDK has connected. You should hide any progress indication at this point. | +| **error** | _feedback, reason_ | iProov encountered an error while processing the authentication | +| **failed** | _type, passed, feedback, reason_ | Authentication was unsuccessful, the user needs to try again | +| **multiple_cameras** \* | _devices, device_selector, slot, label_ | If `enable_camera_selector` is `true` returns an array of devices if more than 1 video device is detected | +| **passed** | _type, feedback, reason, passed_ | Authentication was successful, the result can now be validated | +| **permission** | _reason_ | Camera permission is unknown & not blocked, show permission | +| **permission_denied** | _feedback, reason_ | User has blocked access to the camera | +| **progress** | _progress, message_ | iProov has published a progress update for the authentication | +| **ready** | None | iProov has initialized successfully and has camera permission | +| **started** | None | User has started iProov by launching into fullscreen | +| **streaming** | None | User has started streaming. The client remains in fullscreen. | +| **streamed** | None | User has finished streaming and the client has exited fullscreen _(Not guaranteed to fire every time due to a possible fast failure or any errors that can occur and should be handled within your event handlers accordingly)_ | +| **unsupported** | _feedback, reason_ | Browser does not support using iProov | > \* See [Multiple Camera Example](https://github.com/iProov/web/wiki/Camera-Selection-Example) for an example demonstrating how a camera selection feature could be implemented. @@ -500,21 +518,21 @@ Properties of the event's **detail** payload: | **frame** (†) (\*) | _passed, failed_ | An `ImageData` from the scanning process | | **progress** | _progress_ | A percentage (between 0 and 100) representing the progress | | **message** | _progress_ | A user-friendly description of the current progress stage | -| **feedback** | _cancelled, failed, error, unsupported_ | A fixed feedback code for making logical decisions | -| **reason** | _cancelled, failed, error, unsupported_ | An English description of the reason for the event | +| **feedback** | _canceled, failed, error, unsupported_ | A fixed feedback code for making logical decisions | +| **reason** | _canceled, failed, error, unsupported_ | An English description of the reason for the event | | **slot** | _multiple_cameras_ | The relevant slot for the event, for ease of use | | **devices** | _multiple_cameras_ | Array of suitable `InputDevice`s for imagery capture | | **device_selector** | _multiple_cameras_ | The multiple camera selection `