Kiến trúc Web SDK
Cách eKYC Web SDK được tổ chức bên trong: bố cục module, năm layer kiến trúc, và các class tạo nên mỗi layer. Hữu ích khi mở rộng SDK hoặc chèn view tùy chỉnh.
Bố cục module
| Trường | Kiểu | Mô tả |
|---|---|---|
CakeEkycSDK.ts | module | Entry point chính, chứa class CakeEkycSDK. |
common/ | directory | Các class và hằng số tiện ích dùng chung trong toàn SDK. |
data/ | directory | Thao tác dữ liệu — HTTP request và logic repository. |
face/ | directory | Scan, xác minh và cấu hình khuôn mặt. |
nid/ | directory | Scan, xác minh và cấu hình NID. |
pipeline/ | directory | Logic quy trình xử lý. |
utils/ | directory | Các hàm tiện ích. |
Các layer
1. Presentation Layer
Giao diện mà người dùng tương tác — render các phần tử, chụp đầu vào, hiển thị phản hồi.
| Trường | Kiểu | Mô tả |
|---|---|---|
DefaultCakeFaceScanView | class | Giao diện scan khuôn mặt. |
DefaultCakeNIDScanView | class | Giao diện scan NID. |
DefaultCakeNIDPreview | class | Giao diện xác nhận NID. |
DefaultCakeLoadingView | class | Giao diện loading. |
2. Business Logic Layer
| Trường | Kiểu | Mô tả |
|---|---|---|
CakeEkycSDK | class | Điều phối luồng xử lý và kết nối các thành phần. |
DefaultCakeFaceScanner | class | Chạy một lượt scan khuôn mặt. |
CakeNIDScanTask | class | Chạy một lượt scan NID. |
CakeFaceVerifyStep | class | Xác minh ảnh khuôn mặt. |
CakeNIDVerifyStep | class | Xác minh ảnh NID. |
FaceAssessorFactory | class | Dựng bộ đánh giá khuôn mặt tổng hợp. |
NIDAssessorFactory | class | Dựng bộ đánh giá NID tổng hợp. |
3. Data Access Layer
| Trường | Kiểu | Mô tả |
|---|---|---|
CakeKYCRepository | interface | Hợp đồng cho mọi lệnh gọi API. |
DefaultCakeKYCRepository | class | Triển khai — xử lý mọi lệnh gọi API bao gồm cả tải ảnh lên. |
HttpClient | class | Thực hiện các HTTP request. |
4. Configuration Layer
| Trường | Kiểu | Mô tả |
|---|---|---|
SDKConfigParams | type | Base URL, token và resource path. |
CakeLivenessConfig | class | Kiểm tra cục bộ, kiểm tra từ xa và schema cho liveness. |
CakeNIDConfig | class | Kiểm tra cục bộ và từ xa cho NID. |
DefaultCakeConfigParsers | class | Phân tích cấu hình được lấy về từ server. |
5. Model Layer
| Trường | Kiểu | Mô tả |
|---|---|---|
CESUploadRequest / CESUploadResponse | type | Tải ảnh lên. |
CESCardSanityRequest / CESCardSanityResponse | type | Sanity của thẻ. |
CESCardTamperingRequest / CESCardTamperingResponse | type | Giả mạo thẻ. |
CESReadCardInfoRequest / CESReadCardInfoResponse | type | Trích xuất thông tin thẻ. |
CESFaceSanityRequest / CESFaceSanityResponse | type | Sanity khuôn mặt. |
CESFaceLivenessRequest / CESFaceLivenessResponse | type | Liveness khuôn mặt. |
CESCompareFaceRequest / CESCompareFaceResponse | type | So sánh khuôn mặt. |
CakeNIDCardSide | enum | FRONT hoặc BACK. |
Luồng giao tiếp
- Người dùng tương tác với Presentation Layer.
- Business Logic Layer xử lý các tương tác đó.
- Khi cần, nó yêu cầu dữ liệu từ Data Access Layer.
- Data Access Layer gọi dịch vụ bên ngoài — ví dụ tải một ảnh lên.
- Kết quả chảy ngược lên qua các layer để cập nhật giao diện.
Việc tải ảnh lên diễn ra ở Data Access Layer: DefaultCakeKYCRepository.uploadImage() dựng một FormData và post nó đến endpoint API.
CakeEkycSDK
Interface chính.
| Trường | Kiểu | Mô tả |
|---|---|---|
container | HTMLElement | Phần tử DOM nơi SDK render giao diện của nó. |
faceConfig | CakeLivenessConfig | Cấu hình cho các thao tác khuôn mặt. |
nidConfig | CakeNIDConfig | Cấu hình cho các thao tác NID. |
sdkConfig | SDKConfigParams | Cấu hình chung của SDK. |
repository | CakeKYCRepository | Xử lý các lệnh gọi API và thao tác dữ liệu. |
Phương thức
| Trường | Kiểu | Mô tả |
|---|---|---|
initialize(container, sdkConfig) | Promise<CakeEkycSDK> | Khởi tạo SDK, lấy và phân tích cấu hình từ server. |
scanFace() | CakeFaceScanner | Bắt đầu một lượt scan khuôn mặt bằng một face scan view và assessor. |
scanNID(cardSide, elements?) | CakeNIDScanner | null | Bắt đầu một lượt scan NID cho một mặt, dùng view và assessor được chèn vào hoặc mặc định. |
verifyNID(input) | CakeNIDVerifyStep | Xác minh NID đã scan. |
verifyFaces(faceImages, isFaceAuth?) | CakeFaceVerifyStep | Xác minh ảnh khuôn mặt cho liveness hoặc xác thực. |
verifyPair(params) | Promise<CESCompareFaceResponse> | So sánh độ tương đồng giữa hai khuôn mặt. |
verifyFaceAuthentication(params) | Promise<CESVerifyFaceAuthenticationResponse> | Xác minh xác thực khuôn mặt phía server. |
CakeKYCRepository
Hợp đồng data-access. Mỗi phương thức ánh xạ đến một endpoint của API.
| Trường | Kiểu | Mô tả |
|---|---|---|
config() | Promise<HttpResponse<CESConfigResponse>> | Lấy cấu hình SDK. |
uploadImage(params) | Promise<HttpResponse<CESUploadResponse>> | Tải ảnh lên |
checkCardSanity(params) | Promise<HttpResponse<CESCardSanityResponse>> | Xác minh ID Card Sanity |
checkCardTampering(params) | Promise<HttpResponse<CESCardTamperingResponse>> | Phát hiện giả mạo thẻ ID |
readIdCardInfo(params) | Promise<HttpResponse<CESReadCardInfoResponse>> | Đọc thông tin thẻ ID |
checFaceSanity(params) | Promise<HttpResponse<CESFaceSanityResponse>> | Xác minh sanity khuôn mặt |
checFaceLiveness(params) | Promise<HttpResponse<CESFaceLivenessResponse>> | Xác minh liveness khuôn mặt |
compareFace(params) | Promise<HttpResponse<CESCompareFaceResponse>> | So sánh khuôn mặt |
verifyFaceAuthentication(params) | Promise<HttpResponse<CESVerifyFaceAuthenticationResponse>> | Xác minh FaceAuthen. |
INFO
checFaceSanity và checFaceLiveness được viết thiếu chữ k thứ hai trong source của SDK. Hãy dùng đúng như vậy — đây là tên phương thức thật sự, không phải lỗi gõ trong tài liệu này.
Chèn view tùy chỉnh
scanNID nhận một CakeNIDScanInjectElements để bạn có thể thay thế giao diện mặc định.
| Trường | Kiểu | Mô tả |
|---|---|---|
scanView | CakeNIDScanView | Triển khai render, presentAccessingResult, startCamera, stopCamera. |
assessor | NIDAssessor | Triển khai execute(input): NIDAssessingResult. |
confirmationView | CakeNIDPreview | Triển khai show, hide, onConfirm, onRetry. |
Cùng mẫu hình này áp dụng cho scan khuôn mặt qua CakeFaceScanView và FaceAssessor.
Bước tiếp theo
- Tài liệu tham chiếu Web SDK — bề mặt API công khai
- Tích hợp Web SDK — thiết lập và scan