Overview

Fully implementing the Arkose Fraud Deterrence Platform (Arkose Platform) requires two steps:

Client-side implementation for the Arkose Platform to collect data needed to classify client traffic, display an Enforcement Challenge (EC) if applicable, and provide a one-time use token.
Server-side implementation that takes the client-side provided token and verifies it with the Arkose Labs Verify API. The response contains information about the session, either as a JSON object or in a simple format.

This page describes the required steps to implement client-side integration of Arkose Platform, both for Arkose Detect and Arkose Protect. Arkose Detect provides detection only capabilities with no visual enforcement while Arkose Protect provides both detection and visual enforcements. There are additional instructions for iOS Mobile SDK and Android Mobile SDK.

API Request Authentication

Arkose Labs authenticates your API requests using a private/public key pair that can be retrieved from the Key Settings page of the Arkose Labs Command Center. As shown below, go to the left menubar's Settings entry, and then to the Keys sub-entry. If you do not have access to the Command Center or do not have your private and public keys, contact your Sales Rep or Sales Engineer.

Screen Shot 2022-02-20 at 5.23.57 PM.png

You use the private key 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 Verify API's server-side implementation.

Client-Side Setup

To set up the Arkose Platform's client-side:

For all pages you want to use the Arkose Platform, include the Arkose Platform Client API (the API) with your public key, as shown in the below HTML code.
Define a global JavaScript function as shown below.

The comments have suggestions for where to put the code and how to use this code sample. Note that there are different code samples for Arkose Detect and Arkose Protect.

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

<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="setupDetect" 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="detect-trigger">
  trigger element
</button>
<!--
  To configure the detection, 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 setupDetect(myDetect) {
    myDetectt.setConfig({
      selector: '#detect-trigger',
      onCompleted: function(response) {
        console.log(response.token);
      }
    });
  }
</script>
</body>
</html>

API Reference

Arkose Object

The myArkose object's attributes pass information to the callback function. This applies to both Arkose Detect and Arkose Protect.

Method	Type	Description
`myArkose.getConfig`	Function	Returns the configuration object
`myArkose.reset`	Function	Resets the current session for both Arkose Detect and Arkose Protect. This creates a new session.
`myArkose.setConfig`	Function	Updates the configuration object.
`myArkose.run`	Function	Triggers the Arkose Detect or Arkose Protect API to classify the current session.
`myArkose.version`	String	Returns the API version (e.g. 2.0.0).

API Callback Sequence

This diagram shows the API callbacks sequence, along with a brief description of what triggers each callback in that position of the sequence (i.e. the two onHide references below have different triggering descriptions since that callback happens in two different positions in the sequence).

Configuration Object

You configure Arkose Protect or Arkose Detect by setting attribute values for the configuration object. This is done using the setConfig method on the Arkose object passed to the setup function, as shown here. If any of the callback functions are not invoking as expected, contact your Sales Rep or Sales Engineer. Note that there are separate examples for Arkose Detect and Arkose Protect.

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

// The Callback Function
function setupDetect(myDetect) {
  myDetect.setConfig({
    data: {},
    onCompleted: (response) => {},
    onHide: () => {},
    onReady: () => {},
    onShow: () => {},
    onSuppress: () => {},
    onError: (response) => {},
    selector: '#my-submit-button'
    }
  });
}

This table shows the settable setConfig attributes, their types, and a brief description. Unless otherwise specified, the attributes are applicable for both Arkose Detect and Arkose Protect.

