Standard Setup

 

Overview

The Arkose Labs Fraud Detection and Prevention Platform (Arkose Labs Platform) needs client-side and server-side setup.

The user initiates processing by logging in to your system. A call is made to the Arkose Labs Server to establish credentials and check identity. An Enforcement Challenge (EC) is displayed if it is considered necessary by the Arkose Labs Platform. The user response to the EC is handled by the client-side. It is then passed to your server-side processing, which then calls the Arkose Labs Verify Endpoint. The response from the Arkose Labs Verify Endpoint is then passed to your server-side processing, which decides what action to take, based on the response.

Fig 1. Flow of information for Arkose Labs Platform

This guide includes client-side set up information

 

Client-Side Setup

To set up the client-side of The Arkose Labs Platform:

  1. Include The Arkose Labs Platform JavaScript API (the API) for your public key as shown in the figure below. This should be included in your code where you want the EC to appear.

  2. Define a global JavaScript function.

  3. Configure your public key.

The example below shows code that includes the client API and declares the global JavaScript enforcement function. The comments contain suggestions for where the code should be placed and how this code sample can be used.

<html>
<head>
  <!--
    Include the Arkose Labs API in the <head> of your page. In the example below, remember to
    replace the <YOUR PUBLIC KEY> with the public key supplied to you by Arkose Labs, and replace <YOUR CALLBACK> with a name that
    refers to a global function.
    e.g. <script src="//client-api.arkoselabs.com/v2/11111111-1111-1111-1111-111111111111/api.js" data-callback="setupEnforcement" async defer></script>
  -->
  <script src="//client-api.arkoselabs.com/v2/<YOUR PUBLIC KEY>/api.js" data-callback="<YOUR CALLBACK>" async defer></script>
  <link rel="shortcut icon" href="#">
  <meta charset="UTF-8">
</head>
<body>
<!--
  The trigger element can exist anywhere in your page and can be added to the DOM at any time.
-->
<button id="enforcement-trigger">
  trigger element
</button>
<!--
  To configure the enforcement place a script tag just before the closing <body> tag and define the
  callback as a global function.
-->
<script>
  /*
    This global function will be invoked when the API is ready. Ensure the name is the same name
    that is defined on the attribute `data-callback` in the script tag that loads the api for your
    public key.
  */
  function setupEnforcement(myEnforcement) {
    myEnforcement.setConfig({
      selector: '#enforcement-trigger',
      onCompleted: function(response) {
        console.log(response.token);
      }
    });
  }
</script>
</body>
</html>

API Reference

Enforcement Object

The enforcement object contains attributes that pass information to the callback function.

Method

Type

Description

enforcement.getConfig

Function

Returns the configuration object

enforcement.reset

Function

Resets the enforcement. This will create a new session.

enforcement.setConfig

Function

Updates the configuration object.

enforcement.run

Function

Verifies the user.

enforcement.version

String

Returns the API version (e.g. 2.0.0).

Configuration Object

The configuration object is used to configure the EC.

The EC can be configured using the setConfig method on the enforcement object as shown in the example below.

// The Callback Function
function setupEnforcement(myEnforcement) {
  myEnforcement.setConfig({
    data: {},
    language: 'ar',
    onCompleted: (response) => {},
    onHide: () => {},
    onReady: () => {},
    onReset: () => {},
    onShow: () => {},
    onShown: () => {},
    onSuppress: () => {},
    selector: '#my-submit-button'
  });
}

The table below shows the attributes used on the setconfig method, along with their types and a brief description.

Method

Type

Description

data

Object

Arbitrary data sent to us when the challenge is completed.

language

String

Language code. See Language Support for a list of supported languages. The EC language is automatically controlled by the browser settings, but can be controlled manually by passing the entire Locale ID String for the language required via this setting.

onCompleted(response)

Function

A callback invoked after verification (e.g. After a challenge is completed). A Response Object is passed to this function.

onHide

Function

A callback invoked when the EC is hidden For example, After an EC is completed or if the user clicks the close button.

onReady

Function

A callback invoked when the Enforcement is ready. The Enforcement cannot be triggered before this event. You may want to disable the UI you are protecting until this event has been triggered.

