Bot protection instrumentation

• March 2026 —  Updated the topic to add information about allowing  traceable.ai in your Content Security Policy (CSP) to prevent JavaScript API calls to Traceable services from being blocked. For more information, see Out-of-Band (OOB).

This section explains how to create an Edge configuration, save it, and embed the generated JavaScript.

Configuration overview

Provide a Site Name for this configuration, select an Edge Cluster, choose an Environment label (free text; a new value is created if it does not exist), and review the Domain(s) shown from your Edge onboarding.

Note

To configure Edge deployment, Edge Cluster, and Domain should already be configured.

(Optional) You may also enable:

• Interstitial Page with an optional message. A brief, neutral holding screen appears while Traceable evaluates the request; your page continues afterward.

• IP Whitelisting — Traffic from trusted IP addresses or ranges bypasses bot challenges for this configuration. Keep the list focused and reviewed.

• Captcha — Visual Captcha or ProofShield. Visual Captcha presents an interactive challenge. ProofShield emphasizes passive checks to reduce end-user friction.

• Captcha Scope — Choose Include URLs to protect a narrow set of paths or Exclude URLs to provide broad coverage with a few exceptions.

Steps

Follow these steps to configure Edge and place the JavaScript in your pages.

1. Select Deployment Mode: Edge and complete the fields described above.

2. Save the configuration. After provisioning completes, download the JavaScript.

3. In the dialog, select Captcha Display Type (Modal or User-defined container), then copy the generated JavaScript and embed it on the relevant pages.

The process is complete when the snippet is embedded, and traffic appears in Bot telemetry for the configured environment and domains.

Example (Edge)

<script>
  var traceableCaptchaConfig = { sitekey: "<SITE_KEY>" };
</script>
<script src="/traceable/captcha/v3/<SITE_KEY>/fp.js"></script>

This section explains Out-of-Band end-to-end instrumentation, what you configure in the UI, what the UI provides after provisioning, and how your backend integrates.

How Out-of-Band works in two steps

Out-of-band has a simple handoff between your UI configuration and your backend.

Step 1 — Configure in the UI.
Create the OOB configuration and save it. After provisioning, the UI shows three items: the URL to Validate Token, the API Token, and a generated JavaScript snippet.

Where to find your Site Key ID
If you need to copy the site key later, open JS Tag Management, click the (⋯) menu on your configuration, and choose View. The View Configuration panel shows Site Key ID, API Token, and URL to Validate Token together.

Step 2 — Set up your backend API.
Using the URL to Validate Token and API Token, create a lightweight endpoint in your application, for example, POST /traceable/validate-token. The JavaScript snippet sends the browser token to your endpoint. Your endpoint calls Traceable’s validation URL with the API token and, on success, establishes the session.

Note

The JavaScript snippet alone will not complete validation. It becomes fully effective only after your backend endpoint is in place and you call the Validate Token endpoint with the API Token.

Configuration values

• Specify the Site Name, for example, Traceable.

• Specify the Environment (free text).

• Specify the Domain(s).

• (Optional) Enable the IP Whitelisting.

  Note

  Ensure that traceable.ai is whitelisted in your Content Security Policy (CSP) to prevent JavaScript API calls to Traceable servers from being blocked.

• Enable the Captcha (Visual Captcha or ProofShield) with your chosen display, and Captcha Scope to include or exclude URL

After you save the configuration and Traceable provisions, you get a Site Key ID (available under ⋯ → View), API Token with Rotate Token, and URL to Validate Token.

Steps

Follow these steps to complete OOB from configuration to backend handoff.

1. Select Deployment Mode: Out-of-Band, then save the configuration.

2. When provisioning completes, open Download JavaScript or the configuration view and copy the URL to Validate Token, API Token, and the JavaScript snippet.

3. Implement the backend endpoint in your application. It should accept the token object from the browser, call the URL to validate the Token with the API Token, and, on success, establish your application session.

