API 참조

BotManager Java Agent는 페이지 요청과 API 요청을 탐지하는 메서드를 제공합니다.

페이지 요청 탐지 적용

HTTP 요청 시 매크로 활동을 감지하려면 BotManager.detectPage()를 호출합니다.

코드 예제:

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<>();
        // customId를 전달할 경우
        params.put("customId", "exampleCustomId"); // 경우에 따라서 선택적으로 적용 가능
        boolean isAllowed = BotManager.detectPage(request, response, params);
        if (!isAllowed) {
            // 탐지된 경우 추가 처리 불필요 (자동 Redirect)
            return;
        }
        // 정상 요청 처리
    }
}

API 요청 탐지 적용

REST API 요청 시 매크로 탐지를 적용하려면 BotManager.detectApi()를 호출합니다.

코드 예제:

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<>();
        // customId를 전달할 경우
        params.put("customId", "exampleCustomId"); // 경우에 따라서 선택적으로 적용 가능
        boolean isAllowed = BotManager.detectApi(request, response, params);
        if (!isAllowed) {
            // 탐지된 경우 추가 처리 불필요 (자동 Redirect)
            return;
        }
        // 정상 요청 처리
    }
}

Interceptor에 적용

서버 요청을 처리하는 미들웨어에 다음과 같이 로직을 추가합니다. 아래는 Interceptor를 사용한 예제입니다.

코드 예제:

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<>();
        // 아래 항목은 초기화 설정값을 특정 상황에 다른 값으로 전달시 사용
        params.put("tenantId", "exampleTenantId"); // 경우에 따라서 선택적으로 적용 가능
        params.put("domainName", "example.com"); // 경우에 따라서 선택적으로 적용 가능
        params.put("customId", "exampleCustomId"); // 경우에 따라서 선택적으로 적용 가능

        boolean isAllowed = BotManager.detectApi(request, response, params);
        if (!isAllowed) {
            // 탐지된 경우 추가 처리 불필요 (BotManager가 리다이렉트 처리)
            return false; // 요청 중단
        }
        return true; // 요청을 계속 처리
    }
}

메서드 종류

detectPage 메서드

detectPage는 브라우저에서 페이지 단위의 요청을 처리할 때 사용됩니다.

설명:

• 탐지된 요청에 대해 서버는 HTTP 응답 헤더의 Location 필드를 통해 리다이렉트를 수행하며, 이는 HTTP 표준 리다이렉트 방식으로 모든 브라우저에서 지원됩니다.
• 이 방식은 페이지 전환이 발생하기 때문에 일반적인 브라우저 요청 처리 흐름에 맞춰 설계되었습니다.

특징:

• 주로 페이지 로드 시 동작하며, 브라우저가 서버에서 반환된 Location 값을 확인하고 자동으로 리다이렉트를 수행합니다.
• 추가적으로, 클라이언트 단의 설정 없이 탐지가 동작하므로 간단하게 적용할 수 있습니다.

메서드 시그니처:

// Request와 Response만 사용
boolean isAllowed = BotManager.detectPage(request, response);

// 추가 매개변수 전달 가능
boolean isAllowed = BotManager.detectPage(request, response, params);

매개변수:

• request: 클라이언트 요청 객체 (HttpServletRequest)
• response: 서버 응답 객체 (HttpServletResponse)
• params: 탐지에 필요한 추가 정보 (Map<String, String> 형태)
  • 예: { "tenantId": "exampleTenant", "domainName": "example.com", "customId": "user123" }

반환값:

• true: 탐지 통과, 요청을 계속 처리할 수 있음
• false: 탐지 차단, 자동으로 리다이렉트가 수행됨

detectApi 메서드

detectApi는 브라우저에서 비동기 API 호출(예: XMLHttpRequest, fetch)을 처리할 때 사용됩니다.

설명:

• 탐지된 요청에 대해 서버는 응답 헤더에 약속된 키 X-BotManager-Location을 추가하여 리다이렉트 정보를 전달합니다.
• detectApi는 브라우저가 비동기적으로 API를 호출한 상황에서도 적절히 동작하도록 설계되었습니다.

중요 사항:

• 비동기 API 호출의 경우 브라우저는 Location 헤더를 통한 리다이렉트를 자동으로 처리하지 않기 때문에, 클라이언트 측에서 이를 수동으로 처리해야 합니다.
• 이를 위해 반드시 **botmanager-browser-agent**가 브라우저에 적용되어 있어야 합니다.
  • botmanager-browser-agent는 브라우저에서 비동기 호출(xhr, fetch)을 후킹(hooking)하여 X-BotManager-Location 헤더를 감지하고 클라이언트 측에서 적절한 리다이렉트를 수행합니다.
• botmanager-browser-agent가 적용되지 않은 환경에서는 detectApi가 정상적으로 동작하지 않을 수 있습니다.

메서드 시그니처:

// Request와 Response만 사용
boolean isAllowed = BotManager.detectApi(request, response);

// 추가 매개변수 전달 가능
boolean isAllowed = BotManager.detectApi(request, response, params);

매개변수:

• request: 클라이언트 요청 객체 (HttpServletRequest)
• response: 서버 응답 객체 (HttpServletResponse)
• params: 탐지에 필요한 추가 정보 (Map<String, String> 형태)
  • 예: { "tenantId": "exampleTenant", "domainName": "example.com", "customId": "user123" }

반환값:

• true: 탐지 통과, 요청을 계속 처리할 수 있음
• false: 탐지 차단, X-BotManager-Location 헤더가 응답에 추가됨 (Browser Agent가 처리)