@iproov/web

iProov Biometrics Web SDK v3.4.0

📖 Table of contents

• Introduction
• Registration
• Installation
• Get started
• Options
• Slots
• Events
• Localization
• Browser support
• WebViews
• Native bridge
• Mobile Safari Iframe bridge
• Help & support

🤳 Introduction

The iProov Biometrics Web SDK is the client for web browser based authentication. It can be integrated in a number of ways to support your web journeys for onboarding and authentication. You can find out more about how to use iProov Web in your User Journeys and create API Keys on the iProov Portal.

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 to make the relevant calls and return the token to your front-end. See the backend section for more details.

Check out our example, which can be spun up with a single command, which demonstrates an example backend/frontend integration.

✍ Registration

You can obtain API credentials by registering on the iProov Portal.

📲 Installation

The npm package @iproov/web allows for integration of the iProov Biometrics Web SDK. It makes use of the Web Components APIs which are supported by most modern browsers and uses the Polymer Project to add support where they are not yet available.

Script Tag

For a fast proof of concept, the simplest way to integrate iProov Web to include with a script tag using our NPM package hosted on a CDN such as jsDelivr or UNPKG.

jsDelivr:

<script src="https://cdn.jsdelivr.net/npm/@iproov/web"></script>

UNPKG:

<script src="https://unpkg.com/@iproov/web"></script>

NPM Package

Installing locally with npm is recommended for production installations, and works best with a bundler like Webpack, Parcel or Rollup.

Setup

Install the package as a dependency. You can use Yarn or NPM to do this.

yarn add @iproov/web

npm i @iproov/web --save

After you have installed the @iproov/web package, you can require or import it into your codebase:

// 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 with your project. Now you can inject the web component where you need it using one of the integration methods shown below.

🚀 Get started

Backend

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.

When starting an iProov transaction (or claim), you first need to generate an enrolment or verification 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 or verification 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.

⚠️ The REST API should always be called from your backend so as to never expose your secret to your client application. Always call the validate API from your backend after receiving a result; never trust the result provided by the web client.

Frontend

Once an iProov token has been generated by your backend, you should pass it as an attribute to the <iproov-me> 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 <iproov-me> HTML tag as shown here:

<iproov-me token="***YOUR_TOKEN_HERE***" base_url="***IPROOV_PLATFORM_URL_HERE***"></iproov-me>

JavaScript

The <iproov-me> element can also be injected into the page with the token:

window.addEventListener("WebComponentsReady", function (event) {
  const iProovMe = document.createElement("iproov-me")
  iProovMe.setAttribute("token", "***YOUR_TOKEN_HERE***")
  document.getElementById("your-container-id").appendChild(iProovMe)
})

jQuery

The HTML can also be injected directly onto the page as in this jQuery example:

window.addEventListener("WebComponentsReady", function (event) {
  $("#your-container-id").append($('<iproov-me token="***YOUR_TOKEN_HERE***"></iproov-me>'))
})

There are also the following framework specific example integrations available on the wiki:

• Angular v10
• React v16
• Vue v2

ℹ️ JavaScript methods are run after the WebComponentsReady event to ensure that the SDK is ready to be injected.

⚙ Options

The behaviour of the iProov Biometrics Web SDK can be altered by setting the following options as attributes of the <iproov-me> tag in the same way as the token.

Network Timeout

Time in seconds for the backend to ack a message we send. In the event of the timeout being exceeded, the error event will fire with the feedback code error_network.

The default value is 10 seconds. To set the timeout to 15 seconds you would pass the following option:

<iproov-me token="***YOUR_TOKEN_HERE***" network_timeout="15"></iproov-me>

Setting this option lower than the defaults may increase error rates, so please be mindful when changing this.

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/

<iproov-me token="***YOUR_TOKEN_HERE***" base_url="https://eu.rp.secure.iproov.me"></iproov-me>

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:

<iproov-me token="***YOUR_TOKEN_HERE***" assets_url="https://cdn.iproov.app/assets"></iproov-me>

ℹ️ Full wiki page on assets_url and hosting assets

Logo

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.

<iproov-me token="***YOUR_TOKEN_HERE***" logo="https://www.iproov.com/images/iproov_logo.svg"></iproov-me>

Close Button

You can set a custom close button by setting a valid URI as below:

<iproov-me
  token="***YOUR_TOKEN_HERE***"
  close_button="https://www.materialui.co/materialIcons/navigation/close_black_72x72.png"