4. Embed the generated JavaScript on your pages. The flow completes end-to-end once your backend is live.

Note

As shown in the screenshot above, use the URL to validate and the API token to set up your API backend.

The process is complete when your backend successfully validates tokens, and the application establishes a session after the Traceable check.

Example (OOB)

<script>
  var traceableCaptchaConfig = {
    sitekey: "<SITE_KEY>",
    tokenCallback: function (tokenObj) {
      fetch("https://<YOUR_APP_DOMAIN>/traceable/validate-token", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify(tokenObj)
      });
    }
  };
</script>
<script src="https://app.<region>.traceable.ai/traceable/captcha/v3/<SITE_KEY>/fp.js"></script>

Rotating the API token
Use Rotate Token when you need to change credentials. The previous token remains valid for 7 days to allow a safe switchover.

Backend API implementation

This section provides you with a sample of how to implement the backend API using Python or Java.

HTTP Method: POST

Parameters:

Response - Token Validation Success:

{
  "valid": true,
  "message": "",
  "timestamp": "ISO 8601 timestamp",
  "error-codes": [],
  "traceableSessionCookieString": "traceable-session=cookie"
}

Response - Token Validation Failure:

{
  "valid": false,
  "message": "",
  "timestamp": "ISO 8601 timestamp",
  "error-codes": []
}

Traceable Session Cookie:

If the token is valid, a traceableSessionCookieString is returned in the API response. This string must be added to the response headers using the Set-Cookie header.

Sample Token Validation API Implementation:

• Python

• Java

Sample code for Python and Java is provided below:

Java

package com.crapi.service.Impl;
import com.crapi.model.TraceableCaptchaRequest;
import com.crapi.model.TraceableCaptchaResponse;
import com.crapi.service.TraceableCaptchaValidateTokenService;
import com.fasterxml.jackson.databind.ObjectMapper;
import lombok.extern.slf4j.Slf4j;
import org.springframework.beans.factory.annotation.Value;
import org.springframework.http.HttpEntity;
import org.springframework.http.HttpHeaders;
import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.stereotype.Service;
import org.springframework.web.client.RestTemplate;
/*
 * Sample Implementation of the Customer Validate Token Endpoint 
 * Please note that this snippet only provides a required basic API implementation, without any additional supporting code.
 * Get TRACEABLE_SITE_KEY, TRACEABLE_API_SECRET, TRACEABLE_VALIDATE_TOKEN_URL from Traceable
 */
