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-7.0.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-7.0.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, pt_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

enableFramingAnalyzer

Toggles the AI-guided framing analysis on or off.

When enabled, the SDK uses an AI model to analyze the camera feed and provide real-time feedback to the user, guiding them to adjust the document's position and orientation for optimal capture.

When disabled, the SDK forces the capture mode to "manual" and does not perform any AI-guided framing analysis. The frame is captured and sent directly to our backend for processing. This approach can reduce image quality but significantly improves performance.

Consider disabling this option if you need to optimize the SDK performance on devices with limited resources and your application's use case prioritizes quantity of captures over quality.

boolean

No.

true

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.

Enhanced in v6.8.3: Now uses a nested object format for better organization and readability.

Object

No.

view table

messages

Customizes displayed messages within the SDK to optimize user experience.

Enhanced in v6.8.3: Now uses a nested object format for better organization and readability.

Object

No.

view table

Configuration Format

Starting with version 6.8.3, the SDK uses a nested object format for configuring appearance and messages options, which provides better organization and readability:

appearance: {
  general: {
    fontFamily: "arial",
    closeButtonIconColor: "#FFFFFF",
  },
  capture: {
    captureButtonIconSize: "100%",
    captureButtonColor: "#FFFFFF",
    hideCaptureTitle: false,
  },
  upload: {
    backgroundColor: "#BDBDBD",
    card: {
      backgroundColor: "#FFFFFF",
    },
    startScreen: {
      title: { color: "#323232" },
      details: { color: "#828282" },
      allowButton: {
        backgroundColor: "#323232",
        label: { color: "#FFFFFF" }
      }
    },
    loadingScreen: {
      icon: { color: "#000000" },
      text: { color: "#323232" }
    },
    failureScreen: {
      icon: { color: "#E21B45", shadowColor: "#FFE4E6" },
      title: { color: "#323232" },
      details: { color: "#828282" },
      retryButton: {
        backgroundColor: "#E21B45",
        label: { color: "#FFFFFF" }
      }
    },
    successScreen: {
      icon: { color: "#0BAA43", shadowColor: "#DAFEE5" },
      text: { color: "#0BAA43" }
    }
  }
}

If you're upgrading from a previous version, your existing dot notation configurations (e.g., "general.fontFamily": "arial") will continue to work. However, we recommend migrating to the nested object format for better code organization.

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-7.0.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,
  enableFramingAnalyzer: true,
  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",
      hideCaptureTitle: false,
    },
    upload: {
      backgroundColor: "#BDBDBD",
      card: {
        backgroundColor: "#FFFFFF",
      },
      startScreen: {
        title: { color: "#323232" },
        details: { color: "#828282" },
        allowButton: {
          backgroundColor: "#323232",
          label: { color: "#FFFFFF" },
        },
      },
      loadingScreen: {
        icon: { color: "#000000" },
        text: { color: "#323232" },
      },
      failureScreen: {
        icon: { color: "#E21B45", shadowColor: "#FFE4E6" },
        title: { color: "#323232" },
        details: { color: "#828282" },
        retryButton: {
          backgroundColor: "#E21B45",
          label: { color: "#FFFFFF" },
        },
      },
      successScreen: {
        icon: { color: "#0BAA43", shadowColor: "#DAFEE5" },
        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();

// 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();

Handling build errors

Error Name

Description

CafSdkBuildError

An error occurred during the SDK build/construction.

CafSdkBlockedError

SDK build has been blocked.

CafInvalidOptionsError

SDK build options are invalid. Review the options provided to the SDK.

CafUnsupportedError

SDK is not supported on this device, browser or operating system.

Example

try {
  const sdk = new DocumentDetector(options);
} catch (error) {
  switch (error.name) {
    case "CafSdkBuildError":
      console.error("SDK build error:", error.message);
      break;
    case "CafSdkBlockedError":
      console.error("SDK blocked error:", error.message);
      break;
    case "CafInvalidOptionsError":
      console.error("Invalid options error:", error.message);
      break;
    case "CafUnsupportedError":
      console.error("Unsupported error:", error.message);
      break;
    default:
      console.error("Unexpected build error:", error.name, error.message);
  }
}

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

Last updated 2 months ago