Tích hợp Web SDK

Thiết lập và scan khuôn mặt cho FaceAuthen bằng CAKE eKYC Web SDK. Thực thi bundle.js sẽ tạo object toàn cục window.ekyc.

Điều kiện tiên quyết

Thông tin	Mô tả
Thư mục assets	Một nơi để serve thư mục assets /ekyc.
HTTPS	Bắt buộc để truy cập camera.
Quyền WebView	Trên WebView của iOS, bật allowsInlineMediaPlayback.

Thiết lập HTML

Phần tử container với id cake-ekyc-sdk-container là bắt buộc và phải tồn tại trước khi khởi tạo.

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>FaceAuth Integration</title>
    <style>
      #cake-ekyc-sdk-container {
        width: 100%;
        height: 100vh;
        position: relative;
      }
    </style>
  </head>
  <body>
    <div class="overlay" id="cake-ekyc-sdk-container"></div>

    <script src="/ekyc/bundle.js"></script>

    <script>
      // Code khởi tạo SDK đặt tại đây
    </script>
  </body>
</html>

Khởi tạo

type SDKConfigParams = {
  resourcePath?: string
  baseUrl: string
  token: string
  headers?: Record<string, string>
}

const sdk = await window.ekyc.initialize('cake-ekyc-sdk-container', {
  baseUrl: '<BASE_URL>',
  token: '<ACCESS_TOKEN>',
  resourcePath: '/ekyc/resources',
  headers: {
    'X-Client-Version': '1.0.0',
    'X-Platform': 'web'
  }
})

async function initializeSDK() {
  try {
    const container = document.getElementById('cake-ekyc-sdk-container');
    if (!container) {
      throw new Error('SDK container element not found');
    }

    if (!window.ekyc) {
      throw new Error('eKYC SDK not loaded. Ensure bundle.js is included.');
    }

    return await window.ekyc.initialize('cake-ekyc-sdk-container', {
      baseUrl: '<BASE_URL>',
      token: await fetch('/your-backend/ekyc-token').then((r) => r.text()), // lấy lúc chạy, không đóng gói vào bundle
      resourcePath: '/ekyc/resources'
    });
  } catch (error) {
    console.error('SDK initialization failed:', error);
    throw error;
  }
}

Scan một khuôn mặt

// Khách hàng New-to-Bank — đăng ký lần đầu
const enrolResult = await window.ekyc.scanStart(['face'], {
  isNTB: true,
  faceauthClientId: 'user_00000001',
  faceauthRefId: 'ref_00000001'
})

// Khách hàng quay lại — xác thực
const authResult = await window.ekyc.scanStart(['face'], {
  isNTB: false,
  faceauthClientId: 'user_00000001',
  faceauthRefId: 'ref_00000001'
})

Tham số:

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
types	string[]	Có	—	Truyền ['face'] cho một luồng FaceAuthen.
opts.isNTB	boolean	Không	—	true cho lần đăng ký đầu tiên, false để xác thực một hồ sơ đã có.
opts.faceauthClientId	string	Không	—	Client ID cho xác thực khuôn mặt.
opts.faceauthRefId	string	Không	—	Reference ID cho xác thực khuôn mặt.
opts.timeoutDuration	number	Không	—	Timeout tính bằng mili-giây.

Response

interface FaceScanResult {
  faces: FaceData[];
  sanityResult: SanityResult[];
  livenessResult: LivenessResult;
}

Trường	Kiểu	Mô tả
faces	FaceData[]	Các khuôn mặt đã chụp, mỗi khuôn mặt có image và gesture (left, right, portrait).
sanityResult	SanityResult[]	Kết luận sanity của ảnh chân dung và điểm số cho từng ảnh.
livenessResult	LivenessResult	is_live, score, kết quả theo từng ảnh và main_image_id.

Mỗi faces[].image mang theo id, label, bitmap và response của lần tải lên. Lấy các giá trị id và truyền chúng vào mảng faces cho Đăng ký khuôn mặt hoặc Xác minh Face Authen.

Chuyển đổi bitmap

bitmap là một object ImageData đi kèm hai hàm hỗ trợ:

const blob   = await bitmap.toBlob('image/jpeg')
const base64 = bitmap.toBase64('image/jpeg')

Trạng thái scan

const status = window.ekyc.getScanStatus()
console.log('Face scan completed:', status.faceCompleted)

Trường	Kiểu	Mô tả
faceCompleted	boolean	Scan khuôn mặt đã hoàn tất hay chưa.
faceData	any	Kết quả scan khuôn mặt, được điền sau khi scan.
timestamp	string	Timestamp tùy chọn.

Các trường front, back và qrcode cũng tồn tại trên cùng object này nhưng luôn là false trong một luồng FaceAuthen.

Lời gọi xác thực khuôn mặt

API dựa trên class expose trực tiếp bước xác minh, thay vì đi qua scanStart.

const authResponse = await ekycSDK.verifyFaceAuthentication(authParams);

verifyFaces(faceImages, isFaceAuth) nhận một cờ isFaceAuth chuyển đổi giữa một kiểm tra liveness thuần túy và một xác thực FaceAuthen.

WARNING

Không coi kết quả từ trình duyệt là quyết định cuối cùng. Nó chạy trên một thiết bị bạn không kiểm soát được. Hãy redeem authentication_key từ Xác minh Face Authen trên backend của bạn, sau đó đóng giao dịch bằng Xác minh khóa xác thực giao dịch.

Terminate

await ekyc.terminateScanner();

Giải phóng camera và dọn dẹp. Gọi hàm này khi luồng kết thúc.

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.

Xử lý lỗi

try {
  const result = await window.ekyc.scanStart(['face'], { isNTB: false })
  // Gửi kết quả về backend của bạn; không ghi log — nó chứa dữ liệu sinh trắc học.
} catch (error) {
  console.error('Scan failed:', error.message)
}

Response scan giữ nguyên cấu trúc khi thất bại và đặt chi tiết trong mảng error, cùng một sdkError tùy chọn mang theo kết luận riêng của SDK. Xem Tổng quan Web SDK § Mã lỗi của SDK.

Các vấn đề thường gặp

Thông tin	Mô tả
SDK không tải được	Kiểm tra đường dẫn script và đảm bảo nó tải trước khi sử dụng.
Truy cập camera	Đảm bảo dùng HTTPS và quyền camera đã được cấp.
Không tìm thấy container	Xác nhận phần tử container tồn tại trong DOM.
Vấn đề mạng	Kiểm tra kết nối internet và các endpoint API.

if (typeof window.ekyc === 'undefined') {
    console.error('eKYC SDK not loaded');
}

navigator.mediaDevices.getUserMedia({ video: true })
    .then(stream => {
        stream.getTracks().forEach(track => track.stop());
    })
    .catch(error => {
        console.error('Camera access denied:', error);
    });

Bước tiếp theo

• Tổng quan Web SDK — yêu cầu nền tảng và các tùy chọn FaceAuthen
• Xác minh Face Authen — xác thực bằng các ảnh đã chụp
• Mã lỗi — bảng lỗi API của FaceAuthen