Skip to content

SmilePass Tutorials

Jump to bottom
Rajat Pagare edited this page Mar 27, 2019 · 14 revisions

Initialization

Step 1. Instantiate SmilePass client

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

let smilePassObject = SmilePassClient(apiKey: "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:

let smilePassObject = SmilePassClient(apiKey: "API_KEY", baseURL: "SERVER_URL")

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

let smilePassObject = SmilePassClient(apiKey: "API_KEY", baseURL: "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

do {
    let smilePassObject = try SmilePassClient(apiKey: "")
} catch ClientException.invalidAPIKeyError {
    print("API key should not be blank")
} catch let error {
    print(error.localizedDescription)
}

Exception

This method will throw an exception ClientException.invalidAPIKeyError if the API key is passed as blank.

Features of SDK-

SmilePass SDK supports two main features-

User Registration

To register a new user with face images you can use register method. There are a number of configurable steps of registration i.e. document, selfie etc.

Step 1. Call register method

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

smilePassObject?.register(parameters: dict, completion: { (response, smilePassError) in
    if smilePassError != nil {
        print("Error Code - \(smilePassError?.errorCode ?? "") Error Message - \(smilePassError?.errorMessage ?? "") User Info - \(smilePassError?.additionalData ?? ["": ""])")
    } else {
        if let resp = response as? [String: Any] {
            print(resp)
        }
    }
})

this method takes [String: Any] as argument and in response handler give 2 objects response and smilePassError

response gives JSON and smilePassError is a custom error object.

Step 2. 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 [String: Any] to register a user's documents:

let dict: [String: Any] = ["step" : "document", "uniqueKey" : "yourUniqueKey", "documentId": "3",  "frontImageUrl": "https://sampleImageUrl.com/frontImage.jpg", "backImageUrl": "https://sampleImageUrl.com/backImage.jpg"]

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 3. 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. Following is the example [String: Any] to register a user:

let dict: [String: Any] = ["step" : "selfie", "uniqueKey" : "yourUniqueKey", "callbackUrl": "https://example.com/my/webhook/endpoint", "imageUrls": ["https://sampleImageUrl.com/testSelfie1.jpg"]]

In case of successful registration, you will 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 above.

SmilePassError

SmilePassError is custom error struct which contains errorCode, errorMessage and additionalData (optional) (in case if there is some additional data for error)

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-

smilePassObject?.verify(parameters: dict, completion: { (response, smilePassError) in
        if smilePassError != nil {
            print("Error Code - \(smilePassError?.errorCode ?? "") Error Message - \(smilePassError?.errorMessage ?? "") User Info - \(smilePassError?.additionalData ?? ["": ""])")
        } else {
            if let resp = response as? [String: Any] {
                print(resp)
            }
        }
    })

this method takes [String: Any] as argument and in response handler give 2 objects response and smilePassError similar to register method

Step 2. Verification JSON

Following is the example [String: Any] of verification method-

let dict = ["uniqueKey" : "yourUniqueKey", "imageUrl": "https://sampleImageUrl.com/testSelfie.jpg"]

Step 4. Handle Response You will get below JSON in response :

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.

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
USER_NOT_FOUND When the user is not registered that you are trying to verify
UNKNOWN_ERROR Any other unexpected error
Clone this wiki locally