Web SDK Overview

The eKYC Web SDK is a TypeScript bundle that runs the capture, quality-check and verification flow in the browser. It scans the NID front and back, the QR code, and the user's face, then verifies them against the API. Current version 1.3.20.

Platform

What	Description
Browser	Runs in modern browsers and inside WebViews. Requires HTTPS and camera permission.
WebView	On iOS WebViews, enable inline media playback — `allowsInlineMediaPlayback` in Flutter and React Native.
Node Engine	>= 20 to build the bundle.

Build dependencies

What	Description
`@tensorflow/tfjs-core` 4.20.0	Core operators and data structures.
`@tensorflow/tfjs-backend-cpu` 4.20.0	Runs models on the device CPU.
`@tensorflow/tfjs-tflite` 0.0.1-alpha.8	Runs TensorFlow Lite models in JavaScript.
`@vladmandic/human` 3.2.2	Face detection and facial attribute analysis.
`@types/w3c-image-capture` 1.0.10	Types for the W3C Image Capture API.
`javascript-obfuscator` 4.1.1	Obfuscates the built bundle.
`esbuild` 0.24.0	Bundler and compiler.

What the SDK Does For You

scanStart runs a pipeline rather than a single action, the same way the Mobile SDK's takeNID and takeFaces do.

What	Description
`scanStart(['front','back'])`	Captures the card → uploads → checks sanity → extracts card info.
`scanStart(['face'])`	Captures the selfie → uploads → checks face sanity → checks liveness.
`scanStart(['qrcode'])`	Scans and decodes the QR code on the card.

Quality checks run on the device before upload, so the user sees a blurred-image warning immediately rather than after a network round trip.

The class-based API (CakeEkycSDK) also exposes the individual steps — scanNID, scanFace, verifyNID, verifyFaces, verifyPair, verifyFaceAuthentication — when you need to drive them yourself.

WARNING

The SDK's result object is for driving the UI only. Base the onboarding decision on results your backend fetches from the eKYC server (or on responses whose X-Signature your backend has verified) — never on verdicts reported by the app or browser, which a modified client can change.

Common Configuration

Param	Type	Required	Default	Description
`baseUrl`	string	Yes	—	Base URL for API requests.
`token`	string	Yes	—	Authentication token. Fetch it from your backend at runtime.
`resourcePath`	string	No	—	Path to SDK resources.
`headers`	`Record<string, string>`	No	—	Additional HTTP headers.

WARNING

The token is a per-tenant credential. Fetch it from your backend — never hardcode it in the page or commit it to source. The Access Key itself must never reach the browser.

Journey

The standard flow runs front to back to face, with a review step after each capture:

text

Start
  → Scan Front NID → Preview Front NID
  → Scan Back NID  → Preview Back NID
  → Verify (Front + Back)
  → Scan Face
  → Verify (Front + Back + Face)
End

What	Description
Scan Front NID	Capture the front side of the National ID.
Preview Front NID	Show the capture to the user for review.
Scan Back NID	Capture the back side.
Preview Back NID	Show the capture to the user for review.
Verify (Front + Back)	Check that front and back are consistent and valid.
Scan Face	Capture the user's face.
Verify (Front + Back + Face)	Compare the face against the photo and data on the ID.

Packaging

The build bundles with esbuild, then obfuscates and strips console calls.

javascript

function createBuildSettings(options) {
  return {
    entryPoints: ['./demo/adapter.ts'],
    outfile: 'dist/adapter.js',
    sourcemap: false,
    bundle: true,
    plugins: [
      esbuildPluginTsc({ force: false }),
      ObfuscatorPlugin({
        compact: true,
        controlFlowFlattening: true,
        filter: [],
      }),
    ],
    ...options,
  }
}

const settings = createBuildSettings({
  minify: true,
  minifyWhitespace: true,
  minifyIdentifiers: true,
  minifySyntax: true,
  treeShaking: true,
  drop: ['console'],
  ignoreAnnotations: true,
})

await esbuild.build(settings)

SDK Error Codes

Raised by the SDK itself, separate from the numeric API error codes. The values match the Mobile SDK.

Field	Type	Description
`60000`	NID_SANITY_FAILED	NID sanity check failed.
`60001`	NID_TAMPERING_FAILED	NID tampering detection failed.
`60002`	FACE_SANITY_FAILED	Face sanity check failed.
`60003`	FACE_LIVENESS_FAILED	Face liveness check failed.

QR scanning has its own codes:

Field	Type	Description
`DOP-675_001`	Scan timeout	"Hết thời gian quét mã. Vui lòng thử lại."
`DOP-675_002`	Scan error	"Không thể quét được mã QR, vui lòng thử lại!"

Unlike the Mobile SDK, the Web SDK has no 40000–40003 range — timeouts, cancellation and permission failures surface as thrown exceptions or as sdkError on the response.

APIs Used

What	Description
Upload Image	Every captured image is uploaded before any check runs.
Verify ID Card Sanity	Checks the authenticity and validity of the card.
Read ID Card Info	OCR, MRZ and QR extraction.
Verify Face Sanity · Verify Face Liveness	Selfie quality and liveness.
Compare Faces	Matches the selfie against the card portrait.
FaceAuthen	Verifies identity against a stored reference. Documented in the FaceAuthen.

Next Steps

Web SDK Integration — setup, initialization, scanning and error handling
Web SDK Reference — the global object and TypeScript interfaces
Web SDK Architecture — layers, modules and key classes

Web SDK Overview ​

Platform ​

Build dependencies ​

What the SDK Does For You ​

Common Configuration ​

Journey ​

Packaging ​

SDK Error Codes ​

APIs Used ​

Next Steps ​