FaceAuthenticator

Importing SDK
To use FaceAuthenticator, you can either remotely import the .js file or download it locally.
Remotely
Include the .js file directly from the CDN:
<script src="https://repo.combateafraude.com/javascript/release/face-authenticator/<VERSION>.umd.js" type="text/javascript"></script>
You can retrieve the class from the SDK using the following code:
const { FaceAuthenticatorSdk } = window['@combateafraude/face-authenticator'];
Locally
Download the .js file and import it as an ES6 module:
import { FaceAuthenticatorSdk } from '../assets/js/face-authenticator-<VERSION>.js'
​
Construction
In the builder, the SDK receives a single parameter with the settings:
const sdk = new FaceAuthenticatorSdk(options);
​
Supported parameters
Fields without a default value are required.
Parameter
Required?
​token​
​
Authentication token for consuming the SDK.
Yes.
language
​
Default message language, valid values: en_US, en_BR, es_MX.
No. The default is pt_BR
environmentSettings.disableDesktopExecution
​
Flag indicating whether execution on desktops should be blocked.
No. The default is false
capturerSettings.disableAdvancedCapturing
​
Flag indicating whether advanced capture should be disabled*.
No. The default is false
appearenceSettings.captureButtonIcon
​
Customization of the capture icon accepts values such as image URL or base64 SVGs.
No
appearenceSettings.captureIconSize
​
Customization of the icon size for the captureButtonIcon field.
No
appearenceSettings.captureButtonColor
​
Customization of the default image capture button color.
No
appearenceSettings.switchButtonIcon
​
Customization of the camera switch icon accepts values such as image URL or base64 SVGs.
No
appearenceSettings.switchIconSize
​
Customization of the icon size for the switchButtonIcon field.
No
appearenceSettings.switchIconColor
​
Customization of the color of the default camera switching icon.
No
appearenceSettings.fontFamily
​
Changes the font for all elements contained in the SDK.
No. The pattern is inherited from the page
textSettings.messages.processMessage
​
Customization of the image processing message.
No. The default is "Processando sua foto, aguarde um momento"
textSettings.messages.captureFailedMessage
​
Customization of the capture failure message.
No. The default is "Ops! Tivemos um problema ao processar sua imagem."
*Advanced capture consists of using more complex and not-so-stable APIs in browsers that support them (e.g. ImageCapture)
Example
const sdk = new FaceAuthenticatorSdk({
    token: `my-sdk-token`,
    language: `pt_BR`,
    environmentSettings: {
        disableDesktopExecution: false,
    },
    appearenceSettings: {
        captureButtonIcon: '',
        captureIconSize: '',
        captureButtonColor: '',
        switchButtonIcon: '',
        switchIconSize: '',
        switchIconColor: '',
        fontFamily: '',
    },
    capturerSettings: {
        disableAdvancedCapturing: false,
    },
    textSettings: {
        messages: {
            processMessage: '',
            captureFailedMessage: '',
        },
    }
});
​
CaptureStage
CaptureStage allows the client to configure the stages. To do this, we offer the CaptureStage object, where you can set the following parameters:
Parameter
mode
Desired capture mode. It can be used manual or automatic. In the manual capture, a button will be enabled for the user to perform the capture.
attempts
Number of attempts of the current stage. If it is the only stage, you must pass the value 0.
duration
Duration time of the current stage. If more than one stage is set, the total time for each stage can be set, and when the total time is reached, the stage will move on to the next one. Set to 0 if you don't want to set a time for the stage.
CaptureStage Example
const stages =[{mode: 'automatic', attempts: 3, duration: 60}, {mode: 'manual', attempts: 0, duration: 0}];
Objects are defined for each stage, according to an example, the SDK will start with the automatic capture, where there will be 3 capture attempts or a time limit of 60 seconds for each attempt, after exceeding the time or attempts, the SDK will automatically proceed to the next stage, where the manual capture would be performed without time or attempt limit, so the user can perform as many attempts as he wants without time limit.
Limit SDK attempts
Through the totalAttempts parameter you can set the total number of attempts to run the SDK, after reaching the limit value the SDK will automatically terminate.
totalAttempts Example
await sdk.capture(sdkContainer, stages, {personData, totalAttempts: 3});
Initialization
initialize(): Promise<void>
The SDK has a separate method of initialization, to allow greater control over when it occurs.
During this process, the SDK will initialize its internal variables and download the resources it needs to run.
[!] You must call this method before using other SDK methods.
[!] The initialization of the SDK can take a few seconds. We recommend that you call this function as early as possible in your flow so that opening the SDK is smooth for the user.
Example
await sdk.initialize();
​
Utilization
Opening and taking selfies
capture(container: HTMLElement, stages, {personData?: PersonData, totalAttempts?: Number}): Promise<Result>
Method used to load the SDK onto the screen and perform selfie capture.
It will initialize the video stream (requesting permissions if needed) and load it into the container.
Parameters
Parameter
Type
personData.cpf 
CPF of the user doing the authentication (required).
string
personData.name
Name of the user doing the authentication (optional).
string
¹ If not specified, automatic capture is used.
² If not specified, a default value of 30 seconds is used.
Example
// div or another element on DOM
const sdkContainer = document.getElementById('sdk-displayer');
const personData = { cpf: 'user-cpf', name: 'user-name' };
await sdk.capture(sdkContainer, stages, {personData, totalAttempts});
Return
The return consists of an object with the following fields:
Field
Type
Description
requestId
string
Unique identifier of the requisition
isMatch
boolean
Boolean indicating whether the captured face is identical to the face registered for the entered peopleId
peopleId
string
Information of the document reported for authentication
openEyesProbability
number
Probability of eyes being open in captured selfie
Close SDK
close(): Promise<void>
The method used to remove the SDK on the screen.
De-initialize the SDK
dispose(): Promise<void>
The method used to remove the SDK on the screen.
Will de-initialize the video stream and clear the SDK's internal variables
Complete Example
Soon.

