# Android eKYC Base SDK Docs

###### tags: `docs` `sdk` `ekyc` `android`

## Installation

Here is the steps attach our SDK:

1. In `build.gradle(Project)`, add

buildscript {
    ...
    dependencies {
        ...
        classpath 'com.google.gms:google-services:4.3.3'
    }
}

allprojects {
    repositories {
        ...
        maven {
            url  "https://dl.bintray.com/wiseai/maven"
        }
    }
}

2. In `build.gradle(app)`, add

apply plugin: 'com.google.gms.google-services'

android {
    ...
    
    defaultConfig {
        ...
        multiDexEnabled true
    }
    
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    ...
    implementation 'com.wiseai.ekyc:app:(insert latest version)'
    
    // for converting string result to json
    implementation 'com.google.code.gson:gson:2.8.6'
    
    // Low Memory Support, required for Android API < 5.0
    implementation 'com.android.support:multidex:1.0.3'
}

3. Include your `Google-service.json` into your `/Project/app`
5. Setup your Android Studio Ndk Environment
6. Done! Congratulation you have integrated the SDK!

## Getting Start

To use the Android SDK you must initialize the SDK to include your API token and API endpoint. The API token is a unique identifier that is used to authenticate API. If you do not have a API token, please leave an enquiry to us in email.

To initialize the SDK:

...
@Override
protected void onCreate(@Nullable Bundle savedInstanceState) {
    super.onCreate(savedInstanceState);
    
    // Initialize the SDK with your token & url endpoint.
    // If you does not have the token, please request it with us.
    wiseAiApp = new WiseAiApp();
    wiseAiApp.init(this, "YOUR_TOKEN_STRING", "URL_ENDPOINT");
    ...
}

To start a new application, the server will need to request a session id to identify the same application. Therefore whenever apply a new application, please start a new session.

To start a new session:

public void performMyKadOcr() {
    // Request a new session for a new application
    WiseAiApp.startNewSession();

    // Start a MyKadOcr API
    Intent intent = new Intent(this, MyKadOcr.class);
    startActivityForResult(intent, ACTIVITY_MYKAD_OCR);
}

*Please note, a session will be expired in 30 minutes.*
*If a session is expired, a error message will be returned whenever the application is submitted to our server.*

## eKYC Activity

An eKYC activty will start an eKYC(Electronic Know Your Customer) process to collect user's information. This process including:

1. MyKad Front Capturing
2. MyKad Back Capturing
3. Liveness Capturing

In the end of process, the user will json string result which includes identity information and validation results:

1. Identity information
2. Identity validation result
3. Face liveness result
4. Face matching result

To run this activity:

public void performEkyc() {
    // 0. Please ensure the SDK is initialize at this point.

    // 1. Start a new session
    WiseAiApp.startNewSession();

    // 2. Create a new eKYC activity
    Intent intent = new Intent(this, Ekyc.class);
    
    // 3. Insert config here
    intent.putExtra("MYKAD_AUTO", true);
    
    // 4. Launch your intent here
    startActivityForResult(intent, ACTIVITY_EKYC);
}

To get result:

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    
    if (requestCode == ACTIVITY_EKYC) {

        if (resultCode == Activity.RESULT_OK) {

            // 1. Get result from WiseAiApp
            String result = WiseAiApp.getResult();

            // 2. Parse string to JsonObject
            // Note: JsonObject is from Google Gson Library
            JsonObject jsonObject = JsonParser.parseString(result).getAsJsonObject();

            // 3. Process result
            if (jsonObject.has("status") && jsonObject.get("status").getAsString().equals("error")) {

                // 3.1 if error, get the error message
                String code = jsonObject.get("code").getAsString();
                String message = jsonObject.get("message").getAsString();

                Log.d("Error", message);

            } else {

                // 3.2 Get each result from jsonObject
                JsonObject mykadFront = jsonObject.get("mykadFront").getAsJsonObject();
                JsonObject mykadBack = jsonObject.get("mykadBack").getAsJsonObject();
                JsonObject matchingResult = jsonObject.get("matchingResult").getAsJsonObject();
                JsonObject livenessResult = jsonObject.get("livenessResult").getAsJsonObject();

                // 3.3 Get MyKad Front Result
                String status = mykadFront.get("status").getAsString();
                if (status.equals("success")) {

                    // If succeed, get its result from 'data'
                    JsonObject resultData = mykadFront.get("data").getAsJsonObject();

                    // proceed with succeed result here
                    ...
                }
            }
            
        } else {
        
            // 4. if the user cancelled his action, or unexpected error
            String status = null;
            if (data != null)
                status = data.getStringExtra("STATUS");

            if (Objects.equals(status, "CANCELLED")) {
                Log.d("Cancelled", "Action cancelled");
            } else {
                Log.e(TAG, "Something is wrong here.");
            }
        }
    }
}

