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

Mọi class, thuộc tính và phương thức công khai trong eKYC Android SDK. Xem Tích hợp Android SDK để biết hướng dẫn tích hợp.

CakeEkyc

class CakeEkyc — entry point của SDK.

Trường	Kiểu	Mô tả
upload(uploadImageRequest)	Result<EkycResponse<UploadImageResponseData>>	Tải một ảnh lên.
takeNID(activity, config, listener)	Unit	Chụp NID → tải lên → kiểm tra sanity → kiểm tra giả mạo → trích xuất thông tin. Khi thất bại, pipeline dừng lại và listener.onError được gọi; ngược lại listener.onSuccess nhận một NIDCardResult.
checkNIDSanity(imageId, imageId2, cardType, specialTypeId)	Result<EkycResponse<NIDSanityData>>	Kiểm tra sanity của ảnh NID.
checkNIDTampering(imageId, imageId2, cardType, level)	Result<EkycResponse<NIDTamperingData>>	Kiểm tra giả mạo trong ảnh NID.
readNIDInfo(imageId, imageId2, cardType)	Result<EkycResponse<NIDCardData>>	Trích xuất thông tin từ ảnh NID.
takeFaces(activity, config, listener)	Unit	Chụp khuôn mặt → tải lên → kiểm tra sanity → kiểm tra liveness. Trả về một SelfieResult.
checkFaceSanity(imageId)	Result<EkycResponse<FaceSanityData>>	Kiểm tra sanity của một ảnh khuôn mặt.
checkLiveness(imageIds)	Result<EkycResponse<FaceLivenessData>>	Kiểm tra liveness của ảnh khuôn mặt.
compareFaces(imageId1, imageId2)	Result<EkycResponse<FaceComparedData>>	So sánh hai ảnh khuôn mặt.
close()	Unit	Kết thúc các tác vụ chụp NID và khuôn mặt đang diễn ra.
getInstance(context, config, executor)	static Future<CakeEkyc>	Tạo một instance CakeEkyc một cách bất đồng bộ.
start(activity, pipeline)	static Unit	Bắt đầu quy trình eKYC với pipeline được cung cấp.
start(fromPackage, fromActivity, hostActivityFullClassName, pipeline, args)	static Unit	Bắt đầu eKYC từ một package và activity class cụ thể.
start<T : EkycActivity>(activity, pipeline, hostActivityClass, args)	static Unit	Bắt đầu eKYC với một activity class generic.
start(from, intent, pipeline)	static Unit	Bắt đầu eKYC với một intent tùy chỉnh.
start(activity, fragmentContainerViewId, pipeline)	static Unit	Bắt đầu eKYC trong một fragment container.

Kết quả

NIDCardResult

data class NIDCardResult

Trường	Kiểu	Mô tả
cardType	CardType	Loại thẻ NID (CCCD).
frontSideImage	EkycImage?	Mặt trước của thẻ NID.
backSideImage	EkycImage?	Mặt sau của thẻ NID.
qrData	QRData?	Dữ liệu mã QR của NID.
sanityResult	EkycResponse<NIDSanityData>?	Kết quả kiểm tra sanity.
tamperingResult	EkycResponse<NIDTamperingData>?	Kết quả kiểm tra giả mạo.
cardInfo	EkycResponse<NIDCardData>?	Thông tin thẻ đã trích xuất — tên, số ID, ngày sinh, mrz.

NIDCardResult.QRData

Trường	Kiểu	Mô tả
raw	String?	Giá trị chuỗi thu được từ việc quét QR.
image	EkycImage?	Ảnh mã QR.

SelfieResult

data class SelfieResult

Trường	Kiểu	Mô tả
faces	List<Face>?	Các khuôn mặt đã chụp.
sanityResult	List<EkycResponse<FaceSanityData>>?	Response kiểm tra sanity cho từng ảnh khuôn mặt.
livenessResult	EkycResponse<FaceLivenessData>?	Kết quả kiểm tra liveness.

SelfieResult.Face

Trường	Kiểu	Mô tả
image	EkycImage?	Ảnh chân dung.
gesture	FaceGesture	Cử chỉ khuôn mặt: frontal, left, right, up, down.

Cấu hình

Config

data class Config

Trường	Kiểu	Mô tả
languageCode	String	vi cho tiếng Việt, en cho tiếng Anh.
baseUrl	String	Base URL cho các network request.
networkConfig	NetworkConfig	Thiết lập cấu hình mạng.
tokenProvider	TokenProvider?	Provider cung cấp authentication token.
logger	Logger?	Sink nhận log.

