Arkose Bot Manager Quickstart

This page is a Quickstart for setting up Arkose Bot Manager. It summarizes a step-by-step process with links to full documentation.

Process Workflow

Each block in the workflow has a label at the top for who is responsible for that step; Arkose or the Customer. Customers are primarily responsible for enabling Arkose API components on both their application’s client and server sides.

Prerequisites

  1. You must have signed up with Arkose Labs and received a login to the Arkose Command Center.

  2. To successfully connect with the Arkose Client and Verify APIs, you need a Public and Private Key Pair. Go to the Arkose Command Center and find your keys in the Settings>Keys area (see the left menubar for access). If you need help with your keys, contact your Arkose Customer Success Manager (CSM).

  1. Arkose strongly recommends:

    1. Using a Development Only Key for all Testing purposes.

    2. Using one Production Key per workflow; i.e. use one Key Pair for your application’s login workflow, and different ones for its Register, Purchase, and other workflows and for multiple sites.

  2. Request your custom Arkose Verify API endpoints from your CSM;

    • Request schema:
      <company>-verify.arkoselabs.com/api/v4/verify/schema/request
    • Response schema:
      <company>-verify.arkoselabs.com/api/v4/verify/schema/response
    • Example:
      https://acme-verify.arkoselabs.com/api/v4/verify/schema/request
      https://acme-verify.arkoselabs.com/api/v4/verify/schema/response

STEP 1: Client-Side Implementation

This step covers basic client-side implementation for Arkose Bot Manager on Desktop/Web Browser applications. If you have more than one platform, you will have to set up each one. Note that there are separate instructions for Client-side implementation for Android Mobile SDK or iOS Mobile SDK. For full client-side implementation details, see Client-Side Instructions

On the client-side, Arkose Bot Manager:

  • Collects the data used to classify client traffic.

  • Based on the traffic classification, displays an Enforcement Challenge (EC) if applicable.

  • Provides a one-time use token to send to the Arkose Verify API.

1.1 Client API Endpoints

When doing your initial client setup as a demo or for testing or familiarization purposes, you can call the Arkose Client API via the generic client-api.arkoselabs.com endpoint.

However, after using it to start out, you will need to change over to a custom Client API hostname in the format of <company>-api.arkoselabs.com. See the detailed Client-Side Instructions for how to set this up.

1.2 Include the Arkose Bot Manager Client API

For all pages you want to use Arkose Bot Manager on, include the Arkose Bot Manager Client API (the API) with your public key, as shown in the below HTML code example.

🚧

Only load the Arkose API script ONCE PER PAGE!

Loading the Arkose API script multiple times on a single page causes duplicate event listeners and causes issues during implementation

1.3 Define a Global JavaScript Function

Define a global JavaScript function as shown in the below HTML example. The code comments have suggestions for where to put the code and how to use this code sample. The arkose-trigger button is generically named to apply to both products.

1.4 HTML Client API / JavaScript Function Examples

Arkose Client-Side Code
Open Recipe
<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 your defined global callback 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="arkose-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 setupArkose(myArkose) {
    myArkose.setConfig({
      selector: '#arkose-trigger',
      onCompleted: function(response) {
        console.log(response.token);
      }
    });
  }
</script>
</body>
</html>

Now that you've installed Arkose Bot Manager on a page, it loads the Arkose Bot Manager API script. When loaded, it creates a myArkose object that exposes public functions listed in the Client API myArkose-object and Client API callbacks sections of these docs. Use these functions to support your specific implementation requirements.

You must ALWAYS call setConfig to set up the Client API and its callback functions. You need to define the callback functions to specify what happens when they are triggered at various points when running Arkose Bot Manager. Note that there are different callback definition requirements for our detection and enforcement components. See Client API for instructions for what to do next , what callbacks are called when during Arkose processing, and full information about the various objects and callbacks you need to use and/or define.

STEP 2: Server-Side Setup

This step covers server-side implementation for Arkose Bot Manager. On the server-side, you verify the client-side provided token with the Arkose Verify API. The verification response contains information about the session, either as a JSON object or in a simple format. These instructions assume you are not implementing the Arkose Labs verification call using your Content Delivery Network (CDN) provider. Details for setting up the verification call using your CDN provider can be found at Content Delivery Network Setup.

Step 2.1 Add Calls to Arkose Verify API

There are several ways to make calls to the Arkose Verify API. In this Quickstart, we only show how to make GET and POST request calls. Both take the same two required parameters:

Parameter NameDescription
private_keyThe Arkose Labs issued private key used for the server-side API.
session_tokenThe token value contained within the token key of the Client API response object. This object is provided within the client-side onComplete callback.

Step 2.1.1 Making a GET Verify Request

Below is an example URL that includes the parameters from the above table as query parameters. Before actually using it, replace the ??? placeholders with the real values to be used, as well as replacing <company> with your company's personalized Verify API URL name.

https://<company>-verify.arkoselabs.com/api/v4/verify/?private_key=???&session_token=???&log_data=???

Step 2.1.2 Making a POST Verify Request

POST requests use the request body. Below is an example of a JSON request body using the above parameters. Before actually using it, replace the _***_HERE_ placeholders with real values. In the call, remember to replace <company> with your company's personalized Verify API URL name. The endpoint is <https://<company>-verify.arkoselabs.com/api/v4/verify/>

{
  private_key: "_PRIVATE_KEY_HERE_",
  session_token: "_SESSION_TOKEN_HERE_",
  log_data: "_LOG_DATA_HERE_"
}

Updated 8 months ago