onReset

Function

A callback invoked after the Enforcement resets. Typically occurs after a challenge has been answered.

onShow

Function

A callback invoked when the EC is shown. This happens every time the EC is re-displayed.

onShown

Function

A callback invoked when the an Enforcement Challenge is shown.

onSuppress

Function

A callback invoked when the an Enforcement Challenge is suppressed (i.e. A user verified without being asked to complete a challenge).

selector

String

The element selector (e.g. #my-submit-button) for either triggering the EC to display as a modal, or where the EC will appear inline on the page. This parameter is dependent on how the mode parameter has been configured.

mode

String

Sets if the EC will be shown as a modal or within the selected element. Allowed values are lightbox and inline, where the default is lightbox, which indicates display as modal.

 

Response Object

When an enforcement is completed, the configured onCompleted function is invoked with a response object.

onCompleted: function(response) {
  // sendToBackendServer(response.token);
}

Method

Type

Description

response.token

String

The token you will need to send to your back-end server for verification.

Server Side Set Up

When you have successfully set up your client-side set up you must set up your server by following the server-side instructions.

 

Example Implementations

These code examples show possible implementations of the Arkose Labs Platform.

Session Invocation + Modal Overlay

The example below shows the following:

  1. The enforcement challenge loaded as a semi-opaque modal screen.

  2. The session is loaded and the appropriate challenge is displayed, depending on the key settings.

    1. If the key is set to transparent mode, and the user’s credentials are validated, the modal box will disappear automatically after an imperceptible pause.

<head>
  <script type="text/javascript" data-callback="setupEnforcement" src="//api.arkoselabs.com/v2/11111111-1111-1111-1111-111111111111/api.js" async defer></script>
</head>
<script>
  function setupEnforcement(myEnforcement) {
    myEnforcement.setConfig({
      selector: '#submit-id',
      onCompleted: function(response) {
        alert(response.token);
      },
      onReady: function() {
        document.getElementById("submit-id").style.opacity = "1";
        document.getElementById("submit-id").disabled = false;
      }
    });
  }

</script>

<body>
  <form method="post" target="_self">
    <input type="text">
    <input type="submit" id="submit-id" onclick="return false;" disabled=true, style="opacity:0.5;">
  </form>
</body>

In this example, form elements are locked out until the Arkose Labs session is ready. To make this sample complete, the response.token is output to an alert box. In production the response.token is sent back to your server for further inspection.

Full Modal Overlay

The example below shows the following:

  1. The enforcement challenge loaded as a semi-opaque modal screen.

  2. The session is loaded and the appropriate challenge is displayed, depending on the key settings.

    1. If the key is set to passive mode, and the user’s credentials are validated, the modal box will disappear automatically after an imperceptible pause.

<head>
  <script type="text/javascript" data-callback="setupEnforcement" src="//api.arkoselabs.com/v2/11111111-1111-1111-1111-111111111111/api.js" async defer></script>
</head>
<script>
  function setupEnforcement(myEnforcement) {
    myEnforcement.setConfig({
      onCompleted: function(response) {
        console.log(response);
        alert(response.token);
      },
      onReady: function() {
        myEnforcement.run();
      }
    });
  }
</script>
<body>
</body>

In this example, Configuration Object parameters are manually set (eg. Language), and additional parameters can be passed if necessary.

To make this sample complete, the response.token is output to an alert box. In production, the response.token is sent back to your server for further inspection.

Inline Mode

In the example below, the EC is loaded and displayed inline on the page inside the element specified by selector in setConfig

To make this sample complete, the response.token is output to an alert box. In production, the response.token is sent back to your server for further inspection.

 

<head>
  <script type="text/javascript" data-callback="setupEnforcement" src="//api.arkoselabs.com/v2/11111111-1111-1111-1111-111111111111/api.js" async defer></script>
</head>
<script>
  function setupEnforcement(myEnforcement) {
    myEnforcement.setConfig({
      selector: '#my-element',
      mode: 'inline',
      onCompleted: function(response) {
        alert(response.token);
      },
    });
  }
 
</script>
 
<body>
  <div id="my-element"></div>
</body>
Was this article helpful?
0 out of 0 found this helpful