Migration Guide: Docv-Capture Web 2.x to KYC Documents Capture Web SDK 4.x

This guide explains how to migrate from DocV Capture Web 2.x to @trulioo/kyc-documents-capture 4.x.

Use this guide if your integration still uses any of the following:

• @trulioo/docv-capture-web
• new TruliooCapture()
• initialize(shortCode, previewMode?)
• getCameraComponent(...)
• session-level capture methods that take a camera ID
• renderCamera(...), removeCamera(), or resumeCamera()
• CameraProps(onCaptureRegionChange = ...)
• TruliooCaptureResponse, TruliooManualCaptureResponse, or TruliooVerifyFeedback

What Changed At A Glance

Step 1: Replace The Package And Add The Stylesheet

Replace the 2.0 package with the 4.x package:

npm uninstall @trulioo/docv-capture-web
npm install @trulioo/kyc-documents-capture@^4

Import the Capture stylesheet once from your application's entry file. Version 4.x does not load the camera UI CSS implicitly:

import "@trulioo/kyc-documents-capture/styles";
import {
  initializeCapture,
  createCaptureCamera,
  submitCapture,
  clearSession,
  DetectionType,
} from "@trulioo/kyc-documents-capture/api";

Your bundler must support CSS imports. One stylesheet import is sufficient even when the application creates multiple cameras.

Step 2: Update CDN Imports

For a CDN integration, load main.css before the Capture module. Pin the stylesheet and JavaScript module to the same 4.x version in production:

<link
  rel="stylesheet"
  href="https://cdn.trulioo.com/web/sdk/kyc-documents-capture/4.0.0/main.css"
/>
<script type="module">
  import {
    initializeCapture,
    createCaptureCamera,
    submitCapture,
    clearSession,
    DetectionType,
  } from "https://cdn.trulioo.com/web/sdk/kyc-documents-capture/4.0.0/api.mjs";
</script>

Replace 4.0.0 with the 4.x version you deploy.

Step 3: Replace Session Initialization

The host application no longer creates and initializes a TruliooCapture instance.

// Before: 2.x
const truliooCapture = new TruliooCapture();
await truliooCapture.initialize(shortCode, previewMode);

// After: 4.x
await initializeCapture(shortCode);

Key differences:

• remove new TruliooCapture() from the host application
• replace the instance initialize(...) method with the package-level initializeCapture(...) function
• wait for initialization to resolve before creating a camera or submitting the transaction
• remove the browser-side previewMode argument; environment behavior is no longer selected through this parameter

Step 4: Replace Camera Creation And Detection Types

Create cameras with the package-level createCaptureCamera(...) function:

// Before: 2.x
const documentCamera = truliooCapture.getCameraComponent();
const selfieCamera = truliooCapture.getCameraComponent({
  detectionType: DetectionType.BIOMETRIC_SELFIE,
});

// After: 4.x
const documentCamera = createCaptureCamera();
const selfieCamera = createCaptureCamera({
  detectionType: DetectionType.BIOMETRIC_SELFIE,
});

Create cameras only after initializeCapture(shortCode) succeeds.

The public detection types are also narrower. Capture 2.x exposed DOCUMENT, PASSPORT, BIOMETRIC_SELFIE, and NO_DETECTION; the 4.x Capture API exposes DOCUMENT and BIOMETRIC_SELFIE. Remove dependencies on the 2.x PASSPORT and NO_DETECTION values and use the current capture-mode contract.

Step 5: Update Camera Rendering And Capture-Region Handling

Replace renderCamera(...) with render(...), and move capture-region observation out of CameraProps:

// Before: 2.x
const cameraProps = new CameraProps((captureRegion) => {
  // Render a custom overlay.
});

await documentCamera.renderCamera("camera-root", cameraProps);

// After: 4.x
await documentCamera.render("camera-root");

documentCamera.onCaptureRegion((captureRegion) => {
  // Render a custom overlay.
});

The current public camera props focus on presentation options such as backgroundColor. Use camera.onCaptureRegion(callback) for capture-region updates.

Step 6: Move Capture Operations To The Camera

In 2.x, the session object owned capture operations and each call took a camera ID. In 4.x, the camera instance owns those operations:

// Before: 2.x
truliooCapture.startFeedback(documentCamera.id);
truliooCapture.stopFeedback(documentCamera.id);
truliooCapture.captureLatestFrame(documentCamera.id);
truliooCapture.onFeedbackState((state) => {
  console.log(state);
});

// After: 4.x
documentCamera.startFeedback();
documentCamera.stopFeedback();
documentCamera.captureLatestFrame();
documentCamera.onFeedbackState((state) => {
  console.log(state);
});

Remove camera-ID arguments from these operations.

For a custom auto-capture acceptance rule, use the filter-based path:

documentCamera.startFeedbackWithFilter((feedback) => {
  return feedback.imageFeedbacks.includes("SUCCESS");
});

Step 7: Rename Camera Lifecycle Methods

Update the lifecycle method names:

- documentCamera.renderCamera(...)
+ documentCamera.render(...)

- documentCamera.removeCamera()
+ documentCamera.remove()

- documentCamera.resumeCamera()
+ documentCamera.resume()

Step 8: Update Capture Result Handling

The 2.x capture results exposed individual boolean quality fields and returned a boolean from acceptImage():

