Face Authenticator

Importing SDK

To use Sdk, 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>.js" type="text/javascript"></script>

You can retrieve the class from the SDK using the following code:

const sdk = window['FacesSDK'];

Initialization

initializeSdk(token: string, sdkContainer: string, useFaceAuthenticator: boolean, personId: string, options: any)

The SDK has an isolated initialization method, 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.

Supported Parameters

Parameter	Required?
token Authentication token for consuming the SDK.	Yes.
sdkContainer Id of the container where the SDK will be inserted.	Yes.
useFaceAuthenticator Flag indicating whether to use FaceAuthenticator.	No. The default is false
personId Document number used as a unique identifier for each user.	Yes.
options.timeExpiresUrl Customizing the expiration time of the image Url returned by Sdk.	No. The default is 30 minutes, the accepted values ​​are 3H or 30D.
options.settings.filter Image capture filter customization.	No. The default is shaded
options.settings.language Language customization.	No. The default is pt_BR
options.permissionButton.label Customize the camera permission button text.	No.
options.permissionButton.color Customize the camera permission button text color.	No.
options.permissionButton.backgroundColor Customize camera permission button background color.	No.
options.permissionButton.borderRadius Customize camera permission button border radius.	No.
options.permissionButton.border Customize camera permission button border.	No.
options.startButton.label Customize sdk start button text.	No.
options.startButton.color Customize sdk start button text color.	No.
options.startButton.backgroundColor Customize sdk start button background color.	No.
options.startButton.borderRadius Customize sdk start button border radius.	No.
options.startButton.border Customize sdk start button border.	No.
options.reverseProxy See more details in the Reverse proxy configuration section.	No.

Example

const options = {
  timeExpiresrUrl: '30D',
  settings: {
    filter: 'classic',
    language: 'pt_BR'
  },
  permissionButton: {
    label: 'Permitir',
    color: '#F9F9F9',
    backgroundColor: '#39C560',
    borderRadius: '10px',
    border: '1px solid'
  },
  startButton: {
    label: 'Escanear rosto',
    color: '#F9F9F9',
    backgroundColor: 'blue',
    borderRadius: '0.25rem',
    border: '1px solid #2D994B'
  }
}

const facesSdk = await sdk.initializeSdk(token, sdkContainer, useFaceAuthenticator, personId, options);

Filter

Filter configuration for camera preview. It can be classic, shaded (additional detail, the default), vibrant (full color), clear (no filter) and blur (starts blurred).

Language

Through the language parameter, the application language can be changed, the default value is pt_BR, check the availability below:

Parameter	Language
cy_GB	Welsh.
de	German.
en	English.
es	Spanish.
fr	French.
it	Italian.
nl	Dutch.
pt_BR	Portuguese.

Iframe

To perform integration through an iframe, camera and fullscreen permissions must be provided.

<iframe
  src="https://caf.example"
  allow="camera;fullscreen;accelerometer;gyroscope;magnetometer;"
></iframe>

Reverse proxy configuration

If you choose to use a reverse proxy, you must configure it to properly forward requests to the appropriate endpoints. Below is the mapping for redirection:

• /v1/ → https://api.public.caf.io/v1/sdks/faces/

  • Consider using https://api.public.beta.caf.io/v1/sdks/faces/ for homologation.

• /std/ → https://us.rp.secure.iproov.me/

• /std/ws/ → wss://us.rp.secure.iproov.me/ws/

• /assets/ → https://cdn.iproov.app/

SDK configuration example

Supposing your domain is my.proxy.io, your SDK configuration would look like this:

reverseProxy: {
    authBaseUrl: "https://my.proxy.io/v1/",
    livenessBaseUrl: "https://my.proxy.io/std/",
    assetsBaseUrl: "https://my.proxy.io/assets/"
}

Note: The paths provided in this example are just for reference. You can configure your proxy and paths according to your best practice standards.

Webview

To use the SDK through a Webview, camera permission must be granted in your native application.

Example implementation on Android.

AndroidManifest.xml

  <uses-permission android:name="android.permission.CAMERA" />
  <uses-feature
      android:name="android.hardware.camera"
      android:required="true" />

MainActivity

  @Override
  public void onPermissionRequest(final PermissionRequest request) {
      request.grant(request.getResources());
  }

Sample android project for webview implementation, in addition it is necessary to be able to open the application in full screen, the example shows how to configure it correctly.

Opening and taking selfies

execute()

The 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.

Example

await facesSdk.execute();

Return

Field	Type	Description
signedResponse	string	Signed response from the CAF server confirming that the captured selfie has a real face. This parameter is used to get an extra layer of security, checking that the signature of the response is not broken, or caused by request interception. If it is broken, there is a strong indication of request interception.

Example

{
   "signedResponse": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJyZXF1ZXN0SWQiOiI1ZmUzOTliNi05MWFhLTQ0NmItOWU0OS0yZmM2OGNjMzJiYzciLCJtZXNzYWdlIjoiU3VjY2Vzc2Z1bGx5IiwicGVyc29uSWQiOiJwZXJzb25JZCIsImF0dGVtcHRJZCI6IjY1M2ZmY2NkYjlmMWQ2MjM4ODIyZmJmMCIsImlzTWF0Y2giOnRydWUsImlzQWxpdmUiOnRydWUsInRva2VuIjoiYWRkZDNkYmYwZDE1MGE0NTc1ZTI1N2VmZGFjNWNkN2ZkNWZlYTlmMWFkNjIyY2VlODY2ZmZjMjIxODAxdnUwMSIsInVzZXJJZCI6Ijg5NTQ0MDEzLTc0MDktNGQ0My04ZDFkLTM4NDVlY2E5MzMwNiIsImltYWdlVXJsIjoiaW1hZ2VVcmwiLCJzZGtWZXJzaW9uIjoiaXByb292QDEuMC40IiwiaWF0IjoxNjk4NjkyMzAxfQ.VW8OQShaC7UNy_e9xZ5isKgc9f9JElfMAVsV_dPf8G0"
}

