Android Integration

Integrate Attestr Studio Android SDK within your mobile applications to automate eKYC workflows.

Available Versions

Attestr Android SDK is distributed through Maven Central. Made for Android mobile and tablet devices.

Integration Steps

Step 1. Add Attestr Flowx Android SDK library in your application.

Maven Central

Attestr Android SDK is distributed through Maven. Add the following line to your application's build.gradle file.

repositories {

    mavenCentral()

}

​

dependencies {

    implementation 'com.attestr:attestr-flowx:0.5.0'

}

Step 2. Create a handshake on the server side

The first step involves initiating a handshake. Invoke Create Handshake API from your server side code which returns a handshake Id (also known as device session Id).

Step 3. Store the handshake Id in database

The handshake Id generated in step one must be stored in the database for later retrieval. This is needed for two reasons - 1) To retrieve the final result for the handshake 2) To validate the result signature. More details on signature below.

Step 4. Import AttestrFlowx and AttestrFlowxListener in launch activity

import com.attestr.flowx.AttestrFlowx;

import com.attestr.flowx.listener.AttestrFlowXListener;

Step 5. Conform to AttestrFlowxListener

Make your activity conform to AttestrFlowxListener and add your implementations of success, error and skip handlers.

public class MainActivity extends AppCompatActivity implements AttestrFlowXListener {

   .....

   @Override

    public void onFlowXComplete(Map<String, Object> map) {

        Toast.makeText(this, "Signature: "+map.get("signature"), Toast.LENGTH_SHORT).show();

    }

​

    @Override

    public void onFlowXSkip(Map<String, Object> map) {

        Toast.makeText(MainActivity.this, "Flow skipped", Toast.LENGTH_SHORT).show();

    }

​

    @Override

    public void onFlowXError(Map<String, Object> map) {

        String errorMessage = (String) map.get("message");

        Toast.makeText(MainActivity.this, "Error : "+errorMessage, Toast.LENGTH_SHORT).show();

    }

}

onFlowxSuccess

On successful completion of the flow execution, result signature is returned in the Map object.

{"signature": "2021cc7afd51885eab998765c3dc502177b74ae9f98ff622f05d65dc7d075efe"}

onFlowxError

This handler is triggered, if an irrecoverable error is encountered during the flow execution which leads to termination of user's device session. The signature of error object is as follows.

{"code": 5001, "httpStatusCode": 500, "message": "अनुरोध पूरा नहीं किया जा सका। बाद में कोशिश करें।","retry": false, "stage":"FS02zfeuv3tcnkq2mond2", "original": {"code":4035, httpStatusCode:403, "message":"Requested service is not provisioned for your account"}}

• code An error code which determines the type of error. Every flow stage has its own set of possible error codes. Please check the respective stage type documentation for the list of error codes.
• httpStatusCode The http status codes are used as standard to classify the error into malformed inputs, authorization related issues, configuration issues and other unknown errors.
• message This is the localized error message describing the cause of error in user's language as passed in the launch method below. It can be used to display the errors to user if desired.
• retry Whether the given error is recoverable or irrecoverable. It is always set as False while invoking onFlowxError function as onFlowxError is only called if the error is irrecoverable. Any recoverable errors are handled by the Attestr framework.
• stage This is the Id of the stage at which the execution is halted. If the flow errors while identifying the next stage to run, this returns the last stage which completed successfully. If the flow fails while identifying the first stage in the flow, this key will be set as null.
• original This key is available only in the cases when the error's root cause is something else. It could be either due to low credits balance, rate limit exceeded, service not provisioned etc. Check the error codes in the respective API documentation for the possible values that can show up in original object.

Check the respective stage documentation for possible error code values.

onFlowxSkip

This handler is triggered if the flow session is interrupted by the user. The data object contains only one key called stage which is the Id of the stage at which execution is skipped. If the execution is skipped while the server is busy fetching the next stage, this returns the last stage which completed successfully. If the flow is skipped while identifying the first stage in the flow, this key will be set as null.

{"stage": "FS02zfeuv3tcnkq2mond2"}

Step 6. Initialize the AttestrFlowx object

In your launch activity, next create an instance of AttestrFlowx by calling the constructor and invoke init method on the created instance, as shown below

@Override

