Getting started

Requirements

Before you start using the Document Detector SDK, you will need to have the following:

A valid Caf access token to authenticate the SDK (check this documentation for more information).
A HTML file with a <body> tag. The SDK will render the document detection UI in this tag.

Importing the SDK

Download the .umd.js file: document-detector-6.2.0.umd.js
Download the .wasm file: dd-validator.wasm
Place both files in the same directory (e.g. public/sdks/caf-dd/).
Import the .umd.js file in your HTML file. For example (assuming a public/index.html file):

<script src="sdks/caf-dd/document-detector-6.2.0.umd.js"></script>

Import the SDK as a JavaScript module in a script tag:

<script type="module">
  const { DocumentDetector } = window["@combateafraude/document-detector"];
  // SDK usage here
</script>

Construction and usage

To use the Document Detector SDK, you will need to create an instance of the DocumentDetector class. This class will allow you to initialize the SDK, capture documents, and close the SDK. You can also pass options to the SDK to customize its behavior.

In the builder, the SDK receives a single parameter with the settings:

const sdk = new DocumentDetector(options);

This parameter is an object containing the configuration options for the SDK. These options customize the behavior of the SDK according to your application's requirements. The following table lists the available options:

Parameter

Type

Required?

Default Value

token

Authentication token for consuming the SDK.

String

Yes.

language

Default message language, valid values: en_US, en_BR, es_MX.

String

No.

pt_BR

blockExecutionOnDesktops

Flag indicating whether execution on desktops should be blocked or not

boolean

No.

false

enableVisibilityChangeSecurity

Enables the security enhancement responsible for closing the SDK when the user switches browser tabs.

boolean

No.

false

analytics

Specifies the analytics settings for the SDK. This parameter allows you to configure analytics tracking within the SDK.

Object

No.

view table

appearance

Specifies the appearance settings for the SDK user interface (UI). This parameter allows you to customize the visual appearance of the SDK components to match the look and feel of your application.

Object

No.

view table

messages

Customizes displayed messages within the SDK to optimize user experience.

Object

No.

view table

Example

index.html

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document Detector</title>
  </head>
  <body>
    <script src="sdks/caf-dd/document-detector-6.2.0.umd.js"></script>
    <script type="module" src="index.js"></script>
  </body>
</html>

index.js

const options = {
  token: "My Access Token",
  language: "pt_BR",
  blockExecutionOnDesktops: false,
  enableVisibilityChangeSecurity: false,
  analytics: {
    enabled: true,
    trackingId: "My Tracking ID",
    trackingInfo: {
      myProp: "My Tracking Info",
    },
    enableDebugMode: false,
  },
  appearance: {
    general: {
      fontFamily: "arial",
      closeButtonIconColor: "#FFFFFF",
    },
    capture: {
      captureButtonIconSize: "100%",
      captureButtonColor: "#FFFFFF",
      cameraSwitchButtonIconSize: "4vh",
      cameraSwitchButtonIconColor: "#FFFFFF",
      hideCameraSwitchButton: false,
      hideCaptureTitle: false,
    },
    "upload.backgroundColor": "#BDBDBD",
    "upload.card.backgroundColor": "#FFFFFF",
    "upload.startScreen.title.color": "#323232",
    "upload.startScreen.details.color": "#828282",
    "upload.startScreen.allowButton.backgroundColor": "#323232",
    "upload.startScreen.allowButton.label.color": "#FFFFFF",
    "upload.loadingScreen.icon.color": "#000000",
    "upload.loadingScreen.text.color": "#323232",
    "upload.failureScreen.icon.color": "#E21B45",
    "upload.failureScreen.icon.shadowColor": "#FFE4E6",
    "upload.failureScreen.title.color": "#323232",
    "upload.failureScreen.details.color": "#828282",
    "upload.failureScreen.retryButton.backgroundColor": "#E21B45",
    "upload.failureScreen.retryButton.label.color": "#FFFFFF",
    "upload.successScreen.icon.color": "#0BAA43",
    "upload.successScreen.icon.shadowColor": "#DAFEE5",
    "upload.successScreen.text.color": "#0BAA43"
  },
};
const documentDetector = new DocumentDetector(options);

// This method is optional, but it can significantly improve the SDK's
// loading experience. We recommend using it as early as possible in your
// workflow, even before reaching the SDK's loading screen. However, if it's
// not feasible or doesn't align with the nature of your flow when
// integrating the SDK, the initialize method will handle everything
// necessary to ensure the SDK functions properly without the need for this method.
await documentDetector.loadAiModel();

// Asks the user to allow camera via the browser being used
// It is important to call this method before initializing the SDK
// A good practice here is to give some feedback to the user that the camera is being requested or that the camera is already allowed
// This method returns a promise that resolves when the user allows the camera, or if the camera is already allowed
await documentDetector.initPermissions();

// Now that the camera is allowed, we can initialize the SDK
await documentDetector.initialize();

// Now that the SDK is initialized, we can start the capture process
// This is the moment that the SDK will be displayed to the user via a modal
// The capture process will start and the user will be able to capture the document
// The capture method returns a promise that resolves when the capture process is finished
const captureResult = await documentDetector.capture({
  expectedDocument: "cnh_front",
  mode: "automatic",
  automaticCaptureMaxDuration: 30,
  personID: "my-person-id",
});

// Now we can close the SDK to stop displaying it
await documentDetector.close();

// And dispose the SDK to free up resources
await documentDetector.dispose();

For more information on the SDK's methods and properties, check the SDK methods documentation.

Last updated 2 days ago