JavaScript Bridge

Đọc chip CCCD từ một trang web chạy trong WebView của Android hoặc iOS. SDK native inject một object CESJsBridge vào trang; JavaScript của bạn gọi nó và lớp native thực hiện thao tác NFC. Phiên bản 1.0.8.

Cách hoạt động

Trang web không thể truy cập trực tiếp phần cứng NFC. Ứng dụng host nhúng CICReader native SDK, đăng ký một JavaScript interface trên WebView của nó, và trang gọi thông qua bridge đó.

Trang web  →  CESJsBridge  →  CICReader native SDK  →  Chip CCCD

CESJsBridge được inject khi trang tải lần đầu, nên hãy đợi callback báo trang đã tải xong trước khi gọi nó.

INFO

Bridge chỉ trả về dữ liệu chip thô — com, sod, dg1, dg2, dg13, dg14, dg15 và cloneStatus. Nó không trả về các trường thông tin công dân đã phân tích hay verificationKey. Gửi các data group đến Đọc NFC từ backend của bạn để lấy các thông tin đó.

Đọc chip

Dùng MRZ — số CCCD 9 chữ số, ngày sinh, ngày hết hạn

async function submitForm() {
  const idCard = document.getElementById("idcard").value;
  const dob = document.getElementById("dob").value;
  const exp = document.getElementById("exp").value;

  const result = await CESJsBridge.readNfc(idCard, dob, exp)
    .catch((reason) => { console.log("failed reason: ", reason); });
}

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
idCard	string	Có	—	9 chữ số cuối của số CCCD.
dob	string	Có	—	Ngày sinh, định dạng yyMMdd.
exp	string	Có	—	Ngày hết hạn của thẻ, định dạng yyMMdd.

Dùng CAN — số CCCD 12 chữ số

async function submitForm() {
  const idCard = document.getElementById("idcard").value;
  const result = await CESJsBridge.readNfc(idCard)
    .catch((reason) => { console.log("failed reason: ", reason); });
}

Tham số	Kiểu	Bắt buộc	Mặc định	Mô tả
idCard	string	Có	—	Số CCCD đầy đủ 12 chữ số.

Cùng một tên phương thức nhận một hoặc ba tham số — bridge chọn phương án dựa trên số lượng tham số truyền vào.

Kết quả

Trường	Kiểu	Mô tả
com	string	Thông tin phiên bản Unicode và danh sách các data group hiện có. Base64.
sod	string	Dữ liệu SOD từ lần quét NFC. Base64.
dg1	string	Thông tin cơ bản của cá nhân — thông tin MRZ. Base64.
dg2	string	Ảnh khuôn mặt công dân đã mã hóa. Base64.
dg13	string	Thông tin liên quan đến công dân. Base64.
dg14	string	Dùng cho cơ chế truy cập EAC. Base64.
dg15	string	Public key, dùng cho Passive Authentication. Base64.
cloneStatus	int	0 chưa kiểm tra · 1 hợp lệ · 2 cảnh báo · 8 lỗi.

Lưu ý ở đây cloneStatus là một số nguyên, không phải enum như các SDK native trả về.

Lỗi

Các rejection mang theo { code, message }:

{ code: 600032, message: "NFC is not supported on this device" }

Trường	Kiểu	Mô tả
NfcNotAvailable	600103	Thiết bị không hỗ trợ NFC.
NFCNotSupported	600032	NFC không được hỗ trợ trên thiết bị này.
SessionOnGoing	600101	Một phiên đọc khác đang diễn ra.
SystemResourceUnavailable	600102	Hệ thống NFC đang bận.
UserCancelled	3	Người dùng đã hủy.
Unspecified	-1	Lỗi không mong đợi.

Bảng đầy đủ nằm ở Mã lỗi.

Hàm dựng sẵn

async function checkNfcAvailability() {
  const result = await CESJsBridge.isNfcAvailable();
}

async function checkNfcEnable() {          // Chỉ Android
  const result = await CESJsBridge.isNfcEnable();
}

async function openNfcSetting() {          // Chỉ Android
  await CESJsBridge.openNfcSetting();
}

Thiết lập ứng dụng host

WARNING

Bridge trả dữ liệu chip thô cho bất kỳ trang nào đang được tải trong WebView. Chỉ tải các origin HTTPS của chính bạn, chặn điều hướng sang origin khác, và kiểm tra origin của trang trong native interface trước khi đọc chip.

Android

allprojects {
    repositories {
        maven { url "https://maven.google.com" }
        maven { url "https://jcenter.bintray.com" }
        maven { url "path/to/cic_reader" }
    }
}

dependencies {
    implementation("vn.cake:cic-reader:1.x.x")
}

val jsInterface = CICJsInterface(activity, object : JavascriptEvaluator {
    override fun execute(jsFunc: String) {
        webView.evaluateJavascript(jsFunc) {}
    }
})
webView.addJavascriptInterface(jsInterface, CICJsInterface.JS_KEY)
webView.webViewClient = object : WebViewClient() {
    override fun onPageFinished(view: WebView?, url: String?) {
        super.onPageFinished(view, url)
        jsInterface.pageLoaded()   // gọi hàm này khi trang tải xong
    }
}

INFO

Artefact Android cho bridge là vn.cake:cic-reader, trong khi Android SDK độc lập dùng vn.cake.ekyc.sdk:eid. Hãy kiểm tra coordinate nào build của bạn đang cần.

iOS

let jsInterface = CESNfcJsInterface()
wk.configuration.userContentController.addJavascriptInterface(jsInterface, forKey: CESNfcJsInterface.kJsKey)
jsInterface.delegate = self

// WKWebView — khi trang tải xong
func webView(_: WKWebView, didFinish _: WKNavigation!) {
    jsInterface.pageLoaded()
}

@objc func onJavascriptEvaluate(script: String) {
    webView.evaluateJavaScript(script)
}

iOS cũng cần capability NFC, key NFCReaderUsageDescription và ba ISO7816 identifier — xem Tích hợp iOS SDK.

Flutter

Dùng trực tiếp Flutter plugin thay vì bridge.

Bước tiếp theo

• Đọc NFC — gửi các data group mà bridge trả về
• Mã lỗi — bảng lỗi đầy đủ
• Tổng quan Mobile SDK — các khái niệm dùng chung giữa các nền tảng