Method	Type	Description	Applicable Product
`data`	Object	Encrypted arbitrary JSON data sent to Arkose at the very start of a sessions classification.	Arkose Detect Arkose Protect
`language`	String	Language code. See Supported Languages for our supported values. Browser settings control Arkose Platform's language, but can be overridden by using this setting to pass your desired language's entire Locale ID String.	Arkose Protect
`onCompleted(response)`	Function	Callback function invoked when applicable detection and/or enforcement has been successfully completed. A Response Object is passed to this function.	Arkose Detect Arkose Protect
`onHide`	Function	Callback function invoked when the detection and/or enforcement view is hidden. For example, this happens after detection and/or enforcement is completed. It's also triggered during enforcement if the user clicks the close button. Note that the close button only appears when in Lightbox mode.	Arkose Detect Arkose Protect
`onReady`	Function	Callback function invoked when the detection or 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.	Arkose Detect Arkose Protect
`onShow`	Function	A callback invoked when detection and/or enforcement is loading. The function is also invoked when an enforcement is re-displayed (e.g. if the user closes the view and tries to continue). Note that the close button only appears when in Lightbox mode.	Arkose Detect Arkose Protect
`onShown`	Function	Only applicable to Arkose Protect. A callback invoked when the Enforcement Challenge is displayed. The `onShown` method will only be invoked the first time an Enforcement Challenge is displayed.	Arkose Protect
`onSuppress`	Function	A callback invoked when the detection and/or enforcement is running and the Arkose Platform is analyzing the user intent.	Arkose Detect Arkose Protect
`onError(response)`	Function	A callback invoked when an error occurs in loading of the detection and/or enforcement. A Response Object is passed to this function.	Arkose Detect Arkose Protect
`onFailed(response)`	Function	Callback function invoked when a challenge has failed (the user has failed the challenge multiple times and is not allowed to continue the session). A Response Object is passed to this function.	Arkose Protect
`onResize(response)`	Function	A callback invoked when a sizing event occurs in the loading of the challenge. A Response Object is passed to this function.	Arkose Protect
`onReset`	Function	A callback invoked after the enforcement resets. Typically occurs after a challenge has been successfully answered.	Arkose Protect
`selector`	String	The element selector (e.g. `#my-submit-button`) for either triggering the detection to display as a modal, or where the detection will appear inline on the page. This parameter is dependent on how the mode parameter has been configured."	Arkose Protect
`mode`	String	Sets if the Enforcement Challenge 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.	Arkose Protect
`accessibilitySettings`	Object	Contains settings for accessibility that need to make changes implementing websites markup. `lockFocusToModal` If enabled and `mode` is set to `lightbox`, `aria-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.	Arkose Protect
`styleTheme`	String	Sets theme to existing style manager built theme with the given name. If not set, the default theme is used.	Arkose Protect

Response Object

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

The following only apply to Arkose Protect:

When a challenge has failed, the configured onFailed function is invoked with a response object.
When a challenge is loaded, the configured onResize function is invoked with a response object.

onCompleted: function(response) {
  // sendToBackendServer(response.token);
},
onFailed: function(response) {
  // sendUserChallengeFailedToBackendServer(response.token);
},
onError: function(response) {
  // sendScriptLoadingErrorToBackendServer(response.error);
},
onResize: function(response) {
  // optionally handle sizing events as needed on the client-side with response.height and response.width data
}

onCompleted: function(response) {
  // sendToBackendServer(response.token);
},
  
onError: function(response) {
  // sendScriptLoadingErrorToBackendServer(response.error);
}

Method	Type	Description	Callback
`response.token`	String	The token you will need to send to your back-end server for verification.	onCompleted onFailed
`response.error`	Error object	`response.error` is an error object that contains an error code string.	onError
`response.error.error`	String	An error code string representing the error that occurred during the loading of the challenge.
`response.height`	String	Only applicable to Arkose Protect. The challenge frame height size in px. e.g. "290px"	onResize
`response.width`	String	Only applicable to Arkose Protect. The challenge frame width size in px. e.g. "302px"	onResize

Arkose China Solution

If you are using the Arkose China solution with either Arkose Detect or Arkose Protect, you will need to add some more steps to this process. See Getting Started with the Arkose China Solution (requires Arkose Labs Support Portal login) for details. For an overview, see Arkose Fraud Deterrence Platform in China (requires Arkose Labs Support Portal login).

Inline Integration

This section is applicable for both Arkose Protect and Arkose Detect. However, the content about styling and positioning the Enforcement Challenge only applies to Arkose Protect.

You can integrate the EC inline. This is primarily used for styling, positioning, and in general giving you more control over the integration presentation. If you are considering using inline mode, please consult with Arkose Labs first. There are cost implications associated with its use that you should be aware of before using it.

For full details, see the Inline Integration Guide (Arkose Labs Support login needed).

Example Implementations

These code examples show possible implementations of the Arkose Protect. This section is not applicable to Arkose Detect.

Session Invocation + Modal Overlay

The example below shows the following:

The Enforcement Challenge loaded as a semi-opaque modal screen.
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 session is classified as not requiring a challenge, the modal box is not shown.

In this example, form elements are locked out until the Arkose Labs API 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.

<head>
  <script type="text/javascript" data-callback="setupEnforcement" src="//client-api.arkoselabs.com/v2/11111111-1111-1111-1111-111111111111/api.js" async defer></script>
  <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>
</head>
<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>

Full Modal Overlay

This is only applicable to Arkose Protect.

The example below shows the following:

The Enforcement Challenge loaded as a semi-opaque modal screen.
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 session was classified as not requiring a challenge, the modal box will disappear automatically after an imperceptible pause.

In this example, Configuration Object parameters are manually set, 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.

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