HomeDocumentationKnowledge HubSupportRelease NotesSearch Box
Documentation

React Native Capture SDK (Custom UX/UI)

This guide shows how to integrate the Trulioo DocV-Capture SDK in a React Native app and run a full document + selfie verification flow. For the authoritative API reference, see Trulioo’s docs: https://docs.verification.trulioo.com/sdk/getting-started/index.html.

SDK Overview

The DocV-Capture React Native SDK gives organizations the flexibility to design and manage a custom user experience (UX) and user interface (UI) that reflects their brand language. The SDK provides complete control over the look and feel of the capture flow, while Trulioo powers the underlying image capture and verification technology.

This approach enables:

  • Experiences fully aligned with brand guidelines.
  • Custom UI overlays, animations, and messaging.
  • Dependable Trulioo document and selfie capture with built-in verification intelligence.

In short: the brand owns the UI/UX, and Trulioo ensures the capture and verification are accurate and secure.

For organizations that prefer a ready-made solution, Trulioo also offers out-of-the-box SDKs. These SDKs deliver a complete Trulioo-designed UI/UX along with the same trusted image capture and verification technology - ideal for rapid development with minimal customization.

Installation

npm i @trulioo/docv-capture
cd ios && pod install

Document Capture and Verification Flow Overview

Starting a new document verification transaction

Create an instance of TruliooCapture and call the initialize function using the shortcode obtained from the Trulioo API endpoint: /customer/handoff. This will create a new document verification transaction with a unique Transaction ID.

const shortCode = "generatedFromTruliooAPI"

const truliooCapture = new TruliooCapture()

truliooCapture.initialize(shortCode).then((transactionId: string) => {
    console.log(`Successfully initialized with transaction ID: ${transactionId}`)
}).catch((error: any) => {
    console.log(`Error on initialize: ${error}`)
})

Creating and rendering a camera component

Using the same created instance of TruliooCapture, get a camera component to be rendered later by calling the getCameraComponent function. Specify the camera detection type by providing a TruliooCameraConfig with the desired DetectionType.

// Will get a document detection type camera by default.
const documentCamera = truliooCapture.getCameraComponent()


// To get a selfie detection type camera.
const selfieCamera = truliooCapture.getCameraComponent({
  detectionType: DetectionType.BIOMETRIC_SELFIE,
})

To render the camera component on the screen, render the View of the camera component. This will render a full screen camera on the screen. The onCaptureRegionChangecallback function is provided, which will return the current capture frame coordinates location (the location on the camera screen where the document/face should be located to do a capture). Utilize this coordinate information to render a custom UI overlay. The camera View component also provides an option for a customizable background color for the camera mask overlay and a place to render a custom animation that will be rendered on top of the camera component.

render() {
    return (
        <documentCamera.View
            backgroundColor={'#00000000'} // A custom background color for the camera mask overlay.
            onCaptureRegionChange={(captureRegion: CaptureRegion) => {
                // Utilize the given captureRegion data to render custom UI.
            }}
            animationComponent={
                // Custom animation component that will be render on top of the camera.
                <CustomAnimationExample />
            }
        />
    )
}

Additionally, if to resume the camera feed again after a successful auto or manual capture, call the resumeCamera function.

documentCamera.resumeCamera()

Starting the document capture flow

Once the camera component is loaded and ready, to start the document capture experience call the startFeedbackWithVerifyfunction from the previously created TruliooCaptureinstance.

To do an auto capture experience (a good document/selfie image criteria decided entirely by SDK), call startFeedbackWithVerify by just providing the camera id that refers to the currently active/rendered camera component. The promise will only resolve when the SDK manages to capture a good image that is presented in front of the camera capture frame.

truliooCapture.startFeedbackWithVerify(documentCamera.id).then((result: ITruliooCaptureResponse) => {
    console.log(`Successfully captured a good image with imageId: ${result.imageId}`)
})

To stop the feedback call the stopFeedback function. This will stop any ongoing feedback from the camera component.

truliooCapture.stopFeedback(documentCamera.id)

Note that if the stopFeedback function is called during an ongoing startFeedbackWithVerify promise, the startFeedbackWithVerify promise is expected to be rejected with the specific FeedbackStopped error. It is recommended to check this specific error to make sure it is not treated as an unexpected error.

import { HandledError } from '@trulioo/docv-capture'

truliooCapture.startFeedbackWithVerify(documentCamera.id).then((result: ITruliooCaptureResponse) => {
    console.log(`Successfully captured a good image with imageId: ${result.imageId}`)
}).catch((error: unknown) => {
    if (error instanceof HandledError.FeedbackStopped) {
        console.log("startFeedbackWithVerify was stopped.")
    } else {
        // Other error handling
    }
})

Additionally, to do a manual capture call the captureLatestFrame function. This will return a ITruliooManualCaptureResponse that is similar to the ITruliooCaptureResponse excluding the auto capture specific fields.

Note that it is required to ensure that the camera feed is currently running before triggering the manual capture. To resume the camera again after a successful auto or manual capture use the resumeCamera function.

truliooCapture.captureLatestFrame(documentCamera.id).then((result: ITruliooManualCaptureResponse) => {
    console.log(`Successfully captured an image manually with imageId: ${result.imageId}`)
})

The SDK also provides the onFeedbackState function that can be used to listen for ongoing capture state updates that is started by the startFeedbackWithVerify function. This allows for the addition of any logic or to render any necessary custom UI based on the current capture state. It is recommended to call the onFeedbackState function and start listening to the feedback state before calling the startFeedbackWithVerify function.

truliooCapture.onFeedbackState((feedbackState: FeedbackState) => {
        switch (feedbackState) {
            case FeedbackState.NONE:
                // Nothing happened yet/no document detected at this point.
                break
            case FeedbackState.CAPTURING:
                // Currently in the middle of capturing a document.
                break
            case FeedbackState.BLUR:
                // The detected document is blurry. Show a blur UI feedback to user.
                break
            case FeedbackState.SUCCESS:
                // Managed to capture a document.
                break
            default:
                break
        }
    },
)

Note that the above flow is the same for the selfie capture type too.

Analyzing the captured image result through post capture verify response

Once we have the resulting ITruliooCaptureResponse or ITruliooManualCaptureResponse image data, we are able to get a post capture feedback by simply calling the verifyImage function that is part of the response data. This will give us more information regarding the captured image and let us decide whether we should submit the captured image for verification by calling the acceptImage function.

Additionally, the post capture verify response also has a requiresBackCapture boolean field. This will give us information on whether the document requires a back capture or not.

// As an example, we will submit the captured image for document verification if the post capture feedback VerificationStatus is CAN_BE_PROCESSED.
// Note that the documentVerifyResponse will have more than just documentTypeAccepted, the below code is just an example of just checking for documentTypeAccepted.

result.verifyImage().then((verifyFeedback: ITruliooVerifyResponse) => {
    if (verifyFeedback.verificationStatus == VerificationStatus.CAN_BE_PROCESSED) {

        // Note that the acceptImage can be called outside of the verifyImage function.
        result.acceptImage().then((status: boolean) => {
            console.log("Successfully submitted the image.")
            if (verifyFeedback.requiresBackCapture) {
                // Proceed to do a back capture flow.
            } else {
                // Proceed to the other flow, etc.
            }
        })
    } else {
        // Do something else, e.g., notify the user about the not accepted image and retake a new image.
    }
})

Finalize the document verification transaction

After submitting all the necessary images for the transaction, finalize the transaction by calling the submitTransaction function.

truliooCapture.submitTransaction().then((status: boolean) => {
    console.log("Transaction successfully submitted.")
})