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.

Install

npm install truescene-face-id-capture-sdk

Web Component (primary)

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

<script type="module">
  import 'truescene-face-id-capture-sdk'
</script>

<truescene-capture
  session-token="YOUR_SESSION_TOKEN"
  region="us"
  auto-start
></truescene-capture>

Listening for events

<truescene-capture id="capture" session-token="YOUR_SESSION_TOKEN"></truescene-capture>
<script>
  const el = document.getElementById('capture')
  el.addEventListener('verification-code', (event) => {
    console.log('Verification code:', event.detail)
  })
  el.addEventListener('verification-error', (event) => {
    console.log('Verification error:', event.detail)
  })
  el.addEventListener('metrics-change', (event) => {
    console.log('Metrics:', event.detail)
  })
  el.addEventListener('capture', (event) => {
    console.log('Images:', event.detail)
  })
</script>

Attributes

• session-token (required): token 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.

Events

• 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.

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

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

Debug metrics (demo-only)

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.

Verification errors

verification-error provides a stable error object:

{ 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:

<truescene-capture
  session-token="YOUR_SESSION_TOKEN"
  region="us"
  show-header="false"
  show-instructions="false"
  show-status="false"
></truescene-capture>

Session token flow

1. Your backend issues a session token (after authenticating the end user).
2. Pass the token to the SDK via session-token (or sessionToken in React).
3. The SDK sends the token in:
   • Authorization: Bearer <token> header (configurable), and
   • session_token field in the request body (configurable).

Verification status (demo only)

The SDK only emits verification_code. Use that code in your app (or backend) to request the verification status. For example:

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 browser.

Contributing

See CONTRIBUTING.md for local development and build workflows.