Tổng quan Web SDK

eKYC Web SDK là một bundle TypeScript chạy luồng chụp ảnh, kiểm tra chất lượng và xác minh ngay trên trình duyệt. Nó quét mặt trước và mặt sau NID, mã QR, và khuôn mặt của người dùng, sau đó xác minh chúng với API. Phiên bản hiện tại 1.3.20.

Nền tảng

Thông tin	Mô tả
Trình duyệt	Chạy trên trình duyệt hiện đại và bên trong WebView. Yêu cầu HTTPS và quyền camera.
WebView	Trên WebView của iOS, bật chế độ phát media inline — `allowsInlineMediaPlayback` trong Flutter và React Native.
Node Engine	>= 20 để build bundle.

Dependency khi build

Thông tin	Mô tả
`@tensorflow/tfjs-core` 4.20.0	Các toán tử và cấu trúc dữ liệu cốt lõi.
`@tensorflow/tfjs-backend-cpu` 4.20.0	Chạy model trên CPU của thiết bị.
`@tensorflow/tfjs-tflite` 0.0.1-alpha.8	Chạy model TensorFlow Lite trong JavaScript.
`@vladmandic/human` 3.2.2	Nhận diện khuôn mặt và phân tích đặc điểm khuôn mặt.
`@types/w3c-image-capture` 1.0.10	Kiểu dữ liệu cho W3C Image Capture API.
`javascript-obfuscator` 4.1.1	Làm rối bundle đã build.
`esbuild` 0.24.0	Bundler và compiler.

SDK làm gì cho bạn

scanStart chạy một pipeline thay vì một thao tác đơn lẻ, giống cách takeNID và takeFaces của Mobile SDK hoạt động.

Thông tin	Mô tả
`scanStart(['front','back'])`	Chụp thẻ → tải lên → kiểm tra sanity → trích xuất thông tin thẻ.
`scanStart(['face'])`	Chụp selfie → tải lên → kiểm tra sanity khuôn mặt → kiểm tra liveness.
`scanStart(['qrcode'])`	Quét và giải mã mã QR trên thẻ.

Kiểm tra chất lượng chạy ngay trên thiết bị trước khi tải lên, nên người dùng thấy cảnh báo ảnh mờ ngay lập tức thay vì sau một vòng round trip mạng.

API dựa trên class (CakeEkycSDK) cũng expose các bước riêng lẻ — scanNID, scanFace, verifyNID, verifyFaces, verifyPair, verifyFaceAuthentication — khi bạn cần tự điều khiển chúng.

WARNING

Đối tượng kết quả của SDK chỉ dùng để điều khiển giao diện. Quyết định onboarding phải dựa trên kết quả backend của bạn lấy từ eKYC server (hoặc trên response mà backend đã xác minh X-Signature) — không bao giờ dựa trên verdict do ứng dụng hay trình duyệt báo về, vì client bị chỉnh sửa có thể thay đổi chúng.

Cấu hình chung

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
`baseUrl`	string	Có	—	Base URL cho các request API.
`token`	string	Có	—	Authentication token. Lấy từ backend của bạn tại thời điểm chạy.
`resourcePath`	string	Không	—	Đường dẫn đến tài nguyên SDK.
`headers`	`Record<string, string>`	Không	—	Header HTTP bổ sung.

WARNING

token là một thông tin xác thực riêng cho từng tenant. Hãy lấy nó từ backend của bạn — không bao giờ hardcode trong trang hay commit vào source. Bản thân Access Key không bao giờ được phép đến trình duyệt.

Hành trình

Luồng chuẩn chạy từ mặt trước đến mặt sau rồi đến khuôn mặt, với một bước xem lại sau mỗi lần chụp:

text

Bắt đầu
  → Quét mặt trước NID → Xem lại mặt trước NID
  → Quét mặt sau NID    → Xem lại mặt sau NID
  → Xác minh (Mặt trước + Mặt sau)
  → Quét khuôn mặt
  → Xác minh (Mặt trước + Mặt sau + Khuôn mặt)
Kết thúc

Thông tin	Mô tả
Quét mặt trước NID	Chụp mặt trước của thẻ CCCD.
Xem lại mặt trước NID	Hiển thị ảnh đã chụp cho người dùng xem lại.
Quét mặt sau NID	Chụp mặt sau.
Xem lại mặt sau NID	Hiển thị ảnh đã chụp cho người dùng xem lại.
Xác minh (Mặt trước + Mặt sau)	Kiểm tra mặt trước và mặt sau nhất quán và hợp lệ.
Quét khuôn mặt	Chụp khuôn mặt của người dùng.
Xác minh (Mặt trước + Mặt sau + Khuôn mặt)	So sánh khuôn mặt với ảnh và dữ liệu trên thẻ.

Đóng gói

Bản build được đóng gói bằng esbuild, sau đó làm rối và loại bỏ các lệnh gọi console.

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)

Mã lỗi của SDK

Do chính SDK phát sinh, tách biệt với mã lỗi API dạng số. Các giá trị khớp với Mobile SDK.

Trường	Kiểu	Mô tả
`60000`	NID_SANITY_FAILED	Kiểm tra sanity của NID thất bại.
`60001`	NID_TAMPERING_FAILED	Phát hiện giả mạo của NID thất bại.
`60002`	FACE_SANITY_FAILED	Kiểm tra sanity khuôn mặt thất bại.
`60003`	FACE_LIVENESS_FAILED	Kiểm tra liveness khuôn mặt thất bại.

Quét QR có mã riêng:

Trường	Kiểu	Mô tả
`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!"

Khác với Mobile SDK, Web SDK không có dải mã 40000–40003 — timeout, hủy bỏ và lỗi cấp quyền xuất hiện dưới dạng exception được ném ra hoặc dưới dạng sdkError trên response.

API được sử dụng

Thông tin	Mô tả
Tải ảnh lên	Mọi ảnh đã chụp đều được tải lên trước khi bất kỳ kiểm tra nào chạy.
Xác minh ID Card Sanity	Kiểm tra tính xác thực và hợp lệ của thẻ.
Đọc thông tin thẻ ID	Trích xuất OCR, MRZ và QR.
Xác minh sanity khuôn mặt · Xác minh liveness khuôn mặt	Chất lượng và liveness của selfie.
So sánh khuôn mặt	So khớp ảnh selfie với ảnh chân dung trên thẻ.
FaceAuthen	Xác minh danh tính với một tham chiếu đã lưu trữ. Được ghi ở FaceAuthen.

Bước tiếp theo

Tích hợp Web SDK — thiết lập, khởi tạo, scan và xử lý lỗi
Tài liệu tham chiếu Web SDK — object toàn cục và các interface TypeScript
Kiến trúc Web SDK — các layer, module và class chính

Tổng quan Web SDK ​

Nền tảng ​

Dependency khi build ​

SDK làm gì cho bạn ​

Cấu hình chung ​

Hành trình ​

Đóng gói ​

Mã lỗi của SDK ​

API được sử dụng ​

Bước tiếp theo ​