Signed response params

Event	Description
requestId	Request identifier.
isAlive	Validation of a living person, identifies whether the user passed successfully or not.
isMatch	Face match validation result.
token	Request token.
userId	User identifier provided for the request.
imageUrl	Temporary link to the image, generated by our API.
personId	User identifier provided for the SDK.
sdkVersion	Sdk version in use.
iat	Token expiration.
message	Return message.

The isAlive parameter is VERY IMPORTANT, based on it validation must be carried out to continue with the flow or not, in the case of isAlive: true your user can continue with the journey, in the case of isAlive: false, this user is not valid and should be barred from the rest of the journey. Furthermore, the isMatch parameter indicates whether the Face Match passed successfully or not, returning isMatch: true in case of success and false in case of failure.

Events

Currently the SDK emits three types of events:

Event	Description
started	Capture stream initialization.
sdk-button-ready	SDK components have been loaded and ready to use.
passed	Image capture was successful.
failed	Image capture failed.
error	An error occurred during the capture process.
streaming	streaming started, full screen start.
streamed	End of streaming, closing full screen.
canceled	Capture flow cancellation.
permission	Camera permission is requested.
permission_denied	Camera permission was denied.
unsupported	Browser does not support Sdk.

Failed event details

The failed event is of customEvent type, therefore, if you wish to obtain details regarding the reason for the failure, you can consume the event.detail where you will find the following descriptions.

Feedback	Reason	LA	GPA
eyes_closed	Keep your eyes open	✅	✅
face_too_far	Move your face closer to the screen	❌	✅
face_too_close	Move your face farther from the screen	❌	✅
misaligned_face	Keep your face in the oval	❌	✅
multiple_faces	Ensure only one person is visible	✅	✅
obscured_face	Remove any face coverings	✅	✅
sunglasses	Remove sunglasses	✅	✅
too_bright	Ambient light too strong or screen brightness too low	✅	✅
too_dark	Your environment appears too dark	✅	✅
too_much_movement	Please keep still	❌	✅
unknown	Try again	✅	✅

Example failed event listener

document.addEventListener(
  "failed",
  (event) => {
    console.log(event.detail.feedback);
    console.log(event.detail.reason);
  }
);

Error event details

The error event is of customEvent type, therefore, if you wish to obtain details regarding the reason for the error, you can consume the event.detail where you will find the following descriptions.

Feedback	Reason
unknown	Try again
client_camera	There was an error getting video from the camera
client_error	An unknown error occurred
error_asset_fetch	Unable to fetch assets
error_camera	The camera cannot be started for unknown reasons
error_camera_in_use	The camera is already in use and cannot be accessed
error_camera_not_supported	The camera resolution is too small
error_camera_permission_denied	The user denied our camera permission request
error_device_motion_denied	The user denied our device motion permission request
error_device_motion_unsupported	Your device does not seem to fully report device motion
error_fullscreen_change	Exited fullscreen without completing iProov
error_invalid_token	The sdk internal token is invalid
error_network	Network error
error_no_face_found	No face could be found
error_not_supported	The device or integration isn't able to run the Web SDK
error_server	An error occurred when communicating with iProov's servers
error_token_timeout	The token was claimed too long after being created
error_too_many_requests	The service is under high load and the user must try again
error_user_timeout	The user started the claim but did not stream in time
integration_unloaded	The SDK was unmounted from the DOM before it finished
sdk_unsupported	The SDK has passed end of life and is no longer supported

Example error event listener

document.addEventListener(
  "error",
  (event) => {
    console.log(event.detail.feedback);
    console.log(event.detail.reason);
  }
);

Errors

All errors are instances of the Error object. To understand the cause of an error, you can access the error.name and error.message properties, which provide the following details:

Name	Message	Method
CameraPermissionDeniedError	Error camera permission denied by user.	initializeSdk
CameraPermissionError	Error getting camera permission.	initializeSdk
CameraUnsupportedError	Camera is not supported by this browser.	initializeSdk
RequestTokenError	Error while requesting a token.	initializeSdk
RenderCaptureWindowError	Error while rendering the capture window.	initializeSdk
CaptureError	Error while capturing an image.	execute
FaceLivenessError	Error during face liveness detection.	execute
FaceLivenessError	No face could be found in the selfie sent.	execute
FaceLivenessError	Too many requests in a short period of time.	execute
FaceAuthenticationError	Error during face authentication.	execute

Example handling an initializeSdk error

  try {
    const facesSdk = await sdk.initializeSdk(token, sdkContainer, useFaceAuthenticator, personId, options);
  } catch (error) {
    console.log("Error name:", error.name); // RequestTokenError 
    console.log("Error message:", error.message); // Error while requesting a token.
  }

Example handling execute error

  try {
    await facesSdk.execute();
  } catch (error) {
    console.log("Error name:", error.name); // CaptureError 
    console.log("Error message:", error.message); // Error while capturing an image.
  }

Note: The error event details capture specific errors that occur during the liveness detection process, while the errors section refers to more general and fundamental SDK functionalities. Depending on the implementation, you may need to handle both types of errors to ensure a robust integration.