Android SDK Integration

Integration guide for the CICReader Android SDK, version 1.0.6. Written in Kotlin; the entry point is CICReadSDK.

Build Specifications

What	Description
Kotlin	1.7.10
minSdkVersion	21

Integration

Extract cic-reader-*.zip to a location you can reference — the root project, a local Maven repo, or similar.

allprojects {
    repositories {
        maven { url "https://maven.google.com" }
        maven { url "https://jcenter.bintray.com" }
        maven { url "path/to/cic_reader" }  // Example: maven { url "${project.rootDir}/repo" }
    }
}

dependencies {
    implementation("vn.cake.ekyc.sdk:eid:1.x.x")
}

Initialize

val config = CICConfig(
    "<BASE_URL>",
    true,
    60000,
    60000,
)

CICReadSDK.initialize(
    this,
    config,
    CICHeaderProvider {
        mapOf(
            "custom_header1" to "value1"
        )
    }
)

Parameters:

Param	Type	Required	Default	Description
baseUrl	string	Yes	—	Base URL for API calls.
enableCheckNfcData	bool	No	true	Verify NFC data against Cake RAR.
readTimeout	int	No	60000	API read timeout in milliseconds.
writeTimeout	int	No	60000	API write timeout in milliseconds.
cacheScanStrategy	CICCacheScanStrategy	No	NO_CACHE	See Mobile SDK Overview § Cache on Server Errors.

Read the Chip

Using MRZ — 9-digit ID, date of birth, expiry date

Throws IllegalMRZException when any input is wrong.

class MainActivity : AppCompatActivity(), CICReadCallback {
    fun readCICData() {
        cicReader.readCICData(this,
            "xxxxxxxxx",  // last 9 digits of the NID
            "901212",     // date of birth, yyMMdd
            "301212",     // expiry date, yyMMdd
            "<ACCESS_TOKEN>",
            "ref_00000001",
            this)
    }

    override fun onResult(result: CICReadResult) {
        // Send the result to your backend; never log it — it holds chip data and the verification key.
    }

    override fun onError(exception: CICException?) {
        Log.d("CICReader", exception)
    }

    override fun onCancel() {
        Log.d("CICReader", "on user cancel")
    }
}

Param	Type	Required	Default	Description
activity	Activity	Yes	—	The current activity.
idCard	string	Yes	—	The last 9 digits of the NID number.
dayOfBirth	string	Yes	—	Date of birth, format yyMMdd.
expiryDate	string	Yes	—	Card expiry date, format yyMMdd.
accessToken	string	Yes	—	Request access token.
refId	string	Yes	—	Transaction reference ID to verify.

Using CAN — 12-digit ID number

cicReader.readCICData(this,
    "001xxxxxxxxx",  // full 12-digit NID number
    "<ACCESS_TOKEN>",
    "ref_00000001",
    this)

Param	Type	Required	Default	Description
activity	Activity	Yes	—	The current activity.
idCard	string	Yes	—	The full 12-digit NID number.
accessToken	string	Yes	—	Request access token.
refId	string	Yes	—	Transaction reference ID to verify.

Result

CICReadResult carries the raw data groups plus, when enableCheckNfcData is true, the parsed citizen fields.

Chip data

Field	Type	Description
com	string	Unicode version info and the list of available data groups. Base64.
sod	string	The SOD data from the NFC scan. Base64.
dg1	string	Individual basic details — MRZ information. Base64.
dg2	string	Citizen facial image encoding. Base64.
dg13	string	Citizen-related information. Base64.
dg14	string	Used for the EAC access mechanism. Base64.
dg15	string	Public key, used for Passive Authentication. Base64.
cloneStatus	VerificationStatus	Clone status of the card. See Mobile SDK Overview § Clone Status.

Citizen fields — API derived

Field	Type	Description
idCardNo	string	Identification number of the citizen.
oldIdCardNumber	string	Old identification number.
fullName	string	Full name.
dateOfBirth	string	Date of birth.
dateOfExpiry	string	Card expiry date.
gender	string	Gender.
nationality	string	Nationality.
ethnic	string	Ethnicity.
religion	string	Religion.
placeOfOrigin	string	Place of origin.
residenceAddress	string	Place of residence.
personalSpecificIdentification	string	Personal identification characteristics.
dateOfIssuance	string	Date the card was issued.
fatherName	string	Father's name.
motherName	string	Mother's name.
spouseName	string	Partner's name.
faceImage	string	Facial image. Base64.
isVerified	bool	Whether the card was verified by RAR.
verificationKey	string	Verification key — pass this to Verify NFC.
requestId	string	Request ID of the authentication.

Error Handling

override fun onError(exception: CICException?) {
    Log.w("CICReader", exception)

    when (exception) {
        is CICException.ServerError -> { }
        is CICException.NetworkError -> { }
        // ....
    }
}

Field	Type	Description
IllegalMRZException	600316	Illegal MRZ information detected.
IllegalCanException	600317	Illegal CAN information detected.
EstablishMessageChannelFailedException	600333	Establishing the PACE message channel failed.
NfcNotAvailableException	600032	NFC is not available.
UnexpectedException	600503	An unexpected exception occurred.
ReadingDataFailedException	600666	Reading data from the NID failed.
NetworkError	601400	A network error occurred.
ServerError	601503	A server error occurred.
UnauthorizedError	601404	The user is unauthorized to access the resource.
NotFoundError	601408	The requested resource was not found.
ApiError	601401	An error came back from the API.
InvalidCardType	600396	The scanned card is not an NID.

Built-in Functions

Field	Type	Description
isNFCAvailable(context)	bool	Whether NFC reading is available on the device.
isNfcEnable(context)	bool	Whether NFC is switched on.
openNfcSetting(activity)	void	Opens the device NFC settings screen.

Next Steps

• Android SDK UI Customization — restyle the scanner screen
• Verify NFC — redeem the verificationKey from your backend
• Mobile SDK Overview — concepts shared across platforms