SDK methods

This section provides detailed documentation for each SDK method. Scroll down to learn more about how to use each method, including their parameters, usage examples, and important notes.

• initialize
• capture
• close
• dispose
• isSupported
• getIsInitialized
• loadAiModel

initialize

The initialize method is used to initialize the SDK. This method sets up internal variables and downloads the necessary resources for the SDK to function.

Important

• The initialization process can take a few seconds. It is recommended to call this function as early as possible in your flow to ensure a smooth user experience.

Handling initialization errors

Errors that can occur during the initialize() method:

Error Name	Description
CafSdkInitError	An error occurred during the SDK initialization.
CafSdkUnauthorizedError	Unauthorized access to the SDK. Check if the token provided is valid and not expired.

Example

try {
  await sdk.initialize();
  console.log("SDK initialized successfully!");
} catch (error) {
  switch (error.name) {
    case "CafSdkInitError":
      console.error("SDK initialization error:", error.message);
      break;
    case "CafSdkUnauthorizedError":
      console.error("Unauthorized error:", error.message);
      break;
    default:
      console.error("Unexpected init error:", error.name, error.message);
  }
}

Go back to the top

capture

The capture method is used to load the SDK onto the screen and perform document capture. It initializes the video stream (requesting permissions if needed) and loads it into the container.

For more information on input parameters and output results, refer to the lists below:

Input

The capture method takes one parameter:

const captureResult = await documentDetector.capture(options);

This parameter is an object containing the capture options. The following table lists the available capture options:

Parameter	Type	Required?	Default Value
expectedDocument Type and side of the document expected to be detected by the SDK. If value is "any" then any type of document will be accepted.	"rg_front" | "rg_back" | "rg_full" | "cnh_front" | "cnh_back" | "cnh_full" | "crlv" | "rne_front" | "rne_back" | "passport" | "ctps_front" | "ctps_back" | "any"	Yes.	-
mode The capture mode. Can be "automatic", "manual" or "upload". If the option enableFramingAnalyzer was manually set to false, the capture mode will be forced to manual regardless of the value passed in this parameter.	"automatic" | "manual" | "upload"	Yes.	-
automaticCaptureMaxDuration The maximum duration in seconds for the automatic capture. If the duration is exceeded, the manual capture will be triggered.	number	No.	60
uploadFileType The type of the file to be uploaded. The value can be "IMAGE", "PDF" or undefined. If the value is undefined, both image and PDF files can be uploaded.	"IMAGE" | "PDF" | undefined	No.	Both "IMAGE" and "PDF".
personID The ID of the person (used for tracking purposes).	string	No.	undefined
forceEndWhenInvalid Determines whether the capture should be forcefully finished when it is invalid.	boolean	No.	false

Output

The capture() method returns a signed JWT string (signedResponse) from the backend. This JWT encodes all capture metadata and can be verified server-side. To access the capture details on the client side, decode the JWT payload.

const signedResponse = await documentDetector.capture(options);

JWT Payload Fields

The decoded JWT payload contains the following fields:

Field	Type	Description
captures	Array<object>	List of captured document sides. Contains one entry for single-side or full-document captures.
captures[0].scannedLabel	string	The detected document model label, combining type and side. Possible values: "rg_front", "rg_back", "rg_full", "rg_new_front", "rg_new_back", "rg_new_full", "cnh_front", "cnh_back", "cnh_full", "new_cnh_front", "new_cnh_back", "new_cnh_full", "crlv", "new_crlv", "rne_front", "rne_back", "rnm_front", "rnm_back", "passport_full", "ctps_front", "ctps_back", "cin_front", "cin_back", "cin_full", "generic".
captures[0].imageUrl	string	Pre-signed URL to the captured image stored on S3. This URL is temporary and expires after a few hours.
documentType	string	The detected document type in uppercase. Possible values: "CNH", "NEW_CNH", "RG", "RG_NOVO", "CRLV", "NEW_CRLV", "RNE", "RNM", "PASSPORT", "CTPS", "CIN", "OUTROS".
trackingId	string	The tracking identifier for the capture session. It may be empty if not applicable.
iat	number	JWT "issued at" timestamp (Unix epoch in seconds). Indicates when the token was generated.

JWT Payload Example

(e.g., front of CNH):

