Inline Integration Guide

Overview

Use this guide to implement the Arkose Labs Fraud and Abuse Prevention Platform (Arkose Labs Platform) enforcement challenge (EC) in inline mode.

 

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>
</head>

<body>
<!--
  The element containing the challenge can exist anywhere in your page and can be added to the DOM at any time.
-->
<div id="enforcement-container"></div>
<!--
  To configure the EC, 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-container',
      mode: 'inline',
      onCompleted: function(response) {
        console.log(response.token);
      }
    });
  }
</script>
</body>
</html>

 

API Reference

Enforcement Object

The enforcement object received by setupEnforcement in the code example above contains attributes that expose API functions and information.

 

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: '#enforcement-container',
    mode: 'inline'
  });
}

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. #enforcement-container) 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 to 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 Instructions

When you have successfully set up your client-side set up you must go on to the server-side instructions.

 

Example Implementation

This code example shows a possible implementation of the Arkose Labs Platform in inline mode.

This code shows the EC loaded and displayed inline on the page inside the element specified by selector in setConfig.

To aid debugging, the response.token is sent to an alert box.

In production, the response.token must be sent back to your server for further inspection. See server-side instructions for more information.

 
<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: '#enforcement-container',
      mode: 'inline',
      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">
    <div id='enforcement-container'></div>
    <input type="submit" id="submit-id" onclick="return false;" disabled=true, style="opacity:0.5;">
  </form>
</body>

 

Was this article helpful?
0 out of 0 found this helpful