Config.Builder

Trường	Kiểu	Mô tả
withLanguage(languageCode)	Builder	Đặt languageCode.
withBaseUrl(baseUrl)	Builder	Đặt baseUrl.
withToken(tokenProvider)	Builder	Đặt tokenProvider.
withNetworkConfig(networkConfig)	Builder	Đặt networkConfig.
withLogger(logger)	Builder	Đặt logger.
build()	Config	Tạo Config.

NetworkConfig

Trường	Kiểu	Mô tả
readTimeoutMilliSeconds	Long	Timeout đọc, mặc định 0.
writeTimeoutMilliSeconds	Long	Timeout ghi, mặc định 0.
connectTimeoutMilliSeconds	Long	Timeout kết nối, mặc định 0.
callTimeoutMilliSeconds	Long	Tổng thời gian cho phép cho lệnh gọi, mặc định 60000.

TokenProvider

interface TokenProvider

Trường	Kiểu	Mô tả
getToken(timestamp, path, method)	String	Trả về một authentication token cho request đã cho.
from(authToken)	static TokenProvider	Tạo một provider từ một token tĩnh.

Logger

Trường	Kiểu	Mô tả
info(log)	Unit	Ghi log một thông báo thông tin.
error(log)	Unit	Ghi log một thông báo lỗi.
warning(log)	Unit	Ghi log một thông báo cảnh báo.

TakeNIDConfig

Trường	Kiểu	Mô tả
cardType	CardType	Loại thẻ cần chụp, mặc định CardType.CCCD.
cardSides	List<CardSide>	Các mặt cần chụp, mặc định [Front, Back].
requiredReview	Boolean	Yêu cầu xem lại ảnh đã chụp, mặc định true.
autoCaptureEnable	Boolean	Tự động chụp khi chất lượng đạt yêu cầu, mặc định true.
requiredScanQR	Boolean	Yêu cầu quét QR, mặc định false.
captureOnly	Boolean	Chế độ chỉ chụp, mặc định false.
loadingView	View?	Giao diện loading tùy chỉnh. Mặc định dùng của SDK.
otherSideImages	Map<CardSide, EkycImage>	Mặt còn lại đã được chụp trước đó.

TakeFaceConfig

Trường	Kiểu	Mô tả
captureOnly	Boolean	Chế độ chỉ chụp, mặc định false.
loadingView	View?	Giao diện loading tùy chỉnh.

Kiểu dữ liệu

EkycImage

Trường	Kiểu	Mô tả
id	String?	Định danh duy nhất sau khi tải lên server.
label	String?	Nhãn mô tả ảnh.
bitmap	Bitmap?	Dữ liệu ảnh.

EkycResponse

Trường	Kiểu	Mô tả
data	T?	Dữ liệu response.
error	List<EkycErrorDetail>?	Chi tiết lỗi, nếu có.
code	Int?	Status code của response.
message	String?	Thông báo của response.
signature	String?	Signature của response.
signatureTimestamp	String?	Timestamp của signature.
rawData	String?	Chuỗi dữ liệu thô.
request	String?	Request.
responseBody	String?	Response body thô.

EkycErrorDetail

Trường	Kiểu	Mô tả
code	String?	Mã lỗi.
message	String?	Mô tả lỗi.

CardType

Trường	Kiểu	Mô tả
id	String	Định danh loại thẻ, ví dụ vn.national_id.
name	String	Tên loại thẻ, ví dụ id_card.vn.national_id.
CCCD	static CardType	CCCD Việt Nam: id vn.national_id, name id_card.vn.national_id.

CardSide

sealed class CardSide — name phải là front hoặc back. Object lồng bên trong: Front, Back.

NIDSanityData

Trường	Kiểu	Mô tả
status	String?	success hoặc failure.
cardSanity	CardSanity?	Chi tiết sanity của thẻ.
image1	NIDImage?	Ảnh NID thứ nhất được sử dụng.
image2	NIDImage?	Ảnh NID thứ hai được sử dụng.
requestId	String?	Định danh request.

CardSanity

Trường	Kiểu	Mô tả
verdict	String?	good khi kiểm tra đạt. Xem Định nghĩa kết luận.
score	Double?	Điểm độ tin cậy.
info	String?	Thông tin bổ sung.

NIDTamperingData

Trường	Kiểu	Mô tả
status	String?	Trạng thái của kiểm tra giả mạo.
cardTampering	CardTampering?	Chi tiết kiểm tra giả mạo.
requestId	String?	Định danh request.
imageId	String?	Ảnh thứ nhất được sử dụng.
imageId2	String?	Ảnh thứ hai được sử dụng.