></iproov-me>

SVG is recommended.

Custom Title

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. If you pass a custom title, you must provide the translated version.

<!-- Set the title to a plain string -->
<iproov-me token="***YOUR_TOKEN_HERE***" custom_title="iProov Ltd" />

<!-- Hide the title, empty string, "null" or "false" can be used. Must be a string! -->
<iproov-me token="***YOUR_TOKEN_HERE***" custom_title="" />

<!-- Build dynamic string with type, user_name and sp_name-->
<!-- i.e. Below would generate "Enrol AS [e-mail] TO iProov" -->
<iproov-me token="***YOUR_TOKEN_HERE***" custom_title="%@ AS %@ TO %@" />

Colours

You can customise the look and feel of the main layout by changing the following options. You can pass a literal value red, RGB rgb(230, 245, 66) or a hex value #e6f542.

{
  header_background_color: "rgba(0, 0, 0, .68)", // Header area - usually grey, encloses title and close button
  header_text_color: "#fff", // Header text
  footer_background_color: "rgba(0, 0, 0, .68)", // Footer area
  footer_text_color: "#fff", // Footer text
  progress_bar_color: "#000", // GPA progress bar. Positioned above the footer and behind the text.
  loading_tint_color: "#5c5c5c", // The app is connecting to the server or no face found. Default: grey.
  not_ready_tint_color: "#f5a623", // Cannot start iProoving until the user takes action (e.g. move closer, etc). Default: orange.
  ready_tint_color: "#01bf46", // Ready to start iProoving. Default: green.
  oval_scanning_color: "#fff", // The colour of the oval while scanning in GPA.
  liveness_tint_color: "#1756e5", // Liveness tint colour. Default: blue.
  liveness_scanning_tint_color: "#5c5c5c", // Liveness is scanning. Default: lightGrey.
}

The example below changes the default grey no face to #4293f5 (blue), giving feedback like "Move Closer" to red rgb(245, 66, 66) and starting to purple.

<iproov-me
  token="***YOUR_TOKEN_HERE***"
  loading_tint_color="#4293f5"
  not_ready_tint_color="rgb(245, 66, 66)"
  ready_tint_color="purple"
></iproov-me>

CSP Nonce

Set the csp_nonce option to a random string to avoid requiring unsafe-inline in your style-src CSP.

Note that inline CSS is needed to provide critical styles for <iproov-me> for immediate user interaction.

<iproov-me token="***YOUR_TOKEN_HERE***" csp_nonce="P5wB82PFZt"></iproov-me>

Allow Landscape

When allow_landscape is set to true, handheld devices will be able to start in landscape orientation.

Here is the behaviour:

• 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.
• This blocking behaviour is not enforced 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.

See slots for details on how to override the rotate_portrait slot.

<iproov-me token="***YOUR_TOKEN_HERE***" allow_landscape="true"></iproov-me>

Show Countdown

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.

<iproov-me token="***YOUR_TOKEN_HERE***" show_countdown="true"></iproov-me>

Enable Camera Selector

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 slot for customisation options. This feature is only available on desktop devices (laptops, PCs etc).

<iproov-me token="***YOUR_TOKEN_HERE***" enable_camera_selector="true"></iproov-me>

Debug Logs

Logs at level info or lower are hidden, but can be exposed to the console by setting debug to true. Warnings and errors will always be emitted to the console.

<iproov-me token="***YOUR_TOKEN_HERE***" debug="true"></iproov-me>

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

When deploying iProov on physically secured hardware such as laptops and desktop devices, you can enable the kiosk mode UI.

<iproov-me token="***YOUR_TOKEN_HERE***" kiosk_mode="true"></iproov-me>

ℹ️ Kiosk mode will only activate on tablets and desktops. It is automatically disabled on mobile devices.

📥 Slots

Customise the markup, styling and automatically inherit your app's styles by using 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

The simplest way to add a slot is to include it within the <iproov-me> HTML tag as shown in the example below:

<iproov-me token="***YOUR_TOKEN_HERE***">
  <div slot="ready">
    <h1 class="iproov-lang-heading">Ready to iProov</h1>
  </div>
  <div slot="button">
    <button type="button">Scan Face</button>
  </div>
</iproov-me>

ℹ️ In order to style and manipulate your slots, you can add custom classes and IDs which can be accessed from your CSS and JavaScript.