Last modified 4mo ago

Parameter	Required?
`token` Authentication token for consuming the SDK.	Yes.
`language` Default message language, valid values: en_US, en_BR, es_MX.	No. The default is `pt_BR`
`environmentSettings.disableDesktopExecution` Flag indicating whether execution on desktops should be blocked.	No. The default is `false`
`capturerSettings.disableAdvancedCapturing` Flag indicating whether advanced capture should be disabled*.	No. The default is `false`
`appearenceSettings.captureButtonIcon` Customization of the capture icon accepts values such as image URL or base64 SVGs.	No
`appearenceSettings.captureIconSize` Customization of the icon size for the captureButtonIcon field.	No
`appearenceSettings.captureButtonColor` Customization of the default image capture button color.	No
`appearenceSettings.switchButtonIcon` Customization of the camera switch icon accepts values such as image URL or base64 SVGs.	No
`appearenceSettings.switchIconSize` Customization of the icon size for the switchButtonIcon field.	No
`appearenceSettings.switchIconColor` Customization of the color of the default camera switching icon.	No
`appearenceSettings.fontFamily` Changes the font for all elements contained in the SDK.	No. The pattern is inherited from the page
`textSettings.messages.processMessage` Customization of the image processing message.	No. The default is `"Processando sua foto, aguarde um momento"`
`textSettings.messages.captureFailedMessage` Customization of the capture failure message.	No. The default is `"Ops! Tivemos um problema ao processar sua imagem."`

Parameter	Type
`personData.cpf` CPF of the user doing the authentication (required).	`string`
`personData.name` Name of the user doing the authentication (optional).	`string`

Field	Type	Description
`requestId`	`string`	Unique identifier of the requisition
`isMatch`	`boolean`	Boolean indicating whether the captured face is identical to the face registered for the entered `peopleId`
`peopleId`	`string`	Information of the document reported for authentication
`openEyesProbability`	`number`	Probability of eyes being open in captured selfie

FaceAuthenticator

Importing SDK

Remotely

Locally

Construction

Supported parameters

Example

CaptureStage

Limit SDK attempts

Initialization

`initialize(): Promise<void>`

Example

Utilization

Opening and taking selfies

Parameters

Example

Return

Close SDK

`close(): Promise<void>`

De-initialize the SDK

`dispose(): Promise<void>`

Complete Example