Skip to content

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.

Document 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 - -
deviceRotatedOnOrientation Determines if the selected rotation is forbidden none landscape, portrait or none
documents Expected document type or group XX Any supported document or document group
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
manualCaptureShow Enables the manual capture if set to true true true or false
manualCaptureButtonDelay Time in ms before enabling the manual capture 20000 1500 to 300000
reviewShow Displays the review view if set to true true true or false
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",
        "deviceRotatedOnOrientation": "landscape",
        "documents": "ES2_ID",
        "logoShow": true,
        "closeButtonShow": true,
        "instructionsShow": true,
        "manualCaptureShow": true,
        "manualCaptureButtonDelay": 10000,
        "reviewShow": true,
        "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:

  1. 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'.

  2. 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": "",
}

detectionTimeout

This setting prevents capturing the document in the setted orientation.

If the option is set to "landscape", the SDK will only work in portrait mode. If it's set to "none", the user will be able to capture in both landscape and portrait mode.

Applies to

All screens

Example of deviceRotatedOnOrientation changed:

"setup": {
    "deviceRotatedOnOrientation": "landscape",
}

documents

This setting sets the expected document to be captured.

If the option is set to "XX", the SDK will capture both sides of any document. It can be set to a specific supported document type or group.

Applies to

All screens

Example of documents changed:

"setup": {
    "documents": "US-AL_DrivingLicense_2013",
}

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,
}
Default Configuration Custom Configuration
LogoShowDesktop LogoShowFalseDesktop
LogoShowMobile LogoShowFalseMobile

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,
}
Default Configuration Custom Configuration
InstructionsDefault InstructionsModified
MobileInstructionsDefault MobileInstructionsModified

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 DesktopInstructionsDefault MobileInstructionsDefault
Instructions Reverse DesktopInstructionsBackDefault mobileInstructionsBackModified

Example of instructionsShow removed:

"setup": {
    "instructionsShow": false,
}
Desktop Mobile
Loading loadingDefault loadingDefaultMobile
Instructions (skipped if false) instructionsDefault instructionsDefaultMobile
Capture captureDefault captureDefaultMobile
Review DesktopReviewDefault MobileReviewDefault
Instructions Reverse (skipped if false) DesktopInstructionsBackDefault mobileInstructionsBackModified
Capture Reverse DesktopCaptureBackDefault MobileCaptureBackDefault

manualCaptureShow

The manual capture is enabled after a timeout to let the user with difficulties when capturing a document.

This parameter allows you to enable or disable the manual capture.

Applies to

Desktop Mobile
Capture Obverse DesktopCaptureDefault MobileCaptureDefault
Capture Reverse DesktopCaptureBackDefault MobileCaptureBackDefault

Example of manual capture enabled:

"setup": {
    "manualCaptureShow": true,
}

manualCaptureButtonDelay

This setting controls the manual capture delay.

This parameter allows you to enter a numeric value on miliseconds with a minimun value of 1500ms and a maximum of 300000ms to control when manual capture is enabled.

Applies to

Desktop Mobile
Capture Obverse DesktopCaptureDefault MobileCaptureDefault
Capture Reverse DesktopCaptureBackDefault MobileCaptureBackDefault

Example of manualCaptureButtonDelay customised:

"setup": {
    "manualCaptureButtonDelay": 10000,
}

reviewShow

The review screen is enabled by default, so 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.

Applies to

Desktop Mobile
Review Obverse DesktopReviewDefault MobileReviewDefault
Review Reverse DesktopReviewBackDefault MobileReviewBackDefault

Example of reviewShow removed:

"setup": {
    "reviewShow": false,
}
Desktop Mobile
Capture Obverse captureDefault captureDefaultMobile
Review Obverse (skipped if false) reviewDefault reviewDefaultMobile
Capture Reverse DesktopCaptureBackDefault MobileCaptureBackDefault
Review Reverse (skipped if false) DesktopReviewBackDefault MobileReviewBackDefault
Finish End of the process End of the process

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 Obverse DesktopCaptureDefault MobileCaptureDefault
Capture Reverse DesktopCaptureBackDefault MobileCaptureBackDefault

Example of help icon removed:

"setup": {
    "helpModalShow": false,
}
Default Configuration Custom Configuration
helpModalShowDesktop helpModalShowFalseDesktop
helpModalShowMobile helpModalShowFalseMobile

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 Obverse DesktopCaptureObverseDefault MobileCaptureObverseDefault
Capture Reverse DesktopCaptureReverseDefault MobileCaptureReverseDefault

Example of captureHeadingShow removed:

"setup": {
    "captureHeadingShow": false,
}
Desktop Mobile
Capture Obverse DesktopThemeCaptureObverseWithoutHeading MobileThemeCaptureObverseWithoutHeading
Capture Reverse DesktopThemeCaptureReverseWithoutHeading MobileThemeCaptureReverseWithoutHeading

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 DesktopInstructioseDefault MobileInstructioseDefault
instructions reverse DesktopInstructioseDefault MobileInstructioseDefault

Example of cancelButtonInstructionsShow removed:

"setup": {
    "cancelButtonInstructionsShow": false,
}
Desktop Mobile
instructions DesktopThemeCancelButtonsInstructions MobileThemeCancelButtonsInstructions
instructions reverse DesktopThemeCancelButtonsInstructionsHide MobileThemeCancelButtonsInstructionsHide

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 DesktopInstructionsDefault MobileInstructionsDefault
instructions reverse DesktopInstructionsDefault MobileInstructionsDefault

Example of instructionsHeadingShow removed:

"setup": {
    "instructionsHeadingShow": false,
}
Desktop Mobile
instructions DesktopThemeInstructionsWithoutHeading MobileThemeInstructionsWithoutHeading
instructions reverse DesktopThemeInstructionsBackWithoutHeading MobileThemeInstructionsBackWithoutHeading

reviewHeadingShow

The review 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
review obverse DesktopReviewDefault MobileInstructionsDefault
review reverse DesktopReviewDefault MobileInstructionsDefault

Example of reviewHeadingShow removed:

"setup": {
    "reviewHeadingShow": false,
}
Desktop Mobile
review obverse DesktopThemeReviewWithoutHeading MobileThemeReviewWithoutHeading
review reverse DesktopThemeReviewWithoutHeading MobileThemeReviewWithoutHeading