vishwam-react-video-sdk

React components for the Vishwam Self-KYC (SKYC) web journey: photo liveness, video liveness, and document capture. The SDK handles camera access, on-device face detection, backend API calls, session security validation, and lifecycle event publishing for Jio.com integration.

npm package name: vishwam-react-video-sdk

Installation

npm install vishwam-react-video-sdk

Peer dependencies

• react ^17.0.1
• react-dom

The host app must run over HTTPS (or localhost) for camera access and Web Crypto checksum validation.

Quick start

import {
  CheckLiveness,
  VideoLiveness,
  ReadDocument,
  Init
} from 'vishwam-react-video-sdk'

// Optional: preload face-api models before showing capture UI
Init()

function SkycFlow() {
  return (
    <CheckLiveness
      url="https://your-api.vishwamcorp.com/v1"
      appId="jio_self_kyc"
      userId="user-123"
      referenceId="BR122222"          // ORN / order reference number
      requestId="req-abc-456"         // optional — forwarded as request_id to backend
      storeId="store-001"
      captureType="1"
      eyesCheck="1"
      whiteBackground="1"
      expiryIn="1h"
      traceId="trace-1"
      spanId="span-1"
      acknowledgementCallback={handleSdkEvent}
      getLivenessResponse={handleLivenessResult}
    />
  )
}

function handleSdkEvent({ event, referenceId, eventStatus }) {
  // Jio.com uses this for 5s timeout monitoring on lifecycle events
  console.log(event, referenceId, eventStatus)
}

function handleLivenessResult(response) {
  if (response.status === 'failed') {
    console.error(response.error, response.message)
    return
  }
  // success — use response.result, livenessImage, etc.
}

Exports

| Export | Description | |--------|-------------| | CheckLiveness | Image-based face liveness capture | | VideoLiveness | Video-based liveness capture | | ReadDocument | Document photo capture with orientation checks | | Init | Preloads face-api.js models (alias: prepareFaceDetector) |

Common props (all components)

