Standard Setup

 

Overview

There are two steps required to fully implement the Arkose Labs Detection and Prevention Platform (Arkose Labs Platform):

  1. Client-side implementation that allows the Arkose Labs Platform to collect data necessary to classify the traffic from the client, display an Enforcement Challenge (EC) if necessary, and provide a one-time use token.

  2. Server-side implementation that takes the token provided by the client-side and verifies it with the Arkose Labs verify API. The result is a response that contains information about the session, either in a simple format or as a JSON.

This guide documents the steps required to implement the client-side processing. There are separate instructions for iOS and Android.

API Request Authentication

Arkose Labs authenticates your API requests using a private/public key pair that can be retrieved from the Site Settings page of the Arkose Labs Client Dashboard. If you do not have access to the dashboard or do not have your private and public keys, contact your Sales Rep or Sales Engineer.

The private key is needed to authenticate when using the verify API. This private key must not be published on a client facing website, and must only be used on your server-side implementation on the Arkose Labs verify API.

Client-Side Setup

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

  1. Include The Arkose Labs Platform cIient-api (the API) with 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.

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'',
    accessibilitySettings: {
      lockFocusToModal: true 
    }
  });
}

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 Supported Languages 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.

accessibilitySettings

Object

Contains settings for accessibility that need to make changes implementing websites markup.

lockFocusToModal
If enabled and mode is set to lightboxaria-hidden=true will be added to sibling elements of the Enforcement Challenge container. This is to ensure that users employing Assistive Technology do not accidentally leave the lightbox before interacting with the challenge.

 

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.

AWS China Solution

If you are using the AWS China solution you will need to add some more steps to this process. See https://support.arkoselabs.com/hc/en-us/articles/4401849614227-Get-Started-with-Arkose-Labs-in-China for more details.

 

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.

    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.

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.

    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.

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.

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