@Slf4j
@Service
public class TraceableCaptchaValidateTokenServiceImpl
    implements TraceableCaptchaValidateTokenService {
  private final RestTemplate restTemplate;
  private final ObjectMapper objectMapper;
  @Value("${traceable.captcha.site-key:TRACEABLE_SITE_KEY}")
  private String siteKey;
  @Value("${traceable.captcha.secret:TRACEABLE_API_SECRET}")
  private String secret;
  @Value("${traceable.captcha.validate-url:TRACEABLE_VALIDATE_TOKEN_URL}")
  private String validateUrl;
  public TraceableCaptchaValidateTokenServiceImpl() {
    this.restTemplate = new RestTemplate();
    this.objectMapper = new ObjectMapper();
  }
  @Override
  public ResponseEntity<?> validateToken(String token, String remoteIp) {
    try {
      // Create headers
      HttpHeaders headers = new HttpHeaders();
      headers.setContentType(MediaType.APPLICATION_JSON);
      // Create request object
      TraceableCaptchaRequest requestData = new TraceableCaptchaRequest();
      requestData.setToken(token);
      requestData.setRemoteip(remoteIp);
      requestData.setSecret(secret);
      requestData.setSiteKey(siteKey);
      // Create request entity
      HttpEntity<TraceableCaptchaRequest> requestEntity = new HttpEntity<>(requestData, headers);
      //Request Traceable API
      ResponseEntity<String> response =
          restTemplate.postForEntity(validateUrl, requestEntity, String.class);
      // Parse the response
      TraceableCaptchaResponse captchaResponse =
          objectMapper.readValue(response.getBody(), TraceableCaptchaResponse.class);
      log.info("Traceable Captcha response: {}", captchaResponse);
      if (!captchaResponse.isValid()) {
        log.error("Traceable Captcha response is not valid: {}", captchaResponse);
        return ResponseEntity.status(response.getStatusCode()).body(captchaResponse);
      }
      // Create response headers
      HttpHeaders responseHeaders = new HttpHeaders();
      responseHeaders.setContentType(MediaType.APPLICATION_JSON);
      // Set cookie if present in the response
      if (captchaResponse.getTraceableSessionCookieString() != null
          && !captchaResponse.getTraceableSessionCookieString().isEmpty()) {
        String cookieString = captchaResponse.getTraceableSessionCookieString();
        if (cookieString.contains("=")) {
          String[] cookieParts = cookieString.split("=", 2);
          String cookieValue = cookieParts[1];
          log.info("Extracted cookie value: {}", cookieValue);
          responseHeaders.add("Set-Cookie", "traceable-session=" + cookieValue);
        }
      }
      // Return the response with headers
      return new ResponseEntity<>(captchaResponse, responseHeaders, response.getStatusCode());
    } catch (Exception e) {
      log.error("Error validating token: {}", e.getMessage(), e);
      TraceableCaptchaResponse errorResponse = new TraceableCaptchaResponse();
      errorResponse.setValid(false);
      errorResponse.setMessage("Internal server error: " + e.getMessage());
      return ResponseEntity.internalServerError().body(errorResponse);
    }
  }
}

Python

import http.server
import json
import urllib.request
import urllib.error
import urllib.parse
# Sample Implementation of Customer's Validate token endpoint
# Please note that this snippet only provides a required basic API implementation, without any additional supporting code.
# Get TRACEABLE_SITE_KEY, TRACEABLE_API_SECRET, TRACEABLE_VALIDATE_TOKEN_URL from Traceable
class SecureHTTPRequestHandler(http.server.SimpleHTTPRequestHandler):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, directory="public", **kwargs)
    def do_POST(self):
        if self.path == "/traceable/validate-token":
            self.handle_validate_token()
    def handle_validate_token(self):
        content_length = int(self.headers.get("Content-Length", 0))
        request_body = self.rfile.read(content_length) if content_length > 0 else b"{}"
        try:
            body_data = json.loads(request_body)
            token = body_data.get("token", "")
            if not token:
                self.send_error(400, "Token is required")
                return
            request_data = {
                "token": token,
                "remoteip": self.client_address[0],
                "secret": TRACEABLE_API_SECRET,
                "site-key": TRACEABLE_SITE_KEY 
            }
            data = json.dumps(request_data).encode('utf-8')
            req = urllib.request.Request(TRACEABLE_VALIDATE_TOKEN_URL, data=data, method="POST")
            req.add_header("Content-Type", "application/json")
            with urllib.request.urlopen(req) as response:
                response_bytes = response.read()
                response_text = response_bytes.decode("utf-8")
                response_data = json.loads(response_text)
                self.send_response(200)
                self.send_header("Content-Type", "application/json")
                if "traceableSessionCookieString" in response_data:
                    cookie_string = response_data["traceableSessionCookieString"]
                    cookie_string = cookie_string.encode('utf-8').decode('unicode_escape')
                    self.send_header("Set-Cookie", cookie_string)
                self.end_headers()
                self.wfile.write(response_bytes)
        except JSON.JSONDecodeError:
            self.send_error(400, "Invalid JSON")
        except urllib.error.HTTPError as e:
            self.send_error(e.code, f"Validation error: {e.reason}")
        except Exception as e:
            self.send_error(500, f"Internal server error: {str(e)}")