| Prop | Required | Description | |------|----------|-------------| | url | Yes | Vishwam API base URL (e.g. https://apis-selfkyc-….vishwamcorp.com/v1) | | appId | Yes | Application identifier | | referenceId | Yes | Order Reference Number (ORN) — must match backend session | | userId | Yes | User identifier sent as user_id | | requestId | No | Correlation id sent to backend as request_id on all API calls | | storeId | Yes* | Store identifier (required for liveness; optional for ReadDocument) | | expiryIn | Yes | Auth token expiry (e.g. "1h") | | acknowledgementCallback | Yes* | Receives SDK lifecycle events (required for Jio.com timeout integration) | | traceId | No | Distributed tracing id for Jio event URL | | spanId | No | Span id for Jio event URL | | jioEventsUrl | No | Jio Selfcare event GET endpoint (default: production URL) | | cameraLoadTimeout | No | Camera open timeout in ms (default: 5000) | | delayAcknowledgement | No | Delay event callbacks (default: false) | | delayAcknowledgementTime | No | Delay ms (default: 5000) |

CheckLiveness (photo)

Additional props

| Prop | Description | |------|-------------| | captureType, eyesCheck, whiteBackground | Passed to /check_liveness | | getLivenessResponse | Callback with final result or error | | internetErrorMessage, internetDisplayMessage | Custom network error copy | | tooFarMessage, tooCloseMessage | UI hints during face positioning |

Backend APIs used

• POST /get_auth_token
• POST /sdk_init
• POST /check_liveness
• POST /save_skyc_response (errors and event fallback)

Success response (via getLivenessResponse)

Typical shape when liveness passes:

{
  "status": "success",
  "statusCode": "200",
  "referenceId": "BR122222",
  "checksum": "…",
  "result": {
    "live": "yes",
    "liveness-score": "99",
    "to-be-reviewed": "no",
    "livenessImage": ""
  }
}

On non-success preview flows, the SDK attaches:

• livenessImage — base64 image captured
• livenessImageType — MIME type

SDK lifecycle events (photo)

Fired through acknowledgementCallback and published to Jio (when configured):

1. IMAGE_CAPTURE_REQUEST_RECEIVED_BY_VISHWAM_SDK
2. CAMERA_OPENED_BY_VISHWAM_SDK
3. SDK_INIT_API_CALL_SUCCESS / SDK_INIT_API_CALL_FAILED
4. FACE_DETECTION_MODELS_LOADED_BY_VISHWAM_SDK
5. FIRST_FACE_DETECTED_CHECKS_PASSED
6. FACE_CAPTURE_BUTTON_CLICKED_BY_USER
7. FACE_LIVENESS_API_REQUEST_SENT_TO_VISHWAM_BACKEND
8. FACE_LIVENESS_API_RESPONSE_RECEIVED_BY_VISHWAM_SDK
9. FACE_LIVENESS_API_RESPONSE_SENT_TO_JIO_FROM_VISHWAM_SDK
10. IMAGE_CAPTURE_SUCCESSFUL (SUCCESS or FAIL suffix on Jio URL)

Camera failures emit CAMERA_LOAD_FAILURE and return an error via getLivenessResponse.

VideoLiveness (video)

Additional props

| Prop | Description | |------|-------------| | videoMode | "pause" or "restart" | | videoTime | Recording duration in seconds (default: 10) | | livenessImage | Base64 face image from prior photo step | | maxTimeFaceOutOfFrame, maxFailedAttemptsAllowed | Recording quality controls | | getLivenessResponse | Final result callback |

Video-specific events

Includes all photo-equivalent events plus:

• VIDEO_CAPTURE_REQUEST_RECEIVED_BY_VISHWAM_SDK
• VIDEO_CAPTURE_BUTTON_CLICKED_BY_USER_RECORDING_STARTED
• VIDEO_CAPTURE_RECORDING_COMPLETED
• VIDEO_LIVENESS_API_* API events
• VIDEO_CAPTURE_SUCCESSFUL

On non-success, response may include livenessImage, livenessImageType, and livenessVideo (Blob).

ReadDocument (document)

Additional props

| Prop | Description | |------|-------------| | docType | addhar, pan, passport, voter, pwd, others | | documentType, decision, isBack | Passed to /read_document | | getReadDocumentImage | Final result callback |

Document events

1. DOC_CAPTURE_REQUEST_RECEIVED_BY_VISHWAM_SDK
2. CAMERA_OPENED_BY_VISHWAM_SDK
3. SDK_INIT_API_CALL_SUCCESS / SDK_INIT_API_CALL_FAILED
4. DOC_DETECTION_MODELS_LOADED_BY_VISHWAM_SDK
5. DOC_ALIGNMENT_CHECKS_PASSED
6. DOC_CAPTURE_BUTTON_CLICKED_BY_USER
7. DOC_READ_API_* API events
8. DOC_CAPTURE_SUCCESSFUL

Uses rear camera and device orientation for alignment before capture.

Security validation

Before treating a liveness or document response as successful, the SDK validates:

ORN / session identity

Compares referenceId (ORN) from the SDK with referenceId in the backend response. On mismatch:

{
  "status": "failed",
  "error": "session_mismatch",
  "message": "Identity validation failed. Session mismatch detected."
}

Response checksum

When the backend returns checksum, the SDK computes:

HMAC_SHA256(JSON.stringify(response.result), CHECKSUM_KEY)

On mismatch:

{
  "status": "failed",
  "error": "integrity_error",
  "message": "Response integrity validation failed. Checksum mismatch detected.",
  "previewRetry": true
}

previewRetry: true on document/liveness failures allows the host app to reinvoke capture on the preview screen.

Error handling

Errors are delivered through the result callback (getLivenessResponse / getReadDocumentImage), not thrown to React error boundaries.

| Scenario | status | Typical fields | |----------|----------|----------------| | Camera permission denied | failed | errorCode: NotAllowedError, statusCode: 403 | | Camera timeout (5s default) | failed | errorCode: CameraTimeoutError, statusCode: 408 | | Network / retry exhausted | failed | statusCode: 408, custom internetErrorMessage | | ORN mismatch | failed | error: session_mismatch | | Checksum mismatch | failed | error: integrity_error, previewRetry: true | | Backend liveness rejection | failed | backend result + attached preview media |

Camera errors are also logged to Vishwam via POST /save_skyc_response.

Jio.com event publishing

On each lifecycle event the SDK:

1. Calls acknowledgementCallback({ event, referenceId, eventStatus })
2. Fires a GET to jioEventsUrl with query params: orn, traceId, spanId, deviceType, sdkVer, eventName, eventStatus, eventDtTime, eventFailRsn, retry
3. If the Jio endpoint is unreachable, logs the event payload to Vishwam backend

Jio.com integration note: Maintain a configurable ~5s timeout waiting for the first event (IMAGE_CAPTURE_REQUEST_RECEIVED_BY_VISHWAM_SDK or video/doc equivalent). If not received, show: "We are unable to process your request at the moment, please try again" and route back to the capture initiation page.

Disable Jio publishing during local dev:

jioEventsUrl=""

request_id

Pass a correlation id from your order/session layer:

<CheckLiveness requestId={sessionRequestId} … />

The SDK sends request_id on:

• POST /sdk_init
• POST /check_liveness / POST /video_processing / POST /read_document
• POST /save_skyc_response

Omit the prop to leave request_id out of requests (backward compatible).

Typical SKYC flow

1. Init()                         → preload models (optional)
2. <CheckLiveness … />            → photo liveness
3. <VideoLiveness livenessImage={photo} … />  → video liveness
4. <ReadDocument … />             → document capture (if needed)

Each step is a separate component mount. Retain captured image data between steps when video fails but photo succeeded.

Development

npm install
npm run build      # outputs dist/
npm run test       # lint + unit + build
cd example && npm install && npm run dev

npm README display

Yes — when you publish this package, npm automatically uses the README.md at the package root as the homepage content on npmjs.com. No extra configuration is required beyond keeping this file in the repository root (it is not listed in package.json files but is always included in the published tarball).

Support

For API credentials, checksum keys, and environment URLs, contact your Vishwam / Jio integration team.