Findface Liveness JS Library

Getting started

Requirements

  • node js v14.17.0 or later (for manual build)

Resources

Installation

This library could be installed by adding package liveness-client-js to the desired project.

Basic usage

After installing the package you can use js build located in node_modules/liveness-client-js/dist/libffl.min.js. Or, build library manually:

npm run build_web

Importing the library gives you an access to FFL namespace, which is used to interact with FindFace Liveness API and the one, that exposes all methods, types and properties available at the moment, as well as to FFLOnboarding, FFLIdentification and FFLVerification classes, that implement common tasks using the FFLApi.

Initialization

First of all you should initialize the api object as follows:

const { FFLApi } = FFL;

/* 
FFLApi(
  serverUrl: string,
  username: string,
  password: string,
  serverVersion: string = "1.0",
  defaultToken: string = null,
  defaultLivenessPort: number = null
)
*/

let api = new FFLApi(serverUrl, login, password, "1.5");

serverUrl: String — String with the API server url

login: String — server login

password: String — server password

To use another login and password, it is necessary to create another FFLApi instance, this is crucial for onboarding, verification and identification to work properly.


init

init method is used to check saved token (if any) validity and perform login procedure using login and password to get new token if needed.

await api.init();

Further steps

After performing all the basic setup described above, you are ready to use all FFLApi methods directly according to the desired business logic.

FFLOnboarding

This is the first of three helper classes, that implements basic user onboarding flow. It's purpose is to create a user dossier (in terms of Findface Platform).

Onboarding is performed in the following steps:

  • addDocument — add document photo (from jpeg file binary)
  • addSelfieMovie — add selfie movie (from mp4 file binary)
  • createDossier — create a dossied by selecting unused login.

On every step application should repeat the step until succeed, re-taking photos, movies or asking user to select another login instead of already used.

Note that if some of these steps, namely addDocument, addSelfieMovie and createDossier, fail — it is ok to repeat any of them until successed. It is not necessary to repeat the whole sequence, for example, if the login has already been performed, just call createDossier one more time.

Initialization

const { FFLOnboarding } = FFL;

const onboarding = FFLOnboarding(api: FFLApi,
                               threshold: number);

api: FFLApiFFLApi instance. Usually it would be the shared instance for the application.

threshold: number — tolerance parameter to use to check document and face similarity during the onboarding process. As for example it is 0.7 by default in the demo app.

addDocument

For this and addSelfieMovie step you would need to be able to take a photo and a video using the mobile/web camera and convert it to binary (Uint8Array)

This is the first onboarding step. Having initialized onboarding as a FFLOnboarding instance, you could use the following code to add a document:

const addDocumentResult = await onboarding.addDocument(docFile, 'name.jpg');
console.log(addDocumentResult.status); // 'Ok'

docFile — image binary (Uin8Array), you get from the camera.

addDocumentResult — Result. You process possible outcomes, for example,Ok as a succesful outcome and processing other possible options as needed.

addSelfieMovie

The second onboarding step. Having initialized onboarding as a FFLOnboarding instance, you could use the following code to add a selfie movie:

const addSelfieResult = await onboarding.addSelfieMovie(videoFile);
console.log(addSelfieResult.status); // 'Ok'

videoFile — video file binary (Uin8Array). Generally you take a selfie video and store the video locally in a temporary file.

addSelfieResult — Result. You process possible outcomes, for example,Ok as a succesful outcome and processing other possible options as needed.

createDossier

The third onboarding step. Having initialized onboarding as a FFLOnboarding instance, you could use the following code to create a user dossier:

const createDossierResult = await onboarding.createDossier(login, password);
console.log(createDossierResult.status); // 'Ok'

login — as the name implies, the desired user login.

password — as the name implies, the desired user password.

createDossierResult — Result. You process possible outcomes, for example,Ok as a succesful outcome and processing other possible options as needed.

After this step completes succesfully, the onboarding flow is finished.

FFLIdentification

Identification instance for a given API.

Identification is a process of finding a dossier by checking and scanning live selfie movie against the dossier available on fflsecurity server.

Identification is performed in the following steps:

  • create instance
  • perform — perform the user identification

Initialization

const { FFLIdentification } = FFL;
let identification = FFLIdentification(api: FFLApi);

api: FFLApiFFLApi instance. Usually it would be the shared instance for the application.

perform

Looks for the Dossier associated with a live face presented in the selfie file after ensuring it is a live person video. See FFLApi.LiveIdentificationResult for explanation of resulting values. The method could be safely called multiple times on the same instance.

const dossier = await identification.perform(videoFile);

videoFile — video file binary (Uin8Array). Generally you take a selfie video and store the video locally in a temporary file.