Configuration:
- `MYKAD_AUTO` - toggle MyKad Capturing to Auto Capture
- `FACE_AUTO` - toggle Face Liveness Capturing to Auto Capture

Sample output:

{
    "mykadFront": {
        "status": "success",
        "message": "Success",
        "data": {
            "type": "FRONT",
            "documentImageBase64": "",
            "icNumber": "851110-56-6111",
            "birthDate": {
                "day": 10,
                "month": 11,
                "year": 1985,
                "originalString": "851110"
            },
            "name": "LEE AH MING",
            "street": "NO 22\nJALAN 11A\nTAMAN BUKIT XXXX",
            "city": "KAJANG",
            "state": "SELANGOR",
            "zipCode": "43000",
            "fullAddress": "NO 22\nJALAN 11A\nTAMAN BUKIT XXXX 9\n43000 KAJANG\nSELANGOR",
            "faceImageBase64": "",
            "religion": "",
            "gender": "M",
            "landmarks": {
                "kadPengenalanMalaysiaLandmark": 99.91,
                "securityChip": 99.97,
                "mscLogo": 99.93,
                "ghostImage": 99.99,
                "gender": 99.89,
                "religion": 0.14,
                "citizen": 99.93,
                "name": 99.91,
                "malaysiaFlag": 99.86,
                "address": 99.97,
                "hibiscusLogo": 99.92,
                "facialImage": 100.0,
                "mykadLogo": 99.98,
                "mykadNumber": 99.91
            },
            "ocrScores": {
                "icNumber": {
                    "score": 97.07,
                    "glare": false
                },
                "name": {
                    "score": 92.3,
                    "glare": false
                },
                "address": {
                    "score": 97.24,
                    "glare": false
                },
                "religion": {
                    "score": 0.0,
                    "glare": false
                },
                "gender": {
                    "score": 97.15,
                    "glare": false
                }
            }
        },
        "meta": {
            "reqTs": 1600053733897,
            "respTs": 1600053735157,
            "reqId": "62929434-5243-45b8-aa9e-cd22ee7e78e4"
        }
    },
    "mykadBack": {
        "status": "success",
        "code": "SUCCESS",
        "message": "Success",
        "data": {
            "type": "BACK",
            "documentImageBase64":
            "landmarks": {
                "coatOfArmLandmark": 100.0,
                "klccTower": 100.0,
                "signature": 99.99,
                "kingCrown": 99.99,
                "ketuaPengarahPendaftaranNegara": 99.98,
                "myKadNumber": 99.96,
                "tngLogo": 99.98,
                "atmLogo": 0.04,
                "chipLogo": 99.97,
                "serialNum": 99.85
            }
        },
        "meta": {
            "reqTs": 1600053736307,
            "respTs": 1600053737265,
            "reqId": "4be3900c-fea2-4a01-90f9-e50e7d0bb004"
        }
    },
    "matchingResult": {
        "status": "success",
        "code": "SUCCESS",
        "message": "",
        "data": {
            "confidence": 78.1,
            "mykadVsFaceConfidence": 78.1
        },
        "meta": {
            "reqTs": 1600153542496,
            "respTs": 1600153544206,
            "reqId": "1e6403fc-c22b-48cd-8b2e-17532795c0c9"
        }
    },
    "livenessResult": {
        "status": "success",
        "code": "SUCCESS",
        "data": {
            "livenessDetected": true
        },
        "meta": {
            "reqTs": 1600153546155,
            "respTs": 1600153551634,
            "reqId": "19bb130d-ee71-4189-9623-31f4c0e13c6c"
        },
        "videoPath": "/storage/emulated/0/Android/data/usd.my.wisepass.demo/files/video.mp4"
    }
}