{
  "captures": [
    {
      "scannedLabel": "new_cnh_front",
      "imageUrl": "https://example-url/image.jpg?signature..."
    }
  ],
  "documentType": "NEW_CNH",
  "trackingId": "",
  "iat": 1781646936
}

The signedResponse JWT should be sent to your backend for server-side validation. Client-side decoding is only intended for display or logging purposes — do not rely on it for security decisions.

Handling capture errors

Error Name	Description
CafSdkCaptureError	An error occurred during the capture process.
CafSdkCanceledError	SDK run canceled by the user.
CafInvalidOptionsError	SDK capture options are invalid. Review the options provided to the SDK.
CafSdkBlockedError	SDK capture has been blocked.
CafUnsupportedError	SDK capture is not supported for the specific document type.
CafCameraPermissionError	Error getting camera permission.
CafCameraPermissionDeniedError	Camera permission denied by the user.
CafCameraUnsupportedError	Camera is not supported by the browser/device.

Example

try {
  // Load the SDK onto the screen and perform document capture.
  // Returns a JWT string containing the signed response with capture metadata.
  const signedResponse = await documentDetector.capture({
    expectedDocument: "cnh_front",
    mode: "automatic",
    automaticCaptureMaxDuration: 30,
    personID: "my-person-id",
  });
  
  // Decode the JWT to extract capture details
  const result = decodeJwt(signedResponse);

} catch (error) {
  switch (error.name) {
    case "CafSdkCaptureError":
      console.error("SDK capture error:", error.message);
      break;
    case "CafSdkCanceledError":
      console.error("Capture canceled by user:", error.message);
      break;
    case "CafInvalidOptionsError":
      console.error("Options error:", error.message);
      break;
    case "CafSdkBlockedError":
      console.error("SDK blocked error:", error.message);
      break;
    case "CafUnsupportedError":
      console.error("Unsupported error:", error.message);
      break;
    case "CafCameraPermissionError":
      console.error("General camera permission error:", error.message);
      break;
    case "CafCameraPermissionDeniedError":
      console.error("Camera permission denied error:", error.message);
      break;
    case "CafCameraUnsupportedError":
      console.error("Camera not supported error:", error.message);
      break;
    default:
      console.error("Unexpected capture error:", error.name, error.message);
  }
}

Go back to the top

close

The close method is used to remove the SDK from the screen, removing its visual elements from the DOM.

Handling close errors

Error Name	Description
CafSdkCloseError	An error occurred while closing the SDK.

Example

try {
  await sdk.close();
} catch (error) {
  switch (error.name) {
    case "CafSdkCloseError":
      console.error("SDK close error:", error.message);
      break;
    default:
      console.error("Unexpected close error:", error.name, error.message);
  }
}

Go back to the top

dispose

The dispose method is used to de-initialize the SDK. It stops the video stream and clears the SDK's internal variables.

Handling dispose errors

Error Name	Description
CafSdkDisposeError	An error occurred while disposing the SDK.

Example

try {
  await sdk.dispose();
} catch (error) {
  switch (error.name) {
    case "CafSdkDisposeError":
      console.error("SDK dispose error:", error.message);
      break;
    default:
      console.error("Unexpected dispose error:", error.name, error.message);
  }
}

Go back to the top

isSupported

The isSupported method checks if the browser supports the SDK.

Example

const isSupported: boolean = sdk.isSupported();

Go back to the top

getIsInitialized

The getIsInitialized method checks if the SDK is initialized.

Example

const isInitialized: boolean = sdk.getIsInitialized();

Go back to the top

loadAiModel

If the option enableFramingAnalyzer was manually set to false, this method will have no effect when called.

The loadAiModel method is optional, but it can greatly enhance the SDK's loading performance. For optimal results, we recommend invoking it as early as possible in your workflow, ideally before reaching the SDK's loading screen. However, if this is not feasible or does not align with the specific requirements of your integration, the initialize method will automatically handle all necessary initialization tasks to ensure the SDK operates correctly.

Handling load AI model errors

Error Name	Description
CafLoadAIModelError	An error occurred while loading the AI model.

Example

try {
  await documentDetector.loadAiModel();
} catch (error) {
  switch (error.name) {
    case "CafLoadAIModelError":
      console.error("SDK load AI model error:", error.message);
      break;
    default:
      console.error("Unexpected load AI model error:", error.name, error.message);
  }
}

Go back to the top