Skip to content

SmilePass Tutorials

Jump to bottom
mrajput-systango edited this page Mar 27, 2019 · 12 revisions

Get Started

Before reading this tutorial, we assume you have integrated SmilePass SDK to your Android application. If you have not integrated it yet, please read SDK Setup Guide.

Basic Setup-

Step 1. Instantiate SmilePass client

Create an instance of SmilePass rest client and pass a valid API Key as follows:

SmilePassClient smilePassClient = new SmilePassRestClient("{{API_KEY}}");

The default server URL is the production URL. If you want to set server base URL of different environment i.e. demo server during development time, you can pass it in second argument as follows:

SmilePassClient smilePassClient = new SmilePassRestClient("{{API_KEY}}", "{{SERVER_URL}}");

For example, to use our demo server, you can initialize the SDK as follows-

SmilePassClient smilePassClient = new SmilePassRestClient("{{API_KEY}}", "https://api-demo.smile-pass.com");

Where, https://api-demo.smile-pass.com is the SmilePass demo server URL.

To get API Key of demo server, contact SmilePass.

Step 2. Handle ClientException

You need to handle ClientException for creating an instance and calling any method of SmilePass-

try {
    SmilePassClient smilePassClient = new SmilePassRestClient("{{API_KEY}}");
} catch (ClientException e) {
    e.printStackTrace();
    ClientError clientError = e.error;
}

Features of SDK-

SmilePass SDK supports two main features-

User Registration

You would use this feature where you need to register a new user with face images. There are a number of configurable steps of registration i.e. document, selfie etc. Selfie is the last and mandatory step. Other steps can be optional or mandatory as per the configuration of your company.

Step 1. Call register method

Call register method with the instance of SmilePassClient. For example-

smilePassClient.register(getRegistrationJson(), this);

where, getRegistrationJson() returns the instance of JSONObject and the second argument is the callback listener. The details of JSONObject is discussed later in this document.

Step 2. Implement callback listener

The last parameter of this method is callback listener. Implement OnRegistrationResponseListener listener as follows:

public class MainActivity extends AppCompatActivity implements OnRegistrationResponseListener {
...
}

and override callback method as follows:

@Override
public void onRegistrationResponse(JSONObject jsonObject, Throwable throwable) {
    if (throwable != null) {
       if (throwable instanceof ServerException) {
          ServerError serverError = ((ServerException) throwable).error;
          Log.e(TAG, "onRegistrationResponse(): error=" + serverError.toString());
       } else {
          Log.e(TAG, "onRegistrationResponse(): error=" + throwable.getMessage());
       }
    } else {
          Log.i(TAG, "onRegistrationResponse(): json=" + jsonObject);
    }
}

Step 3. Register with step "document"

To register a user with personal documents i.e. driving license, the first step will be "document". Following is the example JSON to register a user's documents:

private JSONObject getRegistrationJson() {
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("step", "document");
            jsonObject.put("uniqueKey", "[email protected]");
            jsonObject.put("documentId", "3");
            jsonObject.put("frontImageUrl", "https://sampleImageUrl.com/frontImage.jpg");
            jsonObject.put("backImageUrl", "https://sampleImageUrl.com/backImage.jpg");
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return jsonObject;
}

where documentId 3 is for driving license. The list of supported documents, their document IDs and required image URL parameters are as follows:

Document ID Required Images
Passport 1 frontImageUrl
Identity Card 2 frontImageUrl, backImageUrl
Driving License 3 frontImageUrl, backImageUrl

Post Multiple Documents- To post multiple documents, execute this method one by one multiple time with different documentId and images.
Note- For posting images, we support image URLs only. Base64 or any other format is not supported in any feature method.

Step 4. Register with step "selfie"

This is the mandatory and last step to register a new user. Here you need to send selfie(s) of the user. The example JSON of this step is as follows:

private JSONObject getRegistrationJson() {
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("step", "selfie");
            jsonObject.put("uniqueKey", "[email protected]");
            jsonObject.put("callbackUrl","https://example.com/my/webhook/endpoint"); //optional
            JSONArray jsonArray = new JSONArray();
            jsonArray.put("https://sampleImageUrl.com/testSelfie1.jpg");
            jsonArray.put("https://sampleImageUrl.com/testSelfie2.jpg");
            jsonObject.put("imageUrls", jsonArray);
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return jsonObject;
}

If you get a JSON like this-

{
"message": "Your request for registration has been submitted successfully"
}

that means the registration request is submitted successfully. SmilePass is processing this request and will POST final JSON result to webhook URL provided by you in the callbackUrl parameter after completing this process.

If there is an error in registration, an exception will be thrown which you can handle as described in callback method above.

User verification

You would use this feature where you are a service provider who knows the unique ID you want to authenticate against, but nothing else. SmilePass will handle the entire end-to-end process of authenticating the user.

Step 1. Call verify method

Call verify method with the instance of SmilePassClient. For example-

smilePassClient.verify(getVerificationJson(), this);

where, getVerificationJson() returns the instance of JSONObject and the second argument is the callback listener. The details of JSONObject is discussed later in this document.

Step 2. Implement callback listener

The last parameter of this method is callback listener. Implement OnVerificationResponseListener listener as follows:

public class MainActivity extends AppCompatActivity implements OnVerificationResponseListener {
...
}

and override the callback method as follows:

@Override
public void onVerificationResponse(JSONObject jsonObject, Throwable throwable) {
    if (throwable != null) {
       if (throwable instanceof ServerException) {
          ServerError serverError = ((ServerException) throwable).error;
          Log.e(TAG, "onVerificationResponse(): error=" + serverError.toString());
       } else {
          Log.e(TAG, "onVerificationResponse(): error=" + throwable.getMessage());
       }
    } else {
          Log.i(TAG, "onVerificationResponse(): json=" + jsonObject);
    }
}

Step 3. Verification JSON

Following is the example JSON of verification method-

public JSONObject getVerificationJson() {
        JSONObject jsonObject = new JSONObject();
        try {
            jsonObject.put("uniqueKey", "[email protected]");
            jsonObject.put("imageUrl", "https://sampleImageUrl.com/testSelfie.jpg");
        } catch (JSONException e) {
            e.printStackTrace();
        }
        return jsonObject;
}

Step 4. Handle Response

On onVerificationResponse() method, you will get following JSON:

If face matched successfully-

{
"status": true,
"confidenceScore": 0.85
}

If face is not matched-

{
"status": false,
"message": "Face not match",
"confidenceScore": 0.21296
}

where confidenceScore tells how likely two faces belong to the same person. Value of confidenceScore ranges between 0 to 1. The higher the confidence, the more similar are two faces. The recommended value of confidenceScore is 0.6 to match two faces. If there is an error in verification, an exception will be thrown which you can handle as described in callback method above.

Common Errors

There are two types of exceptions-

  • ClientException- You need to handle this while instantiating SmilePass client and calling any feature method. SDK will raise this exception if there is any error found at the client side.
  • ServerException- You will get this in the callback method when there is an error from the server side.

Following are some common error codes and their meanings-

Error Code Description
INVALID_API_KEY When the user is passing blank or invalid API Key to create SmilePass client
JSON_ERROR When the user is sending empty JSON object
BAD_REQUEST When some mandatory parameter is missing in request JSON
INVALID_SERVER_URL When the user is passing invalid server URL in SmilePass client
USER_NOT_FOUND When the user is not registered that you are trying to verify
INTERNAL_SERVER_ERROR When there is some out of control problem from the server side
UNKNOWN_ERROR Any other unexpected error
Clone this wiki locally