protected void onCreate(Bundle savedInstanceState) {

  super.onCreate(savedInstanceState);

  ...

  AttestrFlowx attestrFlowx = new AttestrFlowx();

  // Function signature

  // public void init( String cl,String hs, Activity activity)

    // cl is the client key as associated with the client app created in the Attestr dashboard

  // hs is the handshake Id created in Step 2 above

  // activity refers to the current LaunchActivity instance. Attestr SDK uses this reference for rendering of the flows.

  attestrFlowx.init(clientKey, handShakeID, this);

  ...

}

Step 7. Launch the flow

You must call launch function of AttestrFlowX object to run the flow. The syntax is as below. This establishes the connection with Attestr servers and runs the flow on user's device.

/**

  * This function launches the flow with the following specifications

  * @param lc Mandatory language code eg. 'en' for English.

  * @param retry Mandatory parameter to set retry as true if re-running the flow for a previously used handshake.

  * @param qr Optional query parameters.

 */

 //public void launch(String lc, boolean retry, Map<String, String> qr)

attestrFlowx.launch('en', false, null);

Sample Launch Activity

package com.example.attestrtestapp;

​

import android.os.Bundle;

import android.text.TextUtils;

import android.util.Log;

import android.view.View;

import android.widget.AdapterView;

import android.widget.ArrayAdapter;

import android.widget.AutoCompleteTextView;

import android.widget.Button;

import android.widget.EditText;

import android.widget.Spinner;

import android.widget.Toast;

import androidx.appcompat.app.AppCompatActivity;

​

import com.attestr.flowx.AttestrFlowx;

import com.attestr.flowx.listener.AttestrFlowXListener;

import com.example.attestrtestapp.databinding.ActivityMainBinding;

import java.util.Map;

​

public class MainActivity extends AppCompatActivity implements AttestrFlowXListener {

    ...

    private AttestrFlowx attestrFlowx;

    ...

​

    @Override

    protected void onCreate(Bundle savedInstanceState) {

        super.onCreate(savedInstanceState);

        ....

        attestrFlowx = new AttestrFlowx();

        attestrFlowx.init(clientKey, handShakeID, this);

        attestrFlowx.launch('en', false, null);

    }

​

    @Override

    public void onFlowXComplete(Map<String, Object> map) {

        Toast.makeText(this, "Signature: "+map.get("signature"), Toast.LENGTH_SHORT).show();

    }

​

    @Override

    public void onFlowXSkip(Map<String, Object> map) {

        Toast.makeText(MainActivity.this, "Flow skipped", Toast.LENGTH_SHORT).show();

    }

​

    @Override

    public void onFlowXError(Map<String, Object> map) {

        String errorMessage = (String) map.get("message");

        Toast.makeText(MainActivity.this, "Error : "+errorMessage, Toast.LENGTH_SHORT).show();

    }

}

https://github.com/attestr/android-sample-app/blob/master/app/src/main/java/com/example/attestrtestapp/MainActivity.java

Step 8. Fetch the result on the server side.

On successful completion of the flow, call Execution Result API on the server side to query the result of the session. Pass the handshake Id generated in step 1 while calling the API.

Step 9. Validate signature on server side

This is the final step in integration. The outcome of Execution Result API contains a result signature key. You must perform the following 2 checks.

• Check if the signature returned in the API matches the signature retrieved in the onSuccess handler.
• Generate signature on your server side code base and check if it matches the signature returned in the API. To generate the signature, use the SHA256 algorithm, the client secret and the result object as returned in step 6 to generate a HMAC Hex Digest as shown in the sample code below.

const crypto = require("crypto");

​

var clientSecret; // This should be initialized as client secret.

var apiResponse; // This is apiResponse as retuned in step 6.

​

function hmacHexDigest(secret, input) {

    const hmac = crypto.createHmac('sha256', secret)

    hmac.update(input)

    return hmac.digest('hex')

}

​

var signature = hmacHexDigest(clientSecret, JSON.stringify(apiResponse.result));

​

// Check if signature matches

if(signature !== apiResponse.resultSignature){

  // Flow is tampered.

}

Retry On Error

Attestr offers retry mechanism to reattempt flows that run into errors or return invalid data output for one or more stages. To rerun the flow, set the retry parameter to true while initializing AttestrFlowx object and launch the flow. Check step 5 above.

Retry skips all stages that ran successfully during the previous run. If all stages were successful during the previous run, the flow simply returns invoking the success handler.

Attestr Sample Android Application

Clone this project and add to Android Studio. Build and launch the app.

https://github.com/attestr/android-sample-app