API 참조

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

페이지 요청 탐지 적용

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

코드 예제:

using BotManagerDotNetAgent.Domain;
using System.Collections.Generic;

namespace MyApplication
{
    public class ExamplePageHandler {
        public void HandleRequest(object request, object response) {
            // customId를 전달할 경우
            var params = new Dictionary<string, string> {
                {"customId", "exampleCustomId"} // 경우에 따라서 선택적으로 적용 가능
            };

            // 추가 할 params가 없다면 bool isAllowed = BotManager.DetectPage(request, response); 형태로 호출 가능
            bool isAllowed = BotManager.DetectPage(request, response, params);
            if (!isAllowed) {
                // 탐지된 경우 추가 처리 불필요 (자동 Redirect)
                return;
            }
            // 정상 요청 처리
        }
    } 
}

API 요청 탐지 적용

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

코드 예제:

using BotManagerDotNetAgent.Domain;
using System.Collections.Generic;

namespace MyApplication
{
    public class ExampleApiHandler {
        public void HandleApiRequest(object request, object response) {
            // customId를 전달할 경우
            var params = new Dictionary<string, string> {
                {"customId", "exampleCustomId"} // 경우에 따라서 선택적으로 적용 가능
            };

            // 추가 할 params가 없다면 bool isAllowed = BotManager.DetectApi(request, response); 형태로 호출 가능
            bool isAllowed = BotManager.DetectApi(request, response, params);
            if (!isAllowed) {
                // 탐지된 경우 추가 처리 불필요 (자동 Redirect)
                return;
            }
            // 정상 요청 처리
        }
    } 
}

메서드 종류

DetectPage 메서드

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

설명:

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

특징:

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

메서드 시그니처:

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

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

매개변수:

• request: 클라이언트 요청 객체 (HttpRequest | HttpListenerRequest)
• response: 서버 응답 객체 (HttpResponse | HttpListenerResponse)
• params: 탐지에 필요한 추가 정보 (Dictionary<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만 사용
bool isAllowed = BotManager.DetectApi(request, response);

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

매개변수:

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

반환값:

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