HomeDocumentationKnowledge HubSupportRelease NotesSearch Box
Documentation

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

Upgrading from @trulioo/docv-capture-web 2.x to @trulioo/kyc-documents-capture

This guide maps the legacy DocV Capture Web 2.x contract onto the current Trulioo KYC Documents Capture Web SDK.

Use this guide if your integration still follows the older Capture Web SDK that used:

  • @trulioo/docv-capture-web
  • new TruliooCapture()
  • initialize(shortCode, previewMode?)
  • getCameraComponent(...)
  • startFeedback(cameraId)
  • stopFeedback(cameraId)
  • captureLatestFrame(cameraId)
  • submitTransaction()
  • renderCamera(...)
  • removeCamera()
  • resumeCamera()
  • CameraProps(onCaptureRegionChange = ...)
  • TruliooCaptureResponse, TruliooManualCaptureResponse, and TruliooVerifyFeedback

1. Package Name And Entrypoint Changed

The package changed from the legacy DocV Capture Web SDK to the rebranded KYC Documents Capture package.

Legacy 2.x

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

Current KYC Documents Capture

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

Current web identity:

  • npm package: @trulioo/kyc-documents-capture
  • main capture runtime entrypoint: @trulioo/kyc-documents-capture/api

The current public web contract is organized around exported package functions, not a host-created TruliooCapture instance.

2. Session Initialization Changed

Legacy 2.x created a TruliooCapture instance and initialized that instance directly.

Legacy 2.x

const truliooCapture = new TruliooCapture();

truliooCapture.initialize(shortCode, previewMode);

Current KYC Documents Capture

await initializeCapture(shortCode);

or, if the calling site is not async:

initializeCapture(shortCode).then(() => {
  // Create cameras or continue the capture flow here.
});

Key differences:

  • do not create new TruliooCapture() in the host application
  • do not call initialize(...) on a TruliooCapture instance
  • wait for initializeCapture(shortCode) from @trulioo/kyc-documents-capture/api to resolve before continuing
  • the old previewMode parameter is removed

Current behavior:

  • the shortcode is still required
  • preview or environment behavior is no longer selected through a browser-side previewMode argument
  • initialization must finish successfully before creating a camera or submitting the transaction

3. Camera Creation Changed

Legacy 2.x created a camera from the TruliooCapture instance.

Legacy 2.x

const documentCamera = truliooCapture.getCameraComponent();

const selfieCamera = truliooCapture.getCameraComponent({
  detectionType: DetectionType.BIOMETRIC_SELFIE,
});

Current KYC Documents Capture

const documentCamera = createCaptureCamera();

const selfieCamera = createCaptureCamera({
  detectionType: DetectionType.BIOMETRIC_SELFIE,
});

Key differences:

  • getCameraComponent(...) is replaced by createCaptureCamera(...)
  • camera creation is no longer called on a TruliooCapture instance
  • create the camera only after initializeCapture(shortCode) succeeds

4. Supported Detection Types Are Narrower

The legacy 2.x web SDK exposed more public detection-type values than the current 3.0 web package.

Legacy 2.x exported:

  • DOCUMENT
  • PASSPORT
  • BIOMETRIC_SELFIE
  • NO_DETECTION

Current 3.0 web capture exports:

  • DOCUMENT
  • BIOMETRIC_SELFIE

Migration guidance:

  • if your 2.x host code explicitly referenced PASSPORT, update that integration to use the current supported capture mode contract
  • if your 2.x host code referenced NO_DETECTION, remove that dependency from the public web integration

5. Camera Rendering And Camera Props Changed

Legacy 2.x rendered the camera with renderCamera(...) and passed onCaptureRegionChange through CameraProps.

Legacy 2.x

const cameraProps = new CameraProps((captureRegion) => {
  // Render custom overlay
});

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

Current KYC Documents Capture

await documentCamera.render("camera-root");

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

Key differences:

  • renderCamera(...) is replaced by render(...)
  • onCaptureRegionChange is no longer passed through the render props object
  • capture-region observation now uses camera.onCaptureRegion(callback)
  • the current public camera props are narrower and focus on presentation options such as backgroundColor

If your 2.x integration used CameraProps(onCaptureRegionChange = ...), move that overlay wiring to camera.onCaptureRegion(...) after the camera is created.

6. Capture Flow Methods Moved From Session Object To Camera Object

The largest behavioral change is that the active camera owns the capture operations directly.

Legacy 2.x

truliooCapture.startFeedback(documentCamera.id);
truliooCapture.stopFeedback(documentCamera.id);
truliooCapture.captureLatestFrame(documentCamera.id);
truliooCapture.onFeedbackState((state) => {
  console.log(state);
});

Current KYC Documents Capture

documentCamera.startFeedback();
documentCamera.stopFeedback();
documentCamera.captureLatestFrame();
documentCamera.onFeedbackState((state) => {
  console.log(state);
});

Key differences:

  • startFeedback(...) moved from the session object to the camera instance
  • stopFeedback(...) moved from the session object to the camera instance
  • captureLatestFrame(...) moved from the session object to the camera instance
  • onFeedbackState(...) moved from the session object to the camera instance
  • the camera id is no longer passed into those operations

There is also a new explicit filter-based auto-capture path:

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