Sample Error Output:

{
    "status": "error",
    "code": "OCR_ERROR",
    "message": "Failed to perform OCR.",
    "meta": {
        "reqTs": 1600153497052,
        "respTs": 1600153497951,
        "reqId": "3f81fcb0-79f5-417f-bc78-4e65f8a6da21"
    }
}

## Appendix

### Classes

**WiseAiApp**
- To initialize WiseAI Base SDK
- Get OCR/FR result
- Methods:

_

`init(Context, String)`

*Description*
Initialize your app with your token.

**_Note: Please perform this action before using the application._**

_Parameters_
|Parameter|Type|Description|
|---|---|---|
|`context`| Context| Activity context|
|`token`| String | token generated from WiseAI|

_

`startNewSession()`

*Description*
To request a new session which alive for 30mins.

**_Note: Please perform this action before every new eKYC flow._**

_

`getResult()`

*Description*
get the output result with Json format.

*Output*
- json Result

---

### Activity Classes

#### eKYC Flow

**Ekyc**

_Description_
Upon calling, this activity will initial eKYC process, from `MyKad Front Capturing`, `MyKad Back Capturing` to `Face Liveness + Matching Capturing`.

*Prerequisite*
- initialized the WiseAiApp.

*Parameters (bundle/extra)*
|Parameter|Description|
|---|---|
|`MYKAD_AUTO`|toggle MyKad Capturing to Auto Capture|
|`FACE_AUTO`|toggle Face Liveness Capturing to Auto Capture|
|`EXPORT_FACE`|toggle to receive MyKad face image in `faceImageBase64`|

*Output*
- Json Result

---

#### Optical Character Recognition

**MyKadOcr**

_Description_
Upon calling, this activity will initiate device's camera to capture MyKad Front & Back accordingly.

*Prerequisite*
- initialized the WiseAiApp
- request new session id

*Parameters (bundle/extra)*
|Parameter|Description|
|---|---|
|`SINGLE_SHOT`| to perform 1 side mykad capture, use with `IS_FRONT`|
|`IS_FRONT`|to set whether taking front mykad or back mykad|
|`AUTO_CAPTURE`|to toggle mykad auto detection|
|`EXPORT_FACE`|toggle to receive MyKad face image in `faceImageBase64`|

*Output*
- Json Result

*Sample Output*

<details>
<summary>Mykad Single (Front) Output</summary>

{
    "status": "success",
    "message": "Success",
    "data": {
        "type": "FRONT",
        "documentImageBase64": "",
        "icNumber": "851110-56-6111",
        "birthDate": {
            "day": 10,
            "month": 11,
            "year": 1985,
            "originalString": "851110"
        },
        "name": "LEE AH MING",
        "street": "NO 22\nJALAN 11A\nTAMAN BUKIT XXXX",
        "city": "KAJANG",
        "state": "SELANGOR",
        "zipCode": "43000",
        "fullAddress": "NO 22\nJALAN 11A\nTAMAN BUKIT XXXX 9\n43000 KAJANG\nSELANGOR",
        "faceImageBase64": "",
        "religion": "",
        "gender": "M",
        "landmarks": {
            "kadPengenalanMalaysiaLandmark": 99.93,
            "securityChip": 99.98,
            "mscLogo": 99.87,
            "ghostImage": 100.0,
            "gender": 99.89,
            "religion": 0.17,
            "citizen": 99.92,
            "name": 99.88,
            "malaysiaFlag": 99.85,
            "address": 99.97,
            "hibiscusLogo": 99.92,
            "facialImage": 100.0,
            "mykadLogo": 99.97,
            "mykadNumber": 99.92
        },
        "ocrScores": {
            "icNumber": {
                "score": 97.75,
                "glare": false
            },
            "name": {
                "score": 95.93,
                "glare": false
            },
            "address": {
                "score": 97.65,
                "glare": false
            },
            "religion": {
                "score": 0.0,
                "glare": false
            },
            "gender": {
                "score": 87.63,
                "glare": false
            }
        }
    },
    "meta": {
        "reqTs": 1600152993231,
        "respTs": 1600152994621,
        "reqId": "12322a19-1a7a-4327-b297-7b861a366d05"
    },
    "imageBase64": 
}

</details>

<details>
<summary>Mykad Single (Back) Output</summary>