JavaScript

You can also build up the slots with the <template> element and JavaScript before injecting the Web Component:

Template to be placed anywhere in your page:

<template id="iproov_template">
  <div slot="ready">
    <h1 class="iproov-lang-heading">Register your face</h1>
  </div>
  <div slot="button">
    <button>Start face scan...</button>
  </div>
</template>

JavaScript:

window.addEventListener("WebComponentsReady", function (event) {
  const iProovMe = document.createElement("iproov-me")
  iProovMe.setAttribute("token", "***YOUR_TOKEN_HERE***")
  const templateContent = document.querySelector("#iproov_template").content.cloneNode(true)
  iProovMe.append(templateContent)
  document.getElementById("your-container-id").appendChild(iProovMe)
})

With jQuery, the entire Web Component can be injected with slots using HTML syntax, for example:

window.addEventListener("WebComponentsReady", function (event) {
  const iProovMe = $('<iproov-me token="***YOUR_TOKEN_HERE***"></iproov-me>')

  iProovMe.append('<div slot="ready"><h1 class="iproov-lang-heading">Register your face</h1></div>')
  iProovMe.append('<button type="button" slot="button">Start face scan...</button>')

  $("#your-container-id").append(iProovMe)
})

To integrate with our localization feature, use special class names in your slotted content:

• Headings must use .iproov-lang-heading
• Supplementary terms (message, reason etc) must have .iproov-lang-term

Example: The below text will be swapped with the correctly localized strings when displayed:

<div slot="passed">
  <h3 class="iproov-lang-heading">Passed</h3>
  <div class="iproov-lang-term">You have iProoved successfully</div>
</div>

⚠️ When customising any the button and grant_button slots, the slot must contain a <button> element to ensure interactivity. These buttons may be disabled by the SDK on component load while we configure according to the passed in token.

The following is the complete list of slots can be used with the <iproov-me> web component and have associated 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
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_permission	State displayed to the user when camera permission is unknown and not blocked
interrupted	State displayed to the user when fullscreen quickly exits after launch, maybe due to software
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
unsupported	State displayed to the user when their browser is not supported

* Visible and managed when camera selection 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 option which controls the behaviour of the rotate_portrait slot and details on how to override.

📆 Events

There are a set of CustomEvents that can be used to integrate bespoke functionality. Events are bound directly to the <iproov-me> element after the WebComponentsReady event is called on the window.

Details

Every event has a detail property which contains data relating to that event. The token is present for every event:

{
  "token": "Your Generated Token"
}

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
interrupted	feedback, reason	Fast fullscreen exit possible due to software. Retry is possible.
multiple_cameras *	devices, device_selector, slot	If enable_camera_selector is true returns an array of devices if more than 1 video device is detected
passed	type, passed	Authentication was successful, the result can now be validated
permission	None	Camera permission is unknown & not blocked, show permission
permission_denied	None	User has blocked access to the camera
progress	progress, message	iProov has published a progress update for the authentication
ready	None	iProov has initialised 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 for an example demonstrating how a camera selection feature could be implemented.

Properties of the event's detail payload:

Property	Events	Description
token	All	The token associated with the authentication attempt
type (†)	passed, failed	The type of authentication (enrol, verify or id_match)
passed	passed, failed	Boolean value whether the result passed or failed
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, interrupted, failed, error, unsupported	A fixed feedback code for making logical decisions
reason	cancelled, interrupted, 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 InputDevices for imagery capture
device_selector	multiple_cameras	The multiple camera selection <select> element
is_native_bridge	All	Boolean value if event originates from the native bridge

• • The frame property is for UI/UX purposes only and is only available if enabled on your service provider and token configuration. Imagery upon which authentication may later rely must be obtained from the token validate endpoint by a secure server-to-server call. † - The type and frame properties are not available when running in Native Bridge mode.

In the case of the cancelled, interrupted, failed, error and unsupported events, the feedback code can be used for dealing with special cases, and the reason can be displayed to the user. The following are possible responses:

Feedback	Reason	Event
ambiguous_outcome	Sorry, ambiguous outcome	failed
client_api	There was an error calling the API	error
client_browser	The browser is not supported	unsupported
client_camera	There was an error getting video from the camera	error
client_config	There was an error with the client configuration	error
client_error	An unknown error occurred	error
client_stream	There was an error streaming the video	error
error_asset_fetch	Unable to fetch assets	error
error_camera_in_use	The camera is already in use and cannot be accessed	error
error_camera_not_supported	The camera resolution is too small	error
error_device_motion_unsupported	Your device does not seem to fully report device motion	error
error_expired_token	Token expired because it wasn't claimed in time	error
error_fullscreen_change	Exited fullscreen without completing iProov	cancelled, interrupted
error_invalid_token	The token is invalid	error
error_network	Network error	error
error_no_face_found	No face could be found	error
error_server	Server error	error
lighting_backlit	Strong light source detected behind you	failed
lighting_face_too_bright	Too much light detected on your face	failed
lighting_flash_reflection_too_low	Ambient light too strong or screen brightness too low	failed
lighting_too_dark	Your environment appears too dark	failed
motion_too_much_mouth_movement	Please do not talk while iProoving	failed
motion_too_much_movement	Please keep still	failed
network_problem	Sorry, network problem	error
sdk_unsupported	The SDK has passed end of life and is no longer supported	error
user_timeout	The user started the claim but did not stream in time	failed

Listeners

We recommend the integrator listens for at least the ready and unsupported events because one of them will always be called, so you can determine if iProov is supported or not:

document.querySelector("iproov-me").addEventListener("ready", function (event) {
  console.log("iProov is ready")
})
document.querySelector("iproov-me").addEventListener("unsupported", function (event) {
  console.warn("iProov is not supported: " + event.detail.reason)
})

Because all event details share the same structure, they can be handled by a single function if desired:

const iProovMe = document.querySelector("iproov-me")
iProovMe.addEventListener("ready", iProovEvent)
iProovMe.addEventListener("started", iProovEvent)
iProovMe.addEventListener("cancelled", iProovEvent)
iProovMe.addEventListener("interrupted", iProovEvent)
iProovMe.addEventListener("streaming", iProovEvent)
iProovMe.addEventListener("streamed", iProovEvent)
iProovMe.addEventListener("progress", iProovEvent)
iProovMe.addEventListener("passed", iProovEvent)
iProovMe.addEventListener("failed", iProovEvent)
iProovMe.addEventListener("error", iProovEvent)
iProovMe.addEventListener("unsupported", iProovEvent)
iProovMe.addEventListener("permission", iProovEvent)
iProovMe.addEventListener("permission_denied", iProovEvent)

function iProovEvent(event) {
  switch (event.type) {
    case "cancelled":
    case "interrupted":
    case "error":
    case "unsupported":
    case "permission":
    case "permission_denied":
      console.warn("iProov " + event.type + " - " + event.detail.reason)
      break
    case "progress":
      console.info(event.detail.message + " (" + event.detail.progress + "%)")
      break
    case "passed":
    case "failed":
      console.log("iProov " + event.detail.type + " " + event.type)
      break
    default:
      console.log("iProov " + event.type)
  }
}

If you're using jQuery, you can attach to all the events in one go:

$("iproov-me").on("ready started cancelled interrupted streamed progress passed failed error unsupported", iProovEvent)

🌎 Localization

The Web SDK ships with English strings by default. To provide strings in another language, you can supply language overrides as JSON. Language files use the same structure.

• View the default language file with all keys and language strings

You can customise the language by supplying the language attribute to your iProov component. The language value must be valid JSON and passed as a string.

Any value not supplied will fall back to the English default.

Override language strings

window.addEventListener("WebComponentsReady", (event) => {
  const iProovMe = document.createElement("iproov-me")
  iProovMe.setAttribute("token", "***YOUR_TOKEN_HERE***")

  const customLanguage = {
    passed: "You passed!",
    prompt_connecting: "It's loading...",
  }
  element.setAttribute("language", JSON.stringify(customLanguage))

  // inject iproov element into page
  document.getElementById("your-container-id").appendChild(iProovMe)
})

Load language file

window.addEventListener("WebComponentsReady", async (event) => {
  async function getLanguage(path) {
    const response = await fetch(path)
    const language = await response.text()

    return language
  }

  const iProovMe = document.createElement("iproov-me")
  iProovMe.setAttribute("token", "***YOUR_TOKEN_HERE***")

  const languageFile = "" // local or external path to language file
  const customLanguage = await getLanguage(languageFile)
  element.setAttribute("language", customLanguage)

  // inject iproov element into page
  document.getElementById("your-container-id").appendChild(iProovMe)
})