Use that when the host wants to apply a custom acceptance rule to auto-capture responses.

7. Camera Lifecycle Method Names Changed

The legacy camera lifecycle names changed in 3.0.

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

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

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

These are direct host-code migration changes.

8. Result Objects Changed

Legacy 2.x returned result objects with many boolean quality flags and function properties.

Legacy 2.x

result.hasAcceptableQuality;
result.hasBlur;
result.hasDetection;
result.requiresBackCapture;
result.tooClose;
result.tooFar;
result.acceptImage().then((status) => {
  console.log(status);
});

Current KYC Documents Capture

result.imageFeedbacks;

await result.acceptImage();

Current result behavior:

  • auto-capture returns a CaptureImageResult
  • manual capture returns a CaptureResult
  • CaptureImageResult exposes imageFeedbacks: string[]
  • CaptureResult and CaptureImageResult both expose imageId, acceptImage(), and verifyImage()
  • acceptImage() now resolves with void, not boolean

Migration guidance:

  • replace boolean checks such as hasBlur, tooClose, or requiresBackCapture with string-list checks on imageFeedbacks
  • do not expect acceptImage() to return true

Example:

const hasSuccess = result.imageFeedbacks.includes("SUCCESS")
  || result.imageFeedbacks.includes("SUCCESS_REQUIRES_BACK");

9. Verify Feedback Changed

Legacy 2.x returned a structured documentVerifyResponse object.

Legacy 2.x

result.verifyImage().then((verifyFeedback) => {
  if (verifyFeedback.documentVerifyResponse.documentTypeAccepted !== ResultCheck.RESULT_CHECK_DECLINED) {
    return result.acceptImage();
  }
});

Current KYC Documents Capture

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

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

Key differences:

  • documentVerifyResponse is removed from the public web contract
  • verification results are now exposed as verifyResponses: string[]
  • ResultCheck, DocumentExpirationCheck, and BackImageRequirement are no longer part of the public web verification response
  • host logic should compare returned verification labels instead of reading nested documentVerifyResponse fields

10. Submission And Cleanup Changed

Legacy 2.x used submitTransaction() and implicitly tore down the internal camera/session registry afterward.

Legacy 2.x

truliooCapture.submitTransaction().then((status) => {
  console.log(status);
});

Current KYC Documents Capture

await submitCapture();
clearSession();

Key differences:

  • submitTransaction() is replaced by submitCapture()
  • submitCapture() resolves with void, not boolean
  • clearSession() is now an explicit host call
  • after clearSession(), the host must call initializeCapture(shortCode) again before reuse

11. Error Handling Changed

Legacy 2.x examples often handled stop behavior through HandledError.FeedbackStopped.

Current 3.0 rejects the relevant promises with mapped SDK errors, including a dedicated manual-stop rejection path for stopped auto-capture operations.

Migration guidance:

  • do not expect the old HandledError surface from the 2.0 package
  • update host-side promise rejection handling to the current 3.0 rejection behavior instead of depending on an imported HandledError type
  • if your 2.x code relied on the boolean return from stopFeedback(...), move that logic to the pending startFeedback() rejection path or other host-side state handling

12. Before And After

Legacy 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();
});

Current KYC Documents Capture

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

13. Migration Checklist

  • Replace @trulioo/docv-capture-web with @trulioo/kyc-documents-capture.
  • Replace new TruliooCapture() with package-level imports from @trulioo/kyc-documents-capture/api.
  • Replace initialize(shortCode, previewMode?) with initializeCapture(shortCode).
  • Replace getCameraComponent(...) with createCaptureCamera(...).
  • Replace renderCamera(...) with render(...).
  • Replace removeCamera() with remove().
  • Replace resumeCamera() with resume().
  • Move startFeedback(...), stopFeedback(...), captureLatestFrame(...), and onFeedbackState(...) from the session object to the camera object.
  • Remove camera-id arguments from capture operations.
  • Move overlay-region wiring from CameraProps(onCaptureRegionChange = ...) to camera.onCaptureRegion(...).
  • Replace boolean image-quality fields with imageFeedbacks string-list checks.
  • Replace documentVerifyResponse field checks with verifyResponses string-list checks.
  • Replace submitTransaction() with submitCapture().
  • Add clearSession() when the host application is done with the active Capture transaction.
  • Update host-side type assumptions for removed public detection types such as PASSPORT and NO_DETECTION.

14. Summary Of Breaking Changes

  • The package name changed from DocV Capture Web to KYC Documents Capture.
  • The public web integration moved from an instance-based TruliooCapture API to package-level runtime exports.
  • Initialization changed from initialize(...) to initializeCapture(...).
  • Camera creation changed from getCameraComponent(...) to createCaptureCamera(...).
  • Camera operations moved from session-level camera-id methods to camera-instance methods.
  • Render, remove, and resume method names changed.
  • Capture-region updates moved out of render props and into onCaptureRegion(...).
  • Public detection types are narrower in the current web package.
  • Capture result and verify result contracts changed from boolean/nested-object models to string-list feedback models.
  • acceptImage() and submitCapture() resolve with void, not boolean.
  • Cleanup is now explicit through clearSession().

Updated about 2 hours ago

Did this page help you?

Updated about 2 hours ago

Did this page help you?