In this sample, you will learn how to build and run the face liveness detection application.
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.
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).
Fetch the base64 access token required in the .npmrc file using the API: Liveness Session Operations - Get Client Assets Access Token
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
First, ensure you have installed the npm package as described in the Installation section.
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
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.
});
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:
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.
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:
<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.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.
It's important to note that essential assets like WebAssembly (wasm) files and localization files are packaged within the NPM distribution. During deployment to a production environment, it's essential to include these assets. As an example, you can deploy the 'facelivenessdetector-assets' from the node_modules\azure-ai-vision-face-ui folder to the root assets directory like public folder after the npm installation to ensure proper asset deployment.
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
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.
const azureAIVisionFaceUI = document.createElement("azure-ai-vision-face-ui");
azureAIVisionFaceUI.locale = "pt-PT"; // Setting Portuguese locale
document.getElementById("your-container-id").appendChild(azureAIVisionFaceUI);
You can customize the layout of the page using following options:
Customize the default "Increase your screen brightness" image by providing your own image. Ensure the image is correctly deployed for production. azureAIVisionFaceUI.brightnessImagePath = newImagePath;
Customize the default font size for all the text. The default is 1.5rem azureAIVisionFaceUI.fontSize = newSize;
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;
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;
Customize the look and feel of the feedback messages by providing your own CSS styles.
azureAIVisionFaceUI.feedbackMessageStyles = newCSS;
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
This almost always comes down to how the retry is wired and which token it uses:
src, navigating it, or calling location.reload()), request a token from a new session for that attempt. See Using the SDK inside an iframe.<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.
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/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/facelivenessdetector-assets", "output": "/facelivenessdetector-assets" }
],
}
}
Generated using TypeDoc