Face Verify Web SDK (v2)

The v2 Face Verify Web SDK was built to standardise user journey screens, slot implementations and reduces complexity of development so that we can provide a consistent user experience and Singpass-branding across all relying parties.

Relying parties will not have to implement the SDK slots anymore. We'll handle all that for you.

Introduction

The Face Verify Web SDK is the client for web-based facial biometrics authentication. It can be integrated in a number of ways to support your web journeys for onboarding and authentication.

As per the previous flows, you will need to call the getSessionToken API to generate a token from your backend to use the Web SDK.

Read more on

• Installation
• Customizing the SDK

Installation

Readme

There are three steps to integrate the SDK, namely:

1. Get your <script> tag to point to our Web SDK URLs.
2. Add <sp-face> element to your page.
3. Attach an event listener to <sp-face> for your page to react on CustomEvents returned by the SDK.

SDK Script Tag

Use one of the following URLs to retrieve our Web SDK:

Environment	SDK URL
Staging	https://assets.biometrics-stg.singpass.gov.sg/sdk-assets/latest/sp-face.js
Production	https://assets.biometrics.singpass.gov.sg/sdk-assets/latest/sp-face.js

Include the SDK script in your web application:

<script src="https://assets.biometrics.singpass.gov.sg/sdk-assets/latest/sp-face.js" />

Appending the custom element to your page

It's very simple to include the Web SDK to your frontend page. Here's the necessary code to do it:

<sp-face 
    token="<YOUR TOKEN HERE>" 
    base_url="<STREAMING ENDPOINT HERE>"
></sp-face>

info

You must call the getSessionToken API first to retrieve the token before appending <sp-face> to your page.

Streaming Endpoints

For base_url, use one of the below:

Environment	SDK URL
Staging	https://stg-bio-stream.singpass.gov.sg
Production	https://bio-stream.singpass.gov.sg

Handling SDK Events

To handle events emitted by the SDK, attach an event listener which fires a callback function to the <sp-face> element.

SDK Event Callback Function

Create a callback function to handle events emitted from the SDK:

const sdkEventCallback = (event) => {
    switch (event.type) {
        case "passed":
            // Call /verify/validate endpoint
            validateResult();
            break;
        case "failed":
            // Call /verify/validate endpoint
            validateResult();
            break
        case "scan_again":
            // Request a new token and re-trigger the flow
            handleNewScan();
            break
        default:
            break;
    }
}

Attach event listeners

Add event listeners to the <sp-face> element:

    let spFaceEl = document.querySelector("sp-face");

    [   
        "passed",
        "failed",
        "scan_again", // <-- New event added in v2
        // Refer below for the full list of CustomEvents that you can attach a listener to.
        // At the minimum you should be handling the 'passed', 'failed' and 'scan_again' events.
    ].forEach((eventName) => {
        spFaceEl.addEventListener(eventName, sdkEventCallback);
    })

Supported events

This is the full list of events that can be emitted from the <sp-face> element:

[
    "scan_again",
    "cancelled",
    "connecting",
    "connected",
    "error",
    "failed",
    "interrupted",
    "multiple_cameras",
    "passed",
    "permission",
    "permission_denied",
    "progress",
    "ready",
    "started",
    "streaming",
    "streamed",
    "unsupported"
]

Frontend Framework Integration

When using frontend frameworks like React or Vue, ensure that:

• The event listener is only registered once.
• The event listener is unregistered when the parent component unmounts.

Self-Hosting Assets (optional)

For using self-hosted assets, set the assets_url:

<sp-face 
    token="<YOUR TOKEN HERE>" 
    base_url="<STREAMING ENDPOINT HERE>"
    assets_url="<URL TO SELF-HOSTED ASSETS>"
></sp-face>