API Reference

BotManager Browser Agent provides APIs to perform detection through specific functions.

Overview

In addition to basic detection when the page loads, BotManager Browser Agent can perform detection along with specific events (e.g., button clicks) to protect asynchronous API calls. This allows API requests to be safely processed according to detection results.

detectPage Function

A function that performs detection when a specific event occurs.

Function Signature

BotManager.detectPage(pathname, callback)

Parameters

Parameter	Type	Required	Description
pathname	string	Yes	Path to detect (e.g., /api/login-endpoint)
callback	function	No	Callback function to process detection results

Return Value

None (async mode) or result delivery via callback (sync mode)

Usage

Without Callback (Async Mode)

In async mode, after calling BotManager.detectPage, the original logic (e.g., login logic) is performed immediately regardless of detection.

Example: When a specific button (login button) is clicked

button.addEventListener('click', () => {
    if (window.BotManager && typeof BotManager.detectPage === 'function') {
        BotManager.detectPage('/api/login-endpoint');  // Call detection function
    }
    // Perform original login logic
    performLogin();
});

Features:

• After calling detectPage, it executes the existing logic (performLogin()) as is.
• Handles so that login logic is not interrupted even if botmanager-browser-agent is not loaded.

With Callback (Sync Mode)

In sync mode, based on the result of BotManager.detectPage, if the detection result is normal, it performs the original logic.

Example: When a specific button (login button) is clicked

button.addEventListener('click', () => {
    if (window.BotManager && typeof BotManager.detectPage === 'function') {
        BotManager.detectPage('/api/login-endpoint', (result) => {
            // Perform original login logic if detection result is normal
            performLogin();
        });
    } else {
        // Perform original login logic if botmanager-browser-agent.js is not loaded
        performLogin();
    }
});

Features:

• Ensures that login logic is not interrupted even if botmanager-browser-agent is not loaded.

Callback Function

The callback function is a function that processes detection results. The callback is called when detection is successfully completed.

BotManager.detectPage('/api/login-endpoint', (result) => {
    // result may contain detection result information
    console.log('Detection completed:', result);
    // Perform original logic
    performLogin();
});

Integration with Server-Side Agent

BotManager Browser Agent supports hooking XHR and Fetch requests on the client side to process responses from the server based on specific keys. This feature is particularly applied when using detectApi in Server-Side Agent.

Operation Description

1. XHR and Fetch Hooking:

   • Browser Agent hooks all XHR and Fetch requests occurring on the client side to monitor requests and responses.

2. Header Key Check:

   • If the server response header contains the agreed key x-botmanager-location, the client performs redirection using that value.
   • For example, if the x-botmanager-location header value is set to a specific URL, the client immediately navigates to that URL.

Key Features

• Server-Side Agent Integration:

  • When used together with Server-Side Agent's detectApi, it supports delivering detection results from the server to the client and performing specific actions (e.g., Redirect).

• Redirection Handling:

  • The client automatically responds according to detection results, enabling rapid response to security threats.

Usage Example

The following is a server response example:

HTTP/1.1 200 OK
Content-Type: application/json
x-botmanager-location: https://cdn-botmanager.stclab.com/deny/index.html?...

Browser Agent detects this header and automatically redirects to that URL.

Application Cases

Case 1: Page Detection with Client Agent, Async API Detection with Server Agent

• Client Agent performs page-level detection using the detectOnLoad feature when the page loads.
• Server Agent performs detection on asynchronous API calls.
• No additional configuration needed: Client agent has cfg.detectOnLoad set to true by default, so no additional configuration for page-level detection is needed.

Case 2: Detection Role Separation

• Client Agent only handles client-side detection events such as Selenium usage, developer tools activation, click behavior analysis.
• Server Agent handles both page detection and asynchronous API call detection.
• Configuration needed: Client agent must be configured with cfg.detectOnLoad = false in the snippet so it does not perform page detection.