There are also some framework specific examples on the Angular and React wiki pages.

🌐 Browser support

iProov's Web SDK makes use of the following technologies:

• WebGL
• WebSockets
• WebAssembly
• WebComponents

iProov Biometrics Web SDK requires access to a front facing camera, WebGL, WebAssembly and the ability to enter full screen. A network connection is required that allows WebSockets. Provided there's a suitable webcam available, most modern desktop browsers fall within these criteria.

Of the mainstream browsers that support the above technologies, we support the last two releases. We feature detect capabilities and provide reasonable fallbacks for older or less mainstream browsers, and only mark them as unsupported if we're confident that the experience won't work.

For known issues, see here.

Platform	Safari	Chrome	Edge	Firefox	Opera	Samsung
Windows	N/A	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	N/A
MacOS	:heavy_check_mark: *	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark: *	:heavy_check_mark:	N/A
iOS	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark: *	:heavy_check_mark:	N/A
Android	N/A	:heavy_check_mark:	:heavy_check_mark:	:heavy_check_mark: *	:heavy_check_mark:	:heavy_check_mark:

* See known issues for more details

ℹ️ If the device attempting to iProov doesn't meet the minimum requirements, the unsupported event is emitted. See the events section for more details.

Support checker

Developers can use the iProovSupport check component to ensure their users have the correct hardware and software to use the Web SDK before embedding the web component. If the user device is unsupported, the integrator can send the user down an alternative journey.

iProovSupport is a lightweight, separate component from the main IProovMe web component. Using iProovSupport on a standalone basis means that consumers can code split their bundle so that users don't need to download an entrypoint that contains the full component until device support has been established.

We recommend using this pattern and splitting entrypoints on your app so that iProov is downloaded only when necessary to ensure a quick UX.

Example usage when using a bundler that treats UMD like ESM:

import { iProovSupport } from "@iproov/web/iProovSupport.js"
const optionalLogger = console
const supportChecker = new iProovSupport(optionalLogger)

Example usage without a bundler, inside a vanilla ES6 / ESM environment:

// ESM without a bundler:
import "@iproov/web/iProovSupport.js
const supportChecker = new window.iProovSupport.default()

Example usage for script tag integrators in test:

iProovSupport is available on the window object via window.IProov once included:

const supportChecker = new window.IProov.IProovSupport()

iProovSupport can check for the required APIs on the user's browser, using either event or Promise based APIs:

How to use iProovSupport:

const supportChecker = new iProovSupport()
// Event based:
supportChecker.addEventListener("check", (event) => {
  const { supported, granted, is_native_bridge } = event.detail
  if (supported === false) {
    // go to fallback UX
  }
  if (supported && granted) {
    // full permission and granted, we can definitely iProov!
    if (is_native_bridge) {
      // if native bridge mode has been detected then permission checks have been circumvented as they aren't needed
    }
  }
  if (supported && granted === null) {
    // browser API support, but we haven't run a permission check (see checkWithPermission)
  }
  if (supported && granted === false) {
    // browser API support, but camera access denied - try again or advise user before proceeding
  }
})

// Promise based:
const { supported, granted, is_native_bridge } = await supportChecker.check()

...or to carry out a complete lightweight check for camera access with user interaction, this can pre-set the required permissions for iProoving, save some bandwidth, and provide a cleaner user journey if camera access isn't possible:

const supportChecker = new iProovSupport()
document.querySelector("#check-button").addEventListener("click", async () => {
  const { supported, granted } = await supportChecker.checkWithPermission()
})

If .checkWithPermission() is executed when permission has already been granted and cached within the browser, further permission checks are not required; we can tell if permission has been granted using a soft .check().

Note that browsers have varying regimes to protect against device fingerprinting and to ensure user privacy. Repeated calls to getUserMedia or the Permissions API can result in prompt blockage, or the redaction of media devices, which can return inaccurate results. Our advice is therefore to avoid running multiple checks, in quick succession, on the same page. Therefore, please avoid automatic or accidental repeat calls to check or checkWithPermission, especially without user interaction.

The following events can be emitted from iProovSupport:

const supportChecker = new iProovSupport()
function onCheckResult(event) {
  const {
    /** @var boolean */
    supported,
    /** @var boolean */
    granted,
    /** @var array */
    tests,
    /** @var boolean|undefined */
    is_native_bridge,
  } = event.detail
  console.debug("Checks run:", tests)
  if (supported) {
    if (is_native_bridge) {
      console.debug("User can iProov with the Native SDK")
    } else {
      console.debug("User can iProov with the Web SDK")
    }
    if (granted) {
      console.debug("User has granted permission for camera access")
    } else {
      console.debug("Prompt the user for camera access permission")
    }
  } else {
    console.error("Browser does not support the Web SDK")
  }
}
const onUnsupported = ({ supported, tests }) => ({})
const onPermissionWasGranted = ({ tests }) => ({})
const onPermissionWasDenied = ({ tests }) => ({})
supportChecker.addEventListener("check", onCheckResult)
supportChecker.addEventListener("unsupported", onUnsupported)
supportChecker.addEventListener("granted", onPermissionWasGranted)
supportChecker.addEventListener("denied", onPermissionWasDenied)
// The `tests` object consists of the following options:
// null if unchecked, true if supported, false if not supported:
const possibleTests = {
  videoInput: null,
  wasm: null,
  userMedia: null,
  mediaStreamTrack: null,
  frontCamera: null,
  fullScreen: null,
  webgl: null,
}

The is_native_bridge property will be exposed on support checker events if the checker detects that iProovNativeBridgeInfo exists within the global scope. This variable is injected automatically by the native SDK. In this case, the browser support and permission checks are cast to true as we won't be using the browser to iProov.

Using the support checker is the best and canonical way to detect whether the user's browser supports the Web SDK.

🕸 WebViews

The iProov Web and Native SDKs can work with WebView based apps using the Native Bridge feature. This allows the Web SDK to seamlessly launch the native SDKs embedded within the app.

You can enable this with one line of code in your mobile app; from that point, the Web/Native SDKs take care of the rest.

Note that:

• Native Bridge mode is mandatory for iOS WKWebView based apps until iOS 14.3, when Apple enabled support for getUserMedia. In all other cases, the unsupported event fires.
• In Android WebView apps, it is possible to use the Web SDK directly provided that your app correctly allows fullscreen mode. This ensures the user interface is correctly rendered.

These WebView examples demonstrate how to ensure fullscreen is allowed and configured correctly inside your Android app:

• Java Fullscreen WebView Example
• Kotlin Fullscreen WebView Example

🌉 Native bridge

If integrating iProov into a WebView based app, why not take advantage of our Native SDKs?

Native SDK integration is possible with one line of code in a single location in your app's codebase. The Web SDK then automatically detects and switches to Native Bridge mode if available.

Native SDK integration guides

For more information on using iProov Web within a native WebView based app, see the following Wiki pages:

• Android Native Bridge Integration Guide
• iOS Native Bridge Integration Guide

Customisation

The native_sdk_options setting accepts a base64 encoded JSON object of iProov Native SDK options as defined in the iOS and Android documentation:

iProovMe.setAttribute("native_sdk_options", btoa(JSON.stringify({ ui: { scanLineDisabled: true, filter: "classic" } })))

Iframe integrations

Integrations via iframes are supported by the Web SDK but please note that you must declare that camera and fullscreen permissions are allowed. Any additional permissions you may require must be separated by a semi-colon ;. Please note: accelerometer;gyroscope;magnetometer; are only required if you are intending to complete LA claims.

<iframe src="https://your-iframe-target.example" allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;"></iframe>

Iframe bridge for mobile Safari

If integrating iProov Liveness into an iframed document, you must use Iframe Bridge to support Safari on iOS versions prior to iOS 15. For more details see our Wiki.

Iframe bridge support checker

IProovSupport.check returns a flags object. The presence of requires_iframe_bridge in flags will indicate that Iframe Bridge will be used if a user proceeds. No further tests are made on the host window if this is detected.

❓ Help & support

You may find your question answered on our Wiki pages.

For further help with integrating the SDK, please contact [e-mail].

Known issues

• We do not support tiny video feeds, and will re-prompt the user to provide a different camera.
  • In Firefox this will present the user with the camera prompt again without any further guidance.
• When multiple video devices are attached using Firefox on desktop, permission is requested on each button click.
• iOS WebView based browser support is currently whitelisted to those with the most support.
• MacOS Safari 15.0 is marked as unsupported until further notice due to several regressions out of our control:
  • Safari 15.0 tab crashes when requesting WebGL context
  • Safari 15.0 unable to render webcam to canvas context