General¶

The configuration can be inserted using two methods. To know more, please go to Initialize SDK in API section of this documentation.

Validation¶

The SDK internally validates the configuration received, following this process:

Those properties not inserted in the config will take the default values, as shown below.
Each filled property will have its type validated against the types as shown in the table below.
Each filled property will be compared to the allowed values indicated in the table below in bold.

If all these steps are successful, the SDK will start normally. However, if any of these steps finds a misconfiguration, an error will be thrown via the browser's console and an error message will be shown in the browser's screen as well.

Selfie configuration¶

In the configuration, there are several parameters that can be adjusted to customize your experience. All these parameters are nested within the main setup configuration object. This object centralizes the customization of the SDK’s behavior and appearance, allowing you to adjust multiple aspects of the flow from a single place.

Parameter	Description	Default Value	Possible Values
language	Text default values language	browser	ES, EN or browser
pathAssets	Location folder for all the assets	-	-
liveness	Determines whether the selfie flow is active or passive	passive	passive or active
challengeToken	Valid token for active flow	-	-
logoShow	Displays the header with the logo if set to true	true	true or false
closeButtonShow	Displays the close button if set to true	true	true or false
instructionsShow	Displays the instructions view if set to true	true	true or false
reviewShow	Displays the review view if set to true	false	true or false
selectCamera	Chooses which camera to use in the flow	front	front or back
detectionTimeout	Time in ms before recording stops and SDK shuts down	300000	60000 to 300000
helpModalShow	Displays the help button in capture views if set to true	true	true or false
captureHeadingShow	Displays the heading texts in capture views if set to true	true	true or false
cancelButtonInstructionsShow	Hide the cancel button in instructions views if set to false	true	true or false
instructionsHeadingShow	Displays the heading texts in instruction view if is set to true	true	true or false
reviewHeadingShow	Displays the heading texts in review view if is set to true	true	true or false

In the following sections, we provide a detailed explanation of each parameter listed in the table above. This includes their purpose and specific details to help you better understand how to configure and optimize the SDK according to your needs.

Example of default configuration:

"setup": {
        "language": "browser",
        "pathAssets": "assets",
        "liveness": "passive",
        "challengeToken": "",
        "logoShow": true,
        "closeButtonShow": true,
        "instructionsShow": true,
        "reviewShow": false,
        "selectCamera": "front",
        "detectionTimeout": 300000,
        "helpModalShow": true,
        "captureHeadingShow": true,
        "cancelButtonInstructionsShow": true,
        "instructionsHeadingShow": true,
        "reviewHeadingShow": true
    }

language¶

The language setting plays a crucial role in ensuring that users experience the onboarding process in a language that is familiar and comfortable to them. By default, the SDK utilizes the system/browser language to determine the appropriate default texts. If the system/browser language is either English (en) or Spanish (es), the corresponding default texts will be applied. However, if the system/browser language is not English or Spanish, the SDK will fall back to English as the default language, ensuring that users receive texts in a language they can understand.

When customizing texts within the setup sections, it's important to note that these customized texts will override the default texts included within the SDK. This feature allows for extensive personalization and localization of the onboarding experience, catering to specific cultural or regional preferences.

In instances where all texts are intended to be customized, there's no need to explicitly specify the language setting. The default language logic will be bypassed, and all text customizations will take precedence. This approach provides complete flexibility in tailoring the onboarding process to the desired language and cultural context.

To show all texts in a different language (for example Catalonian, Basque, French, etc) It's mandatory to translate them all using the available text parameters in customization text section.

Applies to

All screens

Example of language changed:

"setup": {
    "language": "EN",
}

pathAssets¶

To configure the paths for the media files, please follow these instructions:

Make sure to include the directory where the file is located in the file name. For instance, if our file is stored in a folder named 'images', you should add the following to the file name: '/images/file_name.png'.
Keep in mind that the path for the media files may vary depending on the nested folders you have. For example, if the root directory (referred to as the pathAssets property) is 'assets', and within the assets folder, you have other subfolders like 'images', 'gifs', and so on, the media file path for GIF files would be '/gifs/file_name.gif'.

By following these guidelines, you can properly configure the paths for your media files.

Applies to

All screens

Example of pathAssets changed:

"setup": {
    "pathAssets": "",
}

liveness¶

This parameter specifies whether the process is passive or active.

passive: A passive liveness check is performed automatically while the user takes a selfie. No specific action is required beyond positioning the face and capturing the photo. This mode provides a seamless experience with minimal user interaction.

active: The user is prompted to actively perform a randomized sequence of head movements (e.g., look left, right, up). These actions are guided on-screen and validated in real time to confirm the user is physically present.

Note: The active mode requires the challengeToken parameter to be provided as part of the configuration.

Applies to

	Desktop	Mobile
Capture

Example of liveness changed:

"setup": {
    "liveness": "active",
}

challengeToken¶

Required in active liveness mode. The challengeToken is used to to indicate the number and direction of the head movements that the user must perform.

Applies to

	Desktop	Mobile
