Web Integration

Integrate Attestr Studio Javascript SDK within your web applications to automate eKYC workflows.

Integration Steps

Step 1. Include Attestr Flowx Javascript library in the front end web application.

You can either directly point the <script> tag to Attestr CDN or download the file and include your local copy. We recommend using the CDN link for automated future updates.

<script src="https://cdn.attestr.com/flowx.js"></script>

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. Initialize AttestrFlowX Javascript object

In the Javascript code, create an instance of AttestrFlowx object as shown below.

<script src="https://cdn.attestr.com/flowx.js"></script>

​

<script style="">

      var flowx = new AttestrFlowx({

        onFlowxError: function (data) {  // Error handler function

          alert(JSON.parse(data).message);

        },

        onFlowxComplete: function (data) { // Success handler function

            alert(JSON.parse(data).signature);

        },

        onFlowxSkip: function (data) { // Skiphandler function. Triggered if user terminates / skips the flow.

          alert("You have skipped the flow");

        },

        cl: 'f976e84c99f3dd1520256723d81c92d2', // This is the client key

        hs: 'DS02zfeuv5245kq3qx0yw', // Handshake Id generated in integration step 1.

        lc: "en", // Localization context to render flow in the user locale.

        qr: {

          var_1: "age" // var_1 is the name of variable defined in the flow.

          .....

        }, // Use qr key to assign initial values to variables defined in the flow, if desired.

        retry: "true | false" // Pass true or false if this is retry attempt for provided handshake

      });

​

      flowx.launch();  // The method to launch the flow in user's browser.

  </script>

Step 5. Define function handlers

While the above code shows sample implementations of success, error and skip handlers, you must provide custom implementations of these functions. Check the tables below for data object definition for the three handler functions.

onFlowxSuccess

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

{"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 chosen while initializing the AttestrFlowX object. 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. Launch the flow

You must call launch function of AttestrFlowX JS 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.

flowx.launch();

Step 7. 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 8. Validate signature

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 key to true while initializing AttestrFlowx object and launch the flow. Check step 3 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.

Browser Support

While the application is validated on majority of browser versions, we provide support for only LTS versions. For any issues in older versions that are officially no longer supported, it is recommended to upgrade the browser.

• Chrome on desktop, android, IOS
• Firefox on desktop, android, IOS
• Safari on MacOS, IOS
• Android webview
• Edge on desktop
• Samsung Internet

Sample Web Application

Sample web application is available at

https://github.com/attestr/studio-sample-webapp

Clone and run it using Nginx, Apache or any other HTTP server.