Get started with the Azure AI Vision Face UI Web SDK

In this sample, you will learn how to build and run the face liveness detection application.

Table of Contents

• Introduction
• Prerequisites
• Installation
• Web component and runtime assets
• Integrate face liveness detector into your own application
  • Obtaining a session token
  • Injecting the web component
  • Retrying a liveness check
  • Using the SDK inside an iframe
  • Deployment
• Localization
  • Setting a Locale
• UX Customization
  • Increase your brightness image
  • Font size
  • Font family
  • Continue button
  • Feedback messages
• FAQ
  • Q: How can I get the results of the liveness session?
  • Q: My retry fails or the session will not start a second time. What is wrong?
  • Q: How can I automate deployment of the assets?

Introduction

The Azure AI Vision Face UI Web SDK is a client library intended to enable the integration of the face liveness feature into web-applications. It works seamlessly with Azure AI Face APIs to determine the authenticity of a face in a video stream.

• API reference: AzureAIVisionFaceUI

Prerequisites

1. An Azure Face API resource subscription.
2. Install node from https://nodejs.org/en/download/prebuilt-installer

Installation

1. Create .npmrc file in root of app folder to pull packages from https://pkgs.dev.azure.com/msface/SDK/_packaging/AzureAIVision/npm/registry/ registry. An example .npmrc file is available here(https://github.com/Azure-Samples/azure-ai-vision-sdk/blob/main/samples/web/angularjs/.npmrc).

2. Fetch the base64 access token required in the .npmrc file using the API: Liveness Session Operations - Get Client Assets Access Token

3. To install the SDK via NPM, run the following command in the root of the app folder:

   npm install @azure/ai-vision-face-ui@latest

Web component and runtime assets

The Web SDK installation contains two browser-side packages:

• @azure/ai-vision-face-ui provides the public <azure-ai-vision-face-ui> component and its type definitions.
• @azure-ai-vision-face/ui-assets provides the gated runtime assets, including localization, JavaScript loaders, and WebAssembly binaries under facelivenessdetector-assets/.

Deploy the complete facelivenessdetector-assets directory at the site root. The component detects WebAssembly SIMD support and selects the SIMD runtime when available, with a non-SIMD runtime for compatible fallback. Copying only one loader or .wasm file can therefore break the experience on other browsers.

If you create liveness sessions with clientType: "web", also install @azure-ai-vision-face/ui-server on your app server, from the same registry and at the same version as @azure-ai-vision-face/ui-assets. It writes each session's wasmInjectionBuffer into the WASM before your server sends it to the browser; see the package README for usage.

npm install @azure-ai-vision-face/ui-server@<ui-assets version>

Gated distribution does not make browser assets secret: JavaScript and WASM downloaded by a browser can be inspected. Never expose the Face API key in frontend code, and retrieve the liveness decision through your app server. Following the Face Liveness architecture, the server creates a short-lived session and sends its authorization token to the frontend; the frontend runs the SDK, while the server retrieves the live/spoof result.

Integrate face liveness detector into your own application

First, ensure you have installed the npm package as described in the Installation section.

Obtaining a session token

The session-authorization-token is required to start a liveness session. See fetchTokenOnServer in server.js file method for a demo. For more information on how to orchestrate the liveness flow by utilizing the Azure AI Vision Face service, visit: https://aka.ms/azure-ai-vision-face-liveness-tutorial

Injecting the web component

After obtaining a valid session-authorization-token, you can integrate the web component, <azure-ai-vision-face-ui> element, using JavaScript.

const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui");
document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI);
azureAIVisionFaceUI.start("***FACE_API_SESSION_TOKEN***")
  .then(resultData => { 
    // The resultData which is LivenessDetectionSuccess interface.
    // The result of analysis is queryable from the service using sessions result API
    // https://learn.microsoft.com/rest/api/face/liveness-session-operations/get-liveness-session-result?view=rest-face-v1.2-preview.1&tabs=HTTP

  })
  .catch(errorData => {
    // In case of failures, the promise is rejected. The errorData which is LivenessDetectionError interface, contains the reason for the failure.
  });

Retrying a liveness check

A session token represents a single liveness session. You can let the user make more than one attempt within that session without asking your backend for a new token, as long as you stay on the same loaded page.

To retry, remove the existing <azure-ai-vision-face-ui> element, create a new one, and call start() again with the same token. Do not reload the page to retry.

function retryLivenessCheck() {
  // 1. Remove the previous detector instance.
  document.querySelector("azure-ai-vision-face-ui")?.remove();

  // 2. Create a fresh instance on the same page and reuse the same token.
  const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui");
  document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI);
  azureAIVisionFaceUI.start("***FACE_API_SESSION_TOKEN***")    // same token as the first attempt
    .then(resultData => { /* ... */ })
    .catch(errorData => { /* ... */ });
}

When to ask your backend for a new token instead of reusing the current one:

• You are starting a genuinely new liveness session (a new user, or a new check).
• The page was fully reloaded (see Using the SDK inside an iframe for why a reload matters).
• start() rejected with LivenessError.InvalidToken. This means the current token has reached the end of its allowed use, and the next attempt needs a fresh token from a new session.