{
	"status": "success",
	"code": "SUCCESS",
	"message": "Success",
	"data": {
		"type": "BACK",
		"documentImageBase64": 
		"landmarks": {
			"coatOfArmLandmark": 100.0,
			"klccTower": 100.0,
			"signature": 99.99,
			"kingCrown": 99.99,
			"ketuaPengarahPendaftaranNegara": 99.98,
			"myKadNumber": 99.96,
			"tngLogo": 99.98,
			"atmLogo": 0.04,
			"chipLogo": 99.97,
			"serialNum": 99.85
		}
	},
	"meta": {
		"reqTs": 1600053736307,
		"respTs": 1600053737265,
		"reqId": "4be3900c-fea2-4a01-90f9-e50e7d0bb004"
	},
    "imageBase64": 
}

</details>

<details>
<summary>Mykad Full result</summary>

{
    "mykadFront": {
        ...
    },
    "mykadBack": {
        ...
    }
}

</details>

<details>
<summary>Error result</summary>

{
    "status": "error",
    "code": "OCR_ERROR",
    "message": "Failed to perform OCR.",
    "meta": {
        "reqTs": 1600153497052,
        "respTs": 1600153497951,
        "reqId": "3f81fcb0-79f5-417f-bc78-4e65f8a6da21"
    }
}

</details>

---

### Facial Analyse

**FaceMatch**

_Description_
Upon calling, this activity will initiate device's camera to capture Face Image for Face Matching.

***Note***: This intend contains only face capturing. Therefore, before capturing using `FaceMatch`, a MyKad Front Capturing should be ran previously to run face compare.

*Prerequisite*
- initialized the WiseAiApp.
- a successful MyKad Front Capture.
- an unexpired session from MyKad Front Capture (30 mins)

*Output*
- Json Result

---

**FaceLiveness**

_Description_
Upon calling, this activity will initiate device's camera to capture Face Liveness in video format.

*Prerequisite*
- initialized the WiseAiApp.
- an unexpired session (30 mins)

*Output*
- Json Result

---

**FaceLivenessMatching**

_Description_
Upon calling, this activity will initiate device's camera to capture Face Liveness in video format & do Face Match in the middle of recording.

*Prerequisite*
- initialized the WiseAiApp.
- a successful MyKad Front Capture.
- an unexpired session from MyKad Front Capture (30 mins)

*Output*
- Json Result

---

**FaceLivenessMatchingAuto**

_Description_
Upon calling, this activity will initiate device's camera to capture Face Liveness in video format & do Face Match in the middle of recording. The recording process is automatic.

*Prerequisite*
- initialized the WiseAiApp.
- a successful MyKad Front Capture.
- an unexpired session from MyKad Front Capture (30 mins)

*Output*
- Json Result

*Sample Output*
<details>
<summary>Matching Result</summary>

{
    "status": "success",
    "code": "SUCCESS",
    "message": "",
    "data": {
        "confidence": 78.1,
        "mykadVsFaceConfidence": 78.1
    },
    "meta": {
        "reqTs": 1600153542496,
        "respTs": 1600153544206,
        "reqId": "1e6403fc-c22b-48cd-8b2e-17532795c0c9"
    }
}

</details>

<details>
<summary>Liveness Result</summary>

{
    "status": "success",
    "code": "SUCCESS",
    "data": {
        "livenessDetected": true
    },
    "meta": {
        "reqTs": 1600153546155,
        "respTs": 1600153551634,
        "reqId": "19bb130d-ee71-4189-9623-31f4c0e13c6c"
    },
    "videoPath": "/storage/emulated/0/Android/data/usd.my.wisepass.demo/files/video.mp4"
}

</details>

<details>
<summary>Matching + Liveness Result</summary>

{
    "matchingResult": {
        ...
    },
    "livenessResult": {
        ...
    }
}

</details>

<details>
<summary>Error Result</summary>

{
    "matchingResult": {
        ...
    },
    "livenessResult": {
        ...
    }
}

</details>

## Change Log

### 1.1.0

2020-11-04

- Fixed endpoint has been changed to flexible.
- Able to export MyKad face image.
- Minor bug fixed.

### 1.0.1

2020-09-30

- Documentation updated.
- Minor bug fixed.

### 1.0.0

2020-09-29

- First version released.