API Reference

BotManager Java Agent provides methods to detect page requests and API requests.

Applying Page Request Detection

Call BotManager.detectPage() to detect macro activities in HTTP requests.

Code Example:

import com.stclab.botmanager.agent.BotManager;
import java.util.HashMap;
import java.util.Map;

public class ExamplePageHandler {
    public void handleRequest(Object request, Object response) {
        Map<String, String> params = new HashMap<>();
        // When passing customId
        params.put("customId", "exampleCustomId"); // Can be optionally applied depending on the case
        boolean isAllowed = BotManager.detectPage(request, response, params);
        if (!isAllowed) {
            // No additional processing needed when detected (automatic Redirect)
            return;
        }
        // Process normal request
    }
}

Applying API Request Detection

Call BotManager.detectApi() to apply macro detection in REST API requests.

Code Example:

import com.stclab.botmanager.agent.BotManager;
import java.util.HashMap;
import java.util.Map;

public class ExampleApiHandler {
    public void handleApiRequest(Object request, Object response) {
        Map<String, String> params = new HashMap<>();
        // When passing customId
        params.put("customId", "exampleCustomId"); // Can be optionally applied depending on the case
        boolean isAllowed = BotManager.detectApi(request, response, params);
        if (!isAllowed) {
            // No additional processing needed when detected (automatic Redirect)
            return;
        }
        // Process normal request
    }
}

Applying to Interceptor

Add the logic to middleware that processes server requests as follows. Below is an example using an Interceptor.

Code Example:

import com.stclab.botmanager.agent.BotManager;
import jakarta.servlet.http.HttpServletRequest;
import jakarta.servlet.http.HttpServletResponse;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

import java.util.HashMap;
import java.util.Map;

@Component
public class ApiInterceptorWithParams implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        Map<String, String> params = new HashMap<>();
        // The following items are used to pass different values from initialization settings in specific situations
        params.put("tenantId", "exampleTenantId"); // Can be optionally applied depending on the case
        params.put("domainName", "example.com"); // Can be optionally applied depending on the case
        params.put("customId", "exampleCustomId"); // Can be optionally applied depending on the case

        boolean isAllowed = BotManager.detectApi(request, response, params);
        if (!isAllowed) {
            // No additional processing needed when detected (BotManager handles redirect)
            return false; // Stop request
        }
        return true; // Continue processing request
    }
}

Method Types

detectPage Method

detectPage is used when processing page-level requests from browsers.

Description:

• For detected requests, the server performs redirect through the Location field in HTTP response headers, which is an HTTP standard redirect method supported by all browsers.
• This method is designed to fit the general browser request processing flow because it causes page transitions.

Features:

• Mainly operates when pages load, and browsers check the Location value returned from the server and automatically perform redirect.
• Additionally, detection works without client-side configuration, so it can be easily applied.

Method Signature:

// Using only Request and Response
boolean isAllowed = BotManager.detectPage(request, response);

// Can pass additional parameters
boolean isAllowed = BotManager.detectPage(request, response, params);

Parameters:

• request: Client request object (HttpServletRequest)
• response: Server response object (HttpServletResponse)
• params: Additional information needed for detection (Map<String, String> format)
  • Example: { "tenantId": "exampleTenant", "domainName": "example.com", "customId": "user123" }

Return Value:

• true: Detection passed, can continue processing request
• false: Detection blocked, redirect is automatically performed

detectApi Method

detectApi is used when processing asynchronous API calls (e.g., XMLHttpRequest, fetch) from browsers.

Description:

• For detected requests, the server adds the agreed key X-BotManager-Location to response headers to deliver redirect information.
• detectApi is designed to work appropriately even when browsers call APIs asynchronously.

Important Notes:

• For asynchronous API calls, browsers do not automatically handle redirects through Location headers, so it must be handled manually on the client side.
• For this, botmanager-browser-agent must be applied to the browser.
  • botmanager-browser-agent hooks asynchronous calls (xhr, fetch) in the browser to detect the X-BotManager-Location header and perform appropriate redirects on the client side.
• In environments where botmanager-browser-agent is not applied, detectApi may not work properly.

Method Signature:

// Using only Request and Response
boolean isAllowed = BotManager.detectApi(request, response);

// Can pass additional parameters
boolean isAllowed = BotManager.detectApi(request, response, params);

Parameters:

• request: Client request object (HttpServletRequest)
• response: Server response object (HttpServletResponse)
• params: Additional information needed for detection (Map<String, String> format)
  • Example: { "tenantId": "exampleTenant", "domainName": "example.com", "customId": "user123" }

Return Value:

• true: Detection passed, can continue processing request
• false: Detection blocked, X-BotManager-Location header is added to response (handled by Browser Agent)