CardTampering

Trường	Kiểu	Mô tả
verdict	String?	good khi kiểm tra đạt.
score	Double?	Điểm độ tin cậy tổng thể.
details	List<TamperingDetail>?	Các tín hiệu giả mạo riêng lẻ.

TamperingDetail

Trường	Kiểu	Mô tả
verdict	String?	Kết luận giả mạo cụ thể.
score	Double?	Điểm độ tin cậy.
info	String?	Thông tin bổ sung.

NIDCardData

Trường	Kiểu	Mô tả
status	String?	Trạng thái trích xuất.
extractedDataOnImage1	ExtractedData?	Dữ liệu từ ảnh thứ nhất.
extractedDataOnImage2	ExtractedData?	Dữ liệu từ ảnh thứ hai.
cardInfo	List<CardInfo>?	Thông tin thẻ đã hợp nhất.
requestId	String?	Định danh request.

ExtractedData

Trường	Kiểu	Mô tả
id	String?	Định danh ảnh NID.
transformedImageId	String?	Định danh ảnh đã biến đổi.
cardBox	CardBox?	Bounding box của thẻ.
qr	QRData?	Dữ liệu mã QR.
ocr	OCRData?	Dữ liệu OCR.
mrzData	MRZData?	Dữ liệu MRZ.

QRData / OCRData / MRZData

Trường	Kiểu	Mô tả
parsedFields	List<ParsedField>?	Các trường đã phân tích từ nguồn này.
raw	String?	Giá trị thô. Chỉ có ở QRData.
confidenceScore	Double?	Độ tin cậy của lần trích xuất.

ParsedField

Trường	Kiểu	Mô tả
key	String?	Tên trường.
value	String?	Giá trị trường.
confidenceVerdict	String?	Kết luận độ tin cậy.
confidenceScore	Double?	Điểm độ tin cậy.

CardInfo

Trường	Kiểu	Mô tả
key	String?	Tên trường.
value	String?	Giá trị trường.
confidenceVerdict	String?	Kết luận độ tin cậy.
confidentScore	Double?	Điểm độ tin cậy.

CardBox / Point

Trường	Kiểu	Mô tả
topLeft topRight bottomLeft bottomRight	Point?	Các góc của bounding box thẻ.
x y	Double?	Tọa độ điểm.

FaceSanityData

Trường	Kiểu	Mô tả
status	String?	Trạng thái của kiểm tra sanity khuôn mặt.
portraitSanity	PortraitSanity?	Chi tiết sanity của ảnh chân dung.
requestId	String?	Định danh request.
image	PortraitImageInfo?	Thông tin ảnh chân dung.
isSanityPassed()	Boolean	True khi portraitSanity.verdict là good.

PortraitSanity

Trường	Kiểu	Mô tả
verdict	String?	Kết quả của kiểm tra sanity.
score	Double?	Điểm độ tin cậy.

FaceLivenessData

Trường	Kiểu	Mô tả
status	String?	Trạng thái của kiểm tra liveness.
isLive	Boolean?	Khuôn mặt có phải là live hay không.
score	Double?	Điểm độ tin cậy.
results	List<LivenessResult>?	Kết quả liveness theo từng ảnh.
requestId	String?	Định danh request.
mainImageId	String?	Ảnh chính được sử dụng.

LivenessResult

Trường	Kiểu	Mô tả
id	String?	Định danh ảnh.
isLive	Boolean?	Khuôn mặt này có phải là live hay không.
score	Double?	Điểm độ tin cậy.

FaceComparedData / ComparedResult

Trường	Kiểu	Mô tả
status	String?	Trạng thái so sánh.
comparedResults	List<ComparedResult>?	Kết quả so sánh.
face1Id face2Id	String?	ID của các ảnh khuôn mặt được so sánh.
score	Double?	Điểm tương đồng.
result	String?	matched hoặc not matched.

Listener và Event

NIDCapturingListener / FaceCapturingListener

Trường	Kiểu	Mô tả
onEvent(event)	Unit	Một sự kiện xảy ra trong lúc chụp.
onError(error)	Unit	Xảy ra lỗi.
onSuccess(result)	Unit	Chụp thành công — NIDCardResult hoặc SelfieResult.

EkycEvent

