Active Liveness Android SDK with Token Submission (Advance Implementation)
This SDK version update will be not supported in June 2022, please move to the latest update on version 0.6.1, and retrieve the SDK file on the changelog page). Please refers to the new documentation.
By using the token integration step, you still need to access our API to get the result. It offers you some benefits on the security layer, such as:
  1. 1.
    You can save your access key and secret key information on your backend instead of in mobile/frontend, so that reduces the risk of leaking the key.
  2. 2.
    To get verification results, the mechanism incorporates token validation and backend to backend interactions to minimize the risk of interception between mobile/frontend and backend.

Getting Started

Supported API Level

The SDK support API level 21 and above (maximum API level 30).

Get Access Key

Before starting integration, you will need API access_key and secret_key . You can get the access_key and secret_key on your application dashboard, please visit dashboard.identifai.id/application.

API Sequence

API sequence to performing liveness check on SDK
  1. 1.
    The end-user initiates the liveness verification through the app, then the client mobile will trigger the need for a submission token to perform the liveness check.
  2. 2.
    Client backend invokes a request for generating a one-time submission token.
  3. 3.
    Nodeflux backend will validate the HMAC authorization (check here for HMAC authorization) and return a submission token to the client backend.
  4. 4.
    The client backend returns the submission token to the client mobile which will perform the SDK. The submission token will expire in 5 minutes.
  5. 5.
    After getting the submission token, SDK will perform a request job to activate the liveness activity.
  6. 6.
    After performing the liveness check, the Nodeflux backend will return a job_id.
  7. 7.
    To get the job result, the client requests GET job_id to get liveness status from the mobile to be triggered to the client backend.
  8. 8.
    The client backend invokes the GET result request by job_id to the Nodeflux backend.
  9. 9.
    The Nodeflux backend returns status and the liveness result to the client backend.

Prepare the SDK Library

To get the SDK Library, please contact our admin. After you get the .arr file, then copy the .arr file to the app/libs.

Obtain Submission Token

Request Header:
Parameter
Value
Authorization
HMAC token
x-nodeflux-timestamp
your x-nodeflux-timestamp
Request Body: null
Then you will get a response:
{
"ok": true,
"submission_token": "9268e8f3-1c2e-4b39-8604-61fe30a29908-GXYDEMJNGA4S2MRS"
}

Configure the Submission Token on The Mobile

Go to MainActivity code to configure the Android Activity. Ensure the activity is granted with camera permission because the Face Liveness SDK needs to capture the face. You need to update your submission token during performing the liveness check. Please check the example snippet below for submission token configuration:
Java
@Override
protected void onCreate(Bundle savedInstanceState) {
super.onCreate(savedInstanceState);
setContentView(R.layout.activity_main);
intent = new Intent(MainActivity.this, Liveness.class);
intent.putExtra("SUBMISSION_TOKEN", "{YOUR_SUBMISSION_TOKEN}");
intent.putExtra("THRESHOLD", "{THRESHOLD_HERE}");
Liveness.setUpListener(new Liveness.LivenessCallback() {
@Override
public void onSuccess(boolean isLive, Bitmap bitmap, double score) {
// unused method when using submission token on liveness SDK
}
@Override
public void onSuccessWithSubmissionToken(String jobID, Bitmap bitmap) {
//in this part you get your job_id status, result, and dumping your bitmap.
//for example: getJobStatus(jobID, submissionToken);
}
@Override
public void onError(String message) {
}
});
Where:
  • SUBMISSION_TOKEN: the generate submission token.
  • THRESHOLD: the value defined by the user to determine the verification is true or false. The value requires a double type, for example 0.6, the Default value is 0.7
  • jobID: job_id for checking the result, you can GET the result through your backend.
  • bitmap: return an image with bitmap type.
  • isLive: boolean type to return face liveness check is true or false. You can get this value if used basic implementation.
  • message: return an error message.
  • score : return liveness score on a double type from 0 to 1
To check the result you can use the livenessCallback method onSuccess and onError.

Get Verification Result

Send GET request to get liveness result to endpoint:
To get the authorization for the submission token please check the documentation link below: https://docs.identifai.id/api-documentation/authorization-using-submission-token
Request Header:
Headers Parameter
Value
Authorization
Your submission token
you will get a result response:
{
"job": {
"id": "22cb223e9cc2fa2c6bfad0526119827e71be1b6de5123b7fGIYDEMJNGA4S2MRS",
"result": {
"status": "success",
"analytic_type": "FACE_LIVENESS",
"result": [
{
"face_liveness": {
"live": true,
"liveness": 0.7660550475120544
}
}
]
}
},
"message": "Face Liveness Success",
"ok": true
}
Tips:
To get liveness results, we suggest creating a request pooling to ensure the backend can get the result because it is performing async API.

Get Error Result

Error because no face is detected

{
"job": {
"id": "<job_id>",
"result": {
"status": "incompleted",
"analytic_type": "FACE_LIVENESS",
"result": []
}
},
"message": "No face detected",
"ok": true
}

Error because the face is occluded

{
"job": {
"id": "<job_id>",
"result": {
"status": "incompleted",
"analytic_type": "FACE_LIVENESS",
"result": []
}
},
"message": "the face is most likely occluded",
"ok": true
}

Error because multiple faces are detected

{
"job": {
"id": "<job_id>",
"result": {
"status": "incompleted",
"analytic_type": "FACE_LIVENESS",
"result": []
}
},
"message": "Multiple faces are detected",
"ok": true
}