TrueScene Capture SDK

Framework-agnostic video capture and ID verification delivered as a Web Component,
with a thin React wrapper for React apps. The SDK performs the capture flow and
calls ml service using a session token you provide to obtain a verification code. Your app can use that code to request a verification status from your backend.

please visit: https://demo.truescene.site/ for demo and https://truescene.site/ to obtain API key for your back to be able to initiate verification session.

Install

``bash
npm install truescene-face-id-capture-sdk
`

Web Component (primary)

Import the SDK once to register the custom element, then render it anywhere.

`html


session-token="YOUR_SESSION_TOKEN"
session-id="YOUR_SESSION_ID"
region="us"
auto-start
>
`

$3

`html


`

$3

- session-token (required): token from your backend.
- session-id (required): session id from your backend.
- region (required): eu, us, or sandbox. The SDK calls https://{region}.ml.truescene.site/comparev2(sandbox: https://ml.truescene.site/comparev2).
- compare-timeout-ms (optional): request timeout in milliseconds, default 20000 (0 disables).
- auto-start (optional): start immediately when token is present.
- show-header (optional): show the SDK header block, default true.
- show-instructions (optional): show the instructions paragraph, default true.
- show-status (optional): show the status pills, default true.
- header-eyebrow (optional): override the eyebrow label.
- header-title (optional): override the main title line.
- header-subtitle (optional): override the secondary title line.
- instructions (optional): override the instruction copy.

$3

- ready-change -> { faceReady, idReady }
- step-change -> CaptureStep
- metrics-change -> FaceAndIdCaptureMetrics
- capture -> { faceImage, idImage, fullImage }
- verification-code -> VerificationCodeResponse | null
- verification-error -> VerificationError | null
- error -> string

verification-code emits null when a compare request starts, then emits the
final code (or verification-error) once the request finishes.
Requests are aborted when the component unmounts, and timeouts trigger
REQUEST_TIMEOUT.

React wrapper

The React wrapper renders the Web Component and maps its events to props.

`tsx
import TrueSceneCapture from 'truescene-face-id-capture-sdk/react'

sessionToken={sessionToken}
sessionId={sessionId}
region="us"
compareTimeoutMs={20000}
autoStart
showHeader
showInstructions
showStatus
onVerificationCode={(result) => console.log(result)}
onMetricsChange={(metrics) => console.log(metrics)}
onCapture={(images) => console.log(images)}
/>
`

$3

The SDK emits capture metrics through metrics-change. If you want a debug
panel or capture preview cards, build them in your app (as the demo does)
instead of inside the SDK.

$3

verification-error provides a stable error object:

`ts
{ code: string; message: string; status?: number }
`

Codes:

- MISSING_TOKEN
- MISSING_REGION
- HTTP_ERROR
- NETWORK_ERROR
- INVALID_RESPONSE
- REQUEST_TIMEOUT

To hide the built-in header/instructions/status UI in the SDK:

`html
session-token="YOUR_SESSION_TOKEN"
session-id="YOUR_SESSION_ID"
region="us"
show-header="false"
show-instructions="false"
show-status="false"
>
`

Session token flow

1. Your backend starts verification process and sends you a token and a session id (after authenticating the end user).
2. Pass the token to the SDK via session-token (or sessionToken in React) and session-id (or sessionId in React).

Verification status (demo only)

The SDK emits verification_code. Use that code in your appto request the verification status. For example:

`ts
await fetch('https://verification.truescene.site/v1/verification/status', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-TRUESCENE-API-KEY': 'YOUR_API_KEY',
},
body: JSON.stringify({
verification_code,
include_extracted_data: true,
}),
})
`

In production, do this exchange on your backend to avoid exposing API keys in
the front end app.

Contributing

See CONTRIBUTING.md` for local development and build workflows.