Trường	Kiểu	Mô tả
id	Int	Định danh sự kiện.
params	Map<String, Any>	Tham số sự kiện.
timestamp	Long	Thời điểm tạo, tính bằng mili-giây.
STEP_COMPLETE_EVENT	-1	Một bước đã hoàn tất.
STEP_RETRY_EVENT	-2	Một bước đang được thử lại.
STEP_EXITED_EVENT	-3	Một bước đã thoát.
STEP_ENTERED_EVENT	-4	Đã vào một bước.
TIME_OUT_EVENT	-1000	Xảy ra timeout.
FACE_SELFIE_ASSESSING_RESULT_EVENT	-1001	Kết quả đánh giá selfie khuôn mặt.
FACE_LIVENESS_ASSESSING_RESULT_EVENT	-1002	Kết quả đánh giá liveness khuôn mặt.
NID_ASSESSING_RESULT_EVENT	-1003	Kết quả đánh giá NID.
LIVENESS_RESULT_EVENT	-1004	Kết quả kiểm tra liveness.
ON_BACK_NAV_PRESSED_EVENT	-1005	Nhấn điều hướng back của thiết bị.
ON_CREATE_ACTIVITY_EVENT	-1006	Một activity đã được tạo.
ON_PERMISSION_NOT_GRANTED	-1007	Quyền chưa được cấp.
NID_CAPTURE_STARTED_EVENT	-1008	Bắt đầu chụp NID.
NID_CAPTURE_ENDED_EVENT	-1009	Kết thúc chụp NID.
NID_REVIEW_STARTED_EVENT	-1010	Bắt đầu xem lại NID.
ON_ID_SHUTTLE_CLICKED_EVENT	-1011	Nhấn nút chụp.
ON_ID_AUTO_CAPTURE_SELECTED_EVENT	-1012	Đã chọn tự động chụp.
NID_REVIEW_ENDED_EVENT	-1013	Kết thúc xem lại NID.
NID_REVIEW_ACCEPT_CLICKED_EVENT	-1014	Nhấn Accept trong lúc xem lại.
NID_REVIEW_DENY_CLICKED_EVENT	-1015	Nhấn Deny trong lúc xem lại.
FACE_CAPTURE_STARTED_EVENT	-1016	Bắt đầu chụp khuôn mặt.
FACE_CAPTURE_ENDED_EVENT	-1017	Kết thúc chụp khuôn mặt.
ON_BACK_BTN_CLICKED_EVENT	-1018	Nhấn nút back trên màn hình.

EkycEvent.Builder

Trường	Kiểu	Mô tả
setEventId(id)	Builder	Đặt id sự kiện.
addParams(params)	Builder	Thêm nhiều tham số.
addParam(key, value)	Builder	Thêm một tham số.
build()	EkycEvent	Tạo sự kiện.

EkycConstant

Các key dùng bên trong EkycEvent.params.

Trường	Kiểu	Mô tả
STEP_NAME_KEY	step_name	Tên bước.
SELFIE_IMAGES_KEY	selfie_images	Dữ liệu ảnh selfie.
ASSESSING_CODE_KEY	assessing_code	Mã đánh giá.
ASSESSING_MESSAGE_KEY	assessing_message	Thông báo đánh giá.
OFFSET_KEY	offset	Dữ liệu offset.
CARD_TYPE_KEY	card_type	Loại thẻ.
CARD_SIDE_KEY	card_side	Mặt thẻ.
AUTO_CAPTURE_KEY	auto_capture	Thiết lập tự động chụp.
TIMESTAMP_KEY	timestamp	Timestamp.

EkycError

sealed class EkycError : RuntimeException()

Trường	Kiểu	Mô tả
TIMEOUT_CODE	40000	Timeout.
USER_CANCEL_CODE	40001	Người dùng hủy.
PERMISSION_NOT_GRANTED_ERROR_CODE	40002	Từ chối cấp quyền.
CAMERA_ERROR_CODE	40003	Lỗi camera.
UNEXPECTED_ERROR_CODE	50000	Lỗi không mong đợi.
NID_SANITY_FAILED	60000	Lỗi sanity của NID.
NID_TAMPERING_FAILED	60001	Lỗi giả mạo của NID.
FACE_SANITY_FAILED	60002	Lỗi sanity khuôn mặt.
FACE_LIVENESS_FAILED	60003	Lỗi liveness khuôn mặt.

Object lồng bên trong: UserCanceledError, TimeoutError, PermissionNotGranted, CameraError, UnexpectedError, QualityFailed.

Bước tiếp theo

• Tích hợp Android SDK — hướng dẫn tích hợp
• Tổng quan Mobile SDK — các khái niệm dùng chung giữa các nền tảng