Tài liệu tham chiếu Web SDK

Object toàn cục window.ekyc và các interface TypeScript của nó. Trang này bổ sung cho Tích hợp Web SDK — hãy đọc trang đó trước.

Object toàn cục

Sau khi bundle.js thực thi, window.ekyc expose:

Trường	Kiểu	Mô tả
initializeSDK()	function	Khởi tạo eKYC SDK.
scanNIDOnly()	function	Scan NID, mặt trước và mặt sau.
scanFaceOnly()	function	Scan khuôn mặt.
scanComplete()	function	Hoàn tất scan — NID cộng khuôn mặt.
checkStatus()	function	Kiểm tra trạng thái scan hiện tại.
terminateSDK()	function	Dọn dẹp và kết thúc SDK.

Interface của module

type SDKConfigParams = {
    resourcePath?: string;
    baseUrl: string;
    token: string;
};

interface ScanOptions {
    frontImageId?: string;
    faceauthClientId?: string;
    faceauthRefId?: string;
    isNTB?: boolean;
}

interface NIDScanResult {
    front: Front;
    back: Back;
    status: Status;
}

interface Status {
    frontCompleted: boolean;
    backCompleted: boolean;
    timestamp?: string;
}

declare const _default: {
    readonly initialize: (elementID: string, opts: SDKConfigParams) => Promise<SDK>;
    readonly scanStart: (types: ("face" | "front" | "back")[], opts?: ScanOptions) => Promise<{
        nid?: NIDScanResult;
        face?: FaceScanResult;
    }>;
    readonly getScanStatus: () => Status;
    readonly terminate: () => void;
    readonly CakeEkycSDK: typeof CakeEkycSDK;
};

INFO

Interface module này bỏ sót qrcode khỏi các kiểu của scanStart và khỏi Status, trong khi Tích hợp Web SDK ghi nhận nó được hỗ trợ. Trang tích hợp là nguồn mới hơn — hãy coi qrcode là khả dụng và xác nhận với đội CAKE nếu bundle của bạn từ chối nó.

Scan

const result = await ekyc.scanStart(['front', 'back', 'face']);

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
types	('face' | 'front' | 'back')[]	Có	—	Những lượt scan cần chạy.
opts	ScanOptions	Không	—	Tùy chọn, chủ yếu cho loại face.

Ví dụ

// Chỉ NID
const nidResult = await ekyc.scanStart(['front', 'back']);

// Chỉ khuôn mặt
const faceResult = await ekyc.scanStart(['face']);

// Scan hoàn chỉnh
const completeResult = await ekyc.scanStart(['front', 'back', 'face']);

// Thứ tự tùy chỉnh
const customResult = await ekyc.scanStart(['back', 'front', 'face']);

Terminate

await ekyc.terminateScanner();

INFO

Phương thức này có thể được expose là terminate hoặc terminateScanner tùy bundle. Hãy kiểm tra bundle của bạn expose tên nào trước khi dựa vào một trong hai.

API dựa trên class

CakeEkycSDK cũng được export để dùng trực tiếp, cho khả năng kiểm soát chi tiết hơn scanStart.

import { CakeEkycSDK, SDKConfigParams } from './CakeEkycSDK';

const container = document.getElementById('ekyc-container');
const sdkConfig: SDKConfigParams = {
  baseUrl: '<BASE_URL>',
  token: '<SDK_TOKEN>',
  resourcePath: '/path/to/resources',
};
const ekycSDK = await CakeEkycSDK.initialize(container, sdkConfig);

// Scan một khuôn mặt
const faceScanner = ekycSDK.scanFace();
faceScanner.start();

// Scan một mặt của NID
const cardSide = 'front'; // hoặc 'back'
const nidScanner = ekycSDK.scanNID(cardSide);
nidScanner?.start();

// Xác minh một NID
const verifyStep = ekycSDK.verifyNID(input);
verifyStep.start();

// Xác minh khuôn mặt
const faceVerifyStep = ekycSDK.verifyFaces(faceImages);
faceVerifyStep.start();

// Xác thực khuôn mặt
const authResponse = await ekycSDK.verifyFaceAuthentication(authParams);

Scan theo hướng sự kiện

Các scanner báo cáo thông qua onEvent thay vì resolve một promise.

const nidScanner = sdk.scanNID(cardSide) as CakeNIDScanner
if (!nidScanner) return reject('Error: Can not start scanNID')
nidScanner.start()

terminate = nidScanner.terminate

nidScanner.onEvent = async (event: any) => {
  if (event instanceof Ekyc.NIDScanOutput) {
    // thành công
  } else {
    // lỗi
  }
}

const scanner = sdk.scanFace() as CakeFaceScanner
if (!scanner) return reject('Error: Can not start scanFace')

scanner.start()

terminate = scanner.terminate

scanner.onEvent = async (event) => {
  if (event instanceof Ekyc.FaceScanOutput) {
    // thành công
  } else {
    // lỗi
  }
}

Event của bước xác minh

stepVerify = sdk.verifyNID({
   front: { id: String(opts?.frontImageId) },
   back:  { image: (await event.blob()) as Blob },
})

if (!stepVerify) throw Error('Instance Verify not found!')

stepVerify.start()

stepVerify.onEvent = (
  verifyEvent:
    | Ekyc.CakeNIDVerifySuccess
    | Ekyc.CakeNIDVerifyRuntimeError
    | Ekyc.CakeNIDVerifyCheckFailed
) => {
  if (verifyEvent instanceof Ekyc.CakeNIDVerifySuccess) {
    // thành công
  }
  if (verifyEvent instanceof Ekyc.CakeNIDVerifyRuntimeError) {
    // sanity hoặc liveness thất bại
  }
  if (verifyEvent instanceof Ekyc.CakeNIDVerifyCheckFailed) {
    // so sánh thất bại
  }

  nidScanner.terminate()
}

Trường	Kiểu	Mô tả
Ekyc.CakeNIDVerifySuccess	event	Xác minh đạt.
Ekyc.CakeNIDVerifyRuntimeError	event	Xác minh sanity hoặc liveness của NID thất bại.
Ekyc.CakeNIDVerifyCheckFailed	event	So sánh NID thất bại.
EkycError.UnexpectedError	50000	Runtime exception.

Tải ảnh lên

function uploadImage(params: CESUploadRequest): Promise<HttpResponse<CESUploadResponse>> {
  const formdata = new FormData()
  formdata.append('file', params.file, 'file.jpeg')
  formdata.append('label', params.label)

  return this.client.request({
    method: 'POST',
    url: `${this.params.baseUrl}/v1/images`,
    body: formdata,
    headers: this.getHeader(),
  })
}

uploadImage({ file: file, label })

Hàm này gọi trực tiếp Tải ảnh lên.

Bước tiếp theo

• Tích hợp Web SDK — thiết lập, scan và xử lý lỗi
• Kiến trúc Web SDK — các class đằng sau các lệnh gọi này