// Before: 2.x
result.hasAcceptableQuality;
result.hasBlur;
result.hasDetection;
result.requiresBackCapture;
result.tooClose;
result.tooFar;

const accepted = await result.acceptImage();

In 4.x, auto-capture returns a CaptureImageResult, manual capture returns a CaptureResult, and feedback is represented by string arrays:

// After: 4.x
const hasSuccess = result.imageFeedbacks.includes("SUCCESS")
  || result.imageFeedbacks.includes("SUCCESS_REQUIRES_BACK");

await result.acceptImage();

CaptureResult and CaptureImageResult both expose imageId, acceptImage(), and verifyImage(). CaptureImageResult also exposes imageFeedbacks: string[]. Do not expect acceptImage() to return a boolean; it resolves with void.

Step 9: Update Verification Feedback

The nested documentVerifyResponse contract and its related enums are no longer part of the public web response:

// Before: 2.x
const verifyFeedback = await result.verifyImage();

if (
  verifyFeedback.documentVerifyResponse.documentTypeAccepted
    !== ResultCheck.RESULT_CHECK_DECLINED
) {
  await result.acceptImage();
}

// After: 4.x
const verifyFeedback = await result.verifyImage();
const accepted = verifyFeedback.verifyResponses.some((value) => {
  return value === "SUCCESS" || value === "SUCCESS_REQUIRES_BACK";
});

if (accepted) {
  await result.acceptImage();
}

Replace checks against ResultCheck, DocumentExpirationCheck, and BackImageRequirement with checks against the labels in verifyResponses: string[].

Step 10: Replace Submission And Add Explicit Cleanup

Replace submitTransaction() with submitCapture(), then clear the active session explicitly:

// Before: 2.x
const submitted = await truliooCapture.submitTransaction();

// After: 4.x
await submitCapture();
clearSession();

submitCapture() resolves with void, not a boolean. After clearSession(), call initializeCapture(shortCode) again before reusing the SDK.

Step 11: Update Error Handling

Do not depend on the HandledError surface, including HandledError.FeedbackStopped. The current API rejects the relevant promises with mapped SDK errors and has a dedicated manual-stop rejection path for stopped auto-capture operations.

If 2.x host logic depended on the boolean result of stopFeedback(...), move that logic to the pending startFeedback() rejection path or to explicit host-side state handling.

End-To-End: Before And After

Before: 2.x

import {
  TruliooCapture,
  DetectionType,
  ResultCheck,
} from "@trulioo/docv-capture-web";

const truliooCapture = new TruliooCapture();

truliooCapture.initialize(shortCode, false).then(() => {
  const camera = truliooCapture.getCameraComponent({
    detectionType: DetectionType.DOCUMENT,
  });

  return camera.renderCamera("camera-root").then(() => {
    return truliooCapture.startFeedback(camera.id).then((result) => {
      return result.verifyImage().then((verifyFeedback) => {
        if (
          verifyFeedback.documentVerifyResponse.documentTypeAccepted
            !== ResultCheck.RESULT_CHECK_DECLINED
        ) {
          return result.acceptImage();
        }
      });
    });
  });
}).then(() => {
  return truliooCapture.submitTransaction();
});

After: 4.x

import "@trulioo/kyc-documents-capture/styles";
import {
  initializeCapture,
  createCaptureCamera,
  submitCapture,
  clearSession,
  DetectionType,
} from "@trulioo/kyc-documents-capture/api";

initializeCapture(shortCode)
  .then(() => {
    const camera = createCaptureCamera({
      detectionType: DetectionType.DOCUMENT,
    });

    return camera.render("camera-root").then(() => {
      return camera.startFeedback().then((result) => {
        return result.verifyImage().then((verifyFeedback) => {
          const accepted = verifyFeedback.verifyResponses.some((value) => {
            return value === "SUCCESS" || value === "SUCCESS_REQUIRES_BACK";
          });

          if (!accepted) {
            throw new Error("Captured image was not accepted");
          }

          return result.acceptImage();
        });
      });
    });
  })
  .then(() => submitCapture())
  .then(() => {
    clearSession();
  });

Migration Checklist

• Replace @trulioo/docv-capture-web with @trulioo/kyc-documents-capture 4.x.
• Import @trulioo/kyc-documents-capture/styles once from the npm application entry file, or load the matching CDN main.css before the JavaScript module.
• Pin the CDN JavaScript module and stylesheet to the same 4.x version in production.
• Replace new TruliooCapture() and instance methods with package-level imports from @trulioo/kyc-documents-capture/api.
• Replace initialize(shortCode, previewMode?) with initializeCapture(shortCode).
• Replace getCameraComponent(...) with createCaptureCamera(...).
• Replace renderCamera(...), removeCamera(), and resumeCamera() with render(...), remove(), and resume().
• Move capture operations from the session object to the camera object and remove camera-ID arguments.
• Move capture-region wiring from CameraProps(onCaptureRegionChange = ...) to camera.onCaptureRegion(...).
• Replace boolean image-quality fields with imageFeedbacks string-array checks.
• Replace nested documentVerifyResponse checks with verifyResponses string-array checks.
• Stop expecting boolean results from acceptImage() and submitCapture().
• Replace submitTransaction() with submitCapture() and call clearSession() when the flow is complete.
• Remove dependencies on 2.x detection types such as PASSPORT and NO_DETECTION.
• Update error handling to the current promise-rejection behavior.
• Verify that the camera UI renders correctly in the production build.