diff --git a/.gitignore b/.gitignore index 9f11b75..ddd0123 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,4 @@ .idea/ +node_modules +.env +**/vendor/prod/ diff --git a/CHANGELOG.md b/CHANGELOG.md index 24abae2..e39898c 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -5,6 +5,20 @@ 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). +## 1.1.2021 3.1.2 + +## Fixed + +- The console object is no longer overridden. Sorry about that. +- Documentation updates and inaccuracies: + - Various iProovSupport documentation relating to payloads and availability on th.e global object + - Documentation relating to the payload of the progress event has been corrected. +- iProovSupport can now be loaded standalone without a bundler; regeneratorRuntime is now defined. +- Language strings can now be customised on slotted elements. Previously this didn't work. +- Fixed double checking for videoInput. Just once is enough. +- iProovSupport prompting in Chrome prompts instantly, previously it delayed. +- Fixed SDK crashing if passing a token not associated with a `user_id`. Unlikely, but displays a clean error instead. + ## 24.12.2020 3.1.1 ## Fixed diff --git a/README.md b/README.md index 04cf67c..54a79c8 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# iProov Biometrics Web SDK v3.1.1 +# iProov Biometrics Web SDK v3.1.2 ## 📖 Table of contents @@ -23,20 +23,7 @@ The iProov Biometrics Web SDK is the client for web browser based authentication You will need to generate a token from your back-end to use with the iProov Biometrics Web SDK. You can use the [REST API](https://eu.rp.secure.iproov.me/docs.html) to make the relevant calls and return the token to your front-end. See the [backend section](#backend) for more details. -## 📖 Contents - -This repository contains a demo showing an example of a backend and frontend integration. In these examples, the token is generated and validated using AJAX (in the register/login demo) and form submission (for the integration examples) by passing the following data to the backend: - -- **user_id** - the email address provided by the user -- **action** - the specific endpoint to call: - - _token_ - generate a unique 64 character token for the client - - _validate_ - check the validity of the result provided by the client - -## âŦ† Upgrading from earlier versions - -Please note that there is new name for the NPM package and URL for the script tag. If you are upgrading from v1 or v2-beta, please ensure that you update your integration to use the new name or URL as described in the [installation](#-installation) section below. - -A few of the options have changed from earlier versions so be sure to check the current supported [list of options](#-options) when upgrading. +Check out our [example](./demo), which can be spun up with a single command, which demonstrates an example backend/frontend integration. ## ✍ Registration @@ -44,17 +31,19 @@ You can obtain API credentials by registering on the [iProov Portal](https://por ## 📲 Installation +The npm package `@iproov/web` allows for integration of the iProov Biometrics Web SDK. It makes use of the [Web Components](https://www.webcomponents.org/introduction) APIs which are supported by most modern browsers and uses the [Polymer Project](https://www.polymer-project.org) to add support where they are not yet available. + ### Script Tag -The simplest and fastest method of integrating with the iProov Biometrics Web SDK is to reference it in a script tag using our [NPM package](https://www.npmjs.com/package/@iproov/web) hosted on a CDN such as [jsDelivr](https://www.jsdelivr.com/package/npm/@iproov/web) or [UNPKG](https://unpkg.com/browse/@iproov/web/). +For a fast proof of concept, the simplest way to integrate iProov Web to include with a script tag using our [NPM package](https://www.npmjs.com/package/@iproov/web) hosted on a CDN such as [jsDelivr](https://www.jsdelivr.com/package/npm/@iproov/web) or [UNPKG](https://unpkg.com/browse/@iproov/web/). -#### jsDelivr +**jsDelivr**: ```html ``` -#### UNPKG +**UNPKG**: ```html @@ -62,7 +51,7 @@ The simplest and fastest method of integrating with the iProov Biometrics Web SD ### NPM Package -The npm package `@iproov/web` allows for integration of the iProov Biometrics Web SDK. It makes use of the [Web Components](https://www.webcomponents.org/introduction) APIs which are supported by most modern browsers and uses the [Polymer Project](https://www.polymer-project.org) to add support where they are not yet available. +Installing locally with npm is recommended for production installations, and works best with a bundler like Webpack, Parcel or Rollup. #### Setup @@ -76,21 +65,26 @@ yarn add @iproov/web npm i @iproov/web --save ``` -After you have installed the `@iproov/web` package, you must then include the code into your project ideally at the root of your application: +After you have installed the `@iproov/web` package, you can require or import it into your codebase: ```javascript +// ESM or Module Bundler: +import "@iproov/web" + +// CJS style: require("@iproov/web") ``` -It's as simple as that to include the iProov Biometrics Web SDK. You now need to inject the web component by one of the [integration methods](#frontend) shown below. +It's as simple as that to include the iProov Biometrics Web SDK with your project. +Now you can inject the web component where you need it using one of the [integration methods](#frontend) shown below. ## 🚀 Get started ### Backend -To make use of this SDK you will require integration with the back-end iProov service. To access credentials and an integration guide, please visit [portal.iproov.com](https://portal.iproov.com). +To make use of this SDK you will require integration with the iProov backend service. You can obtain platform credentials and read our integration guide on [portal.iproov.com](https://portal.iproov.com). -When starting an iProov transaction (or claim), you would first need to generate an [enrolment](https://secure.iproov.me/docs.html#operation/userEnrolServerToken) or [verification](https://secure.iproov.me/docs.html#operation/userVerifyServerToken) token, which can be done as part of the page load or with AJAX. You would then need to pass the token to your frontend to initialise the iProov Biometrics Web SDK. +When starting an iProov transaction (or claim), you first need to generate an [enrolment](https://secure.iproov.me/docs.html#operation/userEnrolServerToken) or [verification](https://secure.iproov.me/docs.html#operation/userVerifyServerToken) token, which can be passed on page load or fetched with AJAX, then used to initialise the iProov Biometrics Web SDK on the frontend. After receiving the result from the SDK, you must then confirm its authenticity by validating the [enrolment](https://secure.iproov.me/docs.html#operation/userEnrolValidate) or [verification](https://secure.iproov.me/docs.html#operation/userVerifyValidate) token _before_ escalating the user's privileges. This must be done from your backend and is typically invoked with a redirect, form submission or AJAX call triggered by the `passed` [event](#-events). @@ -99,14 +93,14 @@ After receiving the result from the SDK, you must then confirm its authenticity ### Frontend -Once an iProov token has been generated by your backend, you should pass it as an attribute to the custom element using one of the integration methods described below. After a successful iProov, the result must be validated by the backend before granting the user any privileges. +Once an iProov token has been generated by your backend, you should pass it as an attribute to the `` element using one of the integration methods described below. After a successful iProov, the result must be validated by the backend before granting the user any privileges. #### HTML The simplest way to pass the token to iProov is to include it as an attribute to the `` HTML tag as shown here: ```html - + ``` #### JavaScript @@ -153,19 +147,17 @@ You can change the backend server you are attempting to iProov against by passin #### Assets URL -External fonts will be loaded from our CDN at cdn.iproov.app. Versions prior to 3.0 also loaded workers and WASM files from this host. From 3.0, this has been simplified. - -From 3.0, all constituent workers and WASM files are bundled together as part of our main file. The remaining resources are non-volatile such as fonts and UI files, which are better off loaded in parallel. - -These external files loaded from our CDN at cdn.iproov.app. In scenarios with custom firewalls or reverse proxy configurations, this option is available to customise and set config accordingly. +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: ```html ``` +> ℹī¸ [Full wiki page on assets_url and hosting assets](https://github.com/iProov/web/wiki/Serving-Assets-And-CORS) + #### Logo -You can use a custom logo by simply passing a relative link or absolute path to your logo. Ideally, the logo would be in an SVG format for scaling but you can use any web safe image format. If you don't pass a logo, the iProov logo will be shown by default. If you do not want a logo to show pass the `logo` attribute as `null`. +You can use a custom logo by simply passing a relative link, absolute path or data URI to your logo. We recommend providing a logo in SVG format, but any web format is supported. If you don't pass a logo, the iProov logo will be shown by default. If you do not want a logo to show pass the `logo` attribute as `null`. ```html @@ -175,7 +167,7 @@ You can use a custom logo by simply passing a relative link or absolute path to Specify a custom title to be shown. Defaults to show an iProov-generated message. Set to empty string "" to 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). -> ⚠ī¸ iProov-generated messages are passed through our translators. Passing a custom title will prevent this and you will need to provide the translated version. +> ⚠ī¸ iProov-generated messages are passed through our translators. If you pass a custom title, you must provide the translated version. ```html @@ -245,7 +237,9 @@ By setting `show_countdown` to `true`, a countdown will be shown to the user bef #### Enable Camera Selector -By setting `enable_camera_selector` to `true`, the `camera_selector` slot and `multiple_cameras` event will be exposed. See [Camera Selector](#-slots) slot for customisation options. This feature is only available on desktop devices (laptops, PCs etc). +Support multiple camera selection on desktop devices by setting `enable_camera_selector` to `true`. + +When enabled, the `camera_selector` slot and `multiple_cameras` event will be exposed. See [Camera Selector](#-slots) slot for customisation options. This feature is only available on desktop devices (laptops, PCs etc). ```html @@ -260,27 +254,26 @@ Warnings and errors will always be emitted to the console. ``` -This setting has no effect on the support checker if it is deployed standalone. +This setting has no effect on any `iProovSupport` instance that's been initialised separately to the main component. The checker itself accepts a logger argument which could be `console`, or any common logging library which you are free to configure to your own requirements. #### Kiosk Mode -Note this setting enables a feature which is in alpha and still under active development. - -For deploying iProov on tablets or fixed hardware such as laptops and desktop devices. Enables snap to face and increases matchable range. - -Set to true to enable; omit the setting to keep disabled. - -A known issue is that kiosk mode currently has display issues in portrait mode, this will be resolved in a later release. +When deploying iProov on physically secured hardware such as laptops and desktop devices, you can enable the kiosk mode UI. ```html ``` +> ℹī¸ Kiosk mode will only activate on tablets and desktops. It is automatically disabled on mobile devices. + ## đŸ“Ĩ Slots -Slots allow the HTML content shown before and after the iProov fullscreen experience to be customised and styled for a more seamless visual integration. The following examples show different ways to include some of the most commonly used slots. +Customise the markup, styling and automatically inherit your app's styles by [using slots](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots). +You can customise the preparation and result stages of iProov to seamlessly integrate it into your application. + +The following examples show different ways to customise some commonly used slots. ### HTML @@ -301,22 +294,27 @@ The simplest way to add a slot is to include it within the `` HTML ta #### JavaScript -You can also build up the slots with JavaScript before injecting the Web Component: +You can also build up the slots with the `