Capture

Example of challengeToken changed:

"setup": {
    "challengeToken": ${generatedToken},
}

logoShow¶

This setting allows you to show or hide the logo consistently across all screens, ensuring branding flexibility based on the desired user experience.

If the option to display the logo is disabled, the header component will be removed entirely.

As a result, the vertical space normally occupied by the header component will be released and made available to the SDK. This allows the SDK interface to expand and make full use of the upper portion of the screen, providing a more immersive or space-efficient layout depending on the device and context of use.

Applies to

All screens

Example of logo removed:

"setup": {
    "logoShow": false,
}

	Desktop	Mobile
Default Configuration
Custom Configuration

closeButtonShow¶

Every flow should provide a way to exit the process, which is why a close button is included by default.

If your integration already includes an external close or abort mechanism (such as a custom "X" button), you can configure this parameter to hide the built-in close button.

However, we strongly recommend keeping the SDK's close button visible to ensure a consistent and user-friendly experience across all use cases and devices.

Applies to

All screens

Example of closeButtonShow removed:

"setup": {
    "closeButtonShow": false,
}

	Desktop	Mobile
Default Configuration
Custom Configuration

instructionsShow¶

The tutorial screen is enabled by default to inform the user about what to expect before starting the process.

This parameter allows you to disable the instructions screen, although doing so is not recommended unless your integration includes custom instructions beforehand.

Without clear guidance at the beginning, users may feel confused or unsure about the steps they need to follow, which can lead to a poor experience or incomplete submissions.

Applies to

	Desktop	Mobile
Instructions Face
Instructions Head

Example of instructionsShow removed:

"setup": {
    "instructionsShow": false,
}

Applies to

	Desktop	Mobile
Loading
Instructions (skipped if false)
Capture

reviewShow¶

The review screen is disabled by default, as this provides a smoother experience for the user.

If enabled, the user will have the opportunity to review the captured image and retake it as many times as needed until satisfied.

While this adds flexibility, it may also slightly increase the time required to complete the process.

This option is not available in active liveness mode

Applies to

	Desktop	Mobile
Review

Example of reviewShow removed:

"setup": {
    "reviewShow": false,
}

Applies to

	Desktop	Mobile
Capture
Review (skipped if false)

selectCamera¶

The front-facing camera should be used by default to carry out the process, as the user needs to see themselves during the selfie capture.

The rear camera should only be enabled in exceptional cases—such as when a third party is taking the selfie on behalf of the user.

However, this is strongly discouraged, as it goes against the intended user flow and may compromise the integrity and usability of the process.

This option is not enabled in active flow.

Applies to

	Desktop	Mobile
Capture

Example of selectCamera changed:

"setup": {
    "selectCamera": "back",
}

detectionTimeout¶

Defines how long (in milliseconds) the SDK will wait before automatically stopping the recording and shutting down.

Accepts values between 60,000 and 300,000 ms.

Applies to

All screens

Example of detectionTimeout changed:

"setup": {
    "detectionTimeout": 70000,
}

helpModalShow¶

This setting allows you to show or hide the help icon on the capture screen. This icon enables you to display a help modal to assist the user during the capture process.

While the help modal is open, the capture process will be paused so that the user can read the instructions. Once the help modal is closed, the process will resume.

Applies to

	Desktop	Mobile
Capture Passive
Capture Active

Example of help icon removed:

"setup": {
    "helpModalShow": false,
}

Default Configuration	Custom Configuration

captureHeadingShow¶

The capture heading is enabled by default, so the user will have the opportunity to read the texts to permorm the action.

If these texts are hidden, this will have a negative effect on accessibility.

Applies to

	Desktop	Mobile
Capture Passive
Capture Active

Example of captureHeadingShow removed:

"setup": {
    "captureHeadingShow": false,
}

	Desktop	Mobile
Capture Passive
Capture Active

cancelButtonInstructionsShow¶

The cancel button in instructions is enabled by default, so the user will have the opportunity to hide the cancel button only for the instructions view.

Applies to

	Desktop	Mobile
instructions face

Example of cancelButtonInstructionsShow removed:

"setup": {
    "cancelButtonInstructionsShow": false,
}

	Desktop	Mobile
instructions face

instructionsHeadingShow¶

The instruction heading is enabled by default, so the user will have the opportunity to read the texts to permorm the action.

If these texts are hidden, this will have a negative effect on accessibility.

Applies to

	Desktop	Mobile
instructions face
instructions head

Example of instructionsHeadingShow removed:

"setup": {
    "instructionsHeadingShow": false,
}

	Desktop	Mobile
instructions face
instructions head

reviewHeadingShow¶

The review heading is enabled by default, so the user will have the opportunity to read the texts to permorm the action.

This option is not available in active liveness mode. If these texts are hidden, this will have a negative effect on accessibility.

Applies to

	Desktop	Mobile
review selfie

Example of reviewHeadingShow removed:

"setup": {
    "reviewHeadingShow": false,
}

	Desktop	Mobile
review selfie