A token cannot be reused after the page that is running the SDK has been reloaded. A reload starts the flow over, so it needs a token from a new session.

Using the SDK inside an iframe

The SDK works the same inside an iframe as it does at the top level of a page. Being in an iframe is not, by itself, a special case, and it does not change how tokens or retries work.

The one thing that matters for retries is whether the page running the SDK is fully reloaded between attempts:

• If your retry keeps the page alive and only re-creates the <azure-ai-vision-face-ui> element (as shown in Retrying a liveness check), the same token keeps working. This is true whether the SDK is at the top level or inside an iframe.
• If your retry reloads the page (for example by setting the iframe's src again, navigating it, or calling location.reload() inside it), that is a fresh start and needs a token from a new session. Reusing the previous token after a reload will not work.

This is intentional: a session token is tied to a single session, so it cannot be carried into a freshly loaded page and reused there.

If a parent page hosts the SDK in an iframe and owns the "Try again" control, prefer telling the iframe to retry in place rather than reloading it. A simple way is to send the iframe a message and have the iframe re-run the retry steps:

// In the parent page, on "Try again":
iframe.contentWindow.postMessage({ type: "retry-liveness" }, iframeOrigin);

// Inside the iframe page:
window.addEventListener("message", (event) => {
  if (event.origin !== expectedParentOrigin) return;      // always validate the sender's origin
  if (event.data?.type !== "retry-liveness") return;
  retryLivenessCheck();                                   // re-creates the element, reuses the same token, no reload
});

A working parent + iframe example is included in the JavaScript sample.

Deployment

Essential assets such as WebAssembly binaries and localization files are installed in node_modules/@azure-ai-vision-face/ui-assets/facelivenessdetector-assets. Deploy the complete directory to /facelivenessdetector-assets in your application's public root.

🌍 Localization

The Azure AI Vision Face UI SDK embraces global diversity by supporting multiple languages. The complete list of supported locales and language dictionary is available here

🌐 Setting a Locale

To use a specific locale, assign the locale attribute to the azure-ai-vision-face-ui component. If translations are available for that locale, they will be used; otherwise, the SDK will default to English.

• Example - Enabling Portuguese

  const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui");
  azureAIVisionFaceUI.locale = "pt-PT";  // Setting Portuguese locale
  document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI);

UX Customization

You can customize the layout of the page using following options:

Increase your brightness image

Customize the default "Increase your screen brightness" image by providing your own image. Ensure the image is correctly deployed for production. azureAIVisionFaceUI.brightnessImagePath = newImagePath;

Font size

Customize the default font size for all the text. The default is 1.5rem azureAIVisionFaceUI.fontSize = newSize;

Font family

Customize the default font family for all the text. The default value is font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, 'Open Sans', 'Helvetica Neue', sans-serif;

azureAIVisionFaceUI.fontFamily = newFontFamily;

Continue button

Customize the look and feel of the "Continue" button by providing your own CSS styles. To change the text, use languageDictionary attribute and override the "Continue" key.

azureAIVisionFaceUI.continueButtonStyles = newCSS;

Feedback messages

Customize the look and feel of the feedback messages by providing your own CSS styles.

azureAIVisionFaceUI.feedbackMessageStyles = newCSS;

FAQ

Q: How can I get the results of the liveness session?

Once the session is completed and the promise fulfilled, for security reasons the client does not receive the outcome whether face is live or spoof.

You can query the result from your backend service by calling the sessions results API to get the outcome https://aka.ms/face/liveness-session/get-liveness-session-result

Q: My retry fails or the session will not start a second time. What is wrong?

This almost always comes down to how the retry is wired and which token it uses:

• Reusing a token after a full page reload. A session token is tied to one session and cannot be reused once the page running the SDK has been reloaded. If your "Try again" reloads the page (or reloads the iframe by re-setting its src, navigating it, or calling location.reload()), request a token from a new session for that attempt. See Using the SDK inside an iframe.
• Retrying without reloading is supported and is the recommended pattern. Keep the page loaded, remove the <azure-ai-vision-face-ui> element, create a new one, and call start() again with the same token. See Retrying a liveness check.
• start() rejected with LivenessError.InvalidToken. The current token has reached the end of its allowed use. Obtain a fresh token from a new session before the next attempt.

Note that running inside an iframe does not change any of this. The deciding factor is whether the page was reloaded, not whether the SDK is in an iframe.

Q: How can I automate deployment of the assets?

• React

  For deployment You can add postbuild script to your package.json to copy facelivenessdetector-assets to public

  "scripts": {
      "postbuild": "cpy node_modules/@azure-ai-vision-face/ui-assets/facelivenessdetector-assets/**/* public/facelivenessdetector-assets --parents"
    }

• Angular

  Please see the AngularJS integration example at samples/angularjs/src/face/face.component.ts

  For deployment you can add section to deploy facelivenessdetector-assets in your projects' build section of the configuration file

    
  "build": {
    "options": {
      "assets": [
        { "glob": "**/*", "input": "./node_modules/@azure-ai-vision-face/ui-assets/facelivenessdetector-assets", "output": "/facelivenessdetector-assets" }
      ],
    }
  }