Client-Side Instructions
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.


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 |
---|---|---|
| Function | Returns the configuration object |
| Function | Resets the current session for both Arkose Detect and Arkose Protect. This creates a new session. |
| Function | Updates the configuration object. |
| Function | Triggers the Arkose Detect or Arkose Protect API to classify the current session. |
| 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 |
---|---|---|---|
| Object | Encrypted arbitrary JSON data sent to Arkose at the very start of a sessions classification. | Arkose Detect |
| 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 |
| Function | Callback function invoked when applicable detection and/or enforcement has been successfully completed. A Response Object is passed to this function. | Arkose Detect |
| 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 |
| 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 |
| 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 |
| Function | Only applicable to Arkose Protect. A callback invoked when the Enforcement Challenge is displayed. The | Arkose Protect |
| Function | A callback invoked when the detection and/or enforcement is running and the Arkose Platform is analyzing the user intent. | Arkose Detect |
| 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 |
| 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 |
| 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 |
| Function | A callback invoked after the enforcement resets. Typically occurs after a challenge has been successfully answered. | Arkose Protect |
| String | The element selector (e.g. | Arkose Protect |
| 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 |
| Object | Contains settings for accessibility that need to make changes implementing websites markup.
| Arkose Protect |
| 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 aresponse
object. -
When a challenge is loaded, the configured
onResize
function is invoked with aresponse
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 |
---|---|---|---|
| String | The token you will need to send to your back-end server for verification. | onCompleted |
| Error object |
| onError |
| String | An error code string representing the error that occurred during the loading of the challenge. | |
| String | Only applicable to Arkose Protect. The challenge frame height size in px. e.g. "290px" | onResize |
| 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.
- 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>
Updated 5 days ago