API 참조

BotManager Browser Agent는 특정 기능을 통한 탐지를 수행할 수 있는 API를 제공합니다.

개요

BotManager Browser Agent는 페이지 로드 시 기본 탐지 외에도, 특정 이벤트(예: 버튼 클릭)와 함께 탐지를 수행하여 비동기 API 호출을 보호할 수 있습니다. 이를 통해 API 요청이 탐지 결과에 따라 안전하게 처리되도록 설정할 수 있습니다.

detectPage 함수

특정 이벤트 발생 시 탐지를 수행하는 함수입니다.

함수 시그니처

BotManager.detectPage(pathname, callback)

매개변수

매개변수	타입	필수	설명
pathname	string	예	탐지할 경로 (예: /api/login-endpoint)
callback	function	아니오	탐지 결과를 처리하는 콜백 함수

반환값

없음 (비동기 모드) 또는 콜백을 통한 결과 전달 (동기 모드)

사용 방법

Without Callback (비동기 모드)

비동기 모드에서는 BotManager.detectPage를 호출한 뒤, 원래의 로직(예: 로그인 로직)을 탐지와 관계없이 바로 수행합니다.

예시: 특정 버튼(로그인 버튼)을 클릭했을 때

button.addEventListener('click', () => {
    if (window.BotManager && typeof BotManager.detectPage === 'function') {
        BotManager.detectPage('/api/login-endpoint');  // 탐지 함수 호출
    }
    // 원래의 로그인 로직 수행
    performLogin();
});

특징:

• detectPage 호출 후 기존 로직(performLogin())을 그대로 실행합니다.
• botmanager-browser-agent가 로드되지 않은 경우에도 로그인 로직이 중단되지 않도록 처리합니다.

With Callback (동기 모드)

동기 모드에서는 BotManager.detectPage의 결과를 기반으로 탐지 결과가 정상이면 원래의 로직을 수행하도록 합니다.

예시: 특정 버튼(로그인 버튼)을 클릭했을 때

button.addEventListener('click', () => {
    if (window.BotManager && typeof BotManager.detectPage === 'function') {
        BotManager.detectPage('/api/login-endpoint', (result) => {
            // 탐지 결과가 정상인 경우 원래의 로그인 로직 수행
            performLogin();
        });
    } else {
        // botmanager-browser-agent.js가 로드되지 않았을 경우, 원래의 로그인 로직 수행
        performLogin();
    }
});

특징:

• botmanager-browser-agent가 로드되지 않은 경우에도 로그인 로직이 중단되지 않도록 보장합니다.

콜백 함수

콜백 함수는 탐지 결과를 처리하는 함수입니다. 탐지가 성공적으로 완료되면 콜백이 호출됩니다.

BotManager.detectPage('/api/login-endpoint', (result) => {
    // result는 탐지 결과 정보를 포함할 수 있습니다
    console.log('탐지 완료:', result);
    // 원래의 로직 수행
    performLogin();
});

Server-Side Agent와의 연동

BotManager Browser Agent는 클라이언트 측에서 XHR 및 Fetch 요청을 후킹하여 서버에서 특정 키를 기반으로 응답을 처리하도록 지원합니다. 이 기능은 특히 Server-Side Agent에서 detectApi를 사용하는 경우에 적용됩니다.

동작 설명

1. XHR 및 Fetch 후킹:

   • Browser Agent는 클라이언트 측에서 발생하는 모든 XHR 및 Fetch 요청을 후킹하여 요청과 응답을 모니터링합니다.

2. 헤더 키 확인:

   • 서버 응답 헤더에 약속된 키인 **x-botmanager-location**이 포함되어 있는 경우, 해당 값을 이용해 클라이언트가 리디렉션을 수행합니다.
   • 예를 들어, x-botmanager-location 헤더 값이 특정 URL로 설정되어 있으면, 클라이언트는 즉시 해당 URL로 이동합니다.

주요 기능

• Server-Side Agent 연동:

  • Server-Side Agent의 detectApi와 함께 사용할 때, 서버에서 탐지 결과를 클라이언트로 전달하고 특정 행동(예: Redirect)을 수행하도록 지원합니다.

• 리디렉션 처리:

  • 탐지 결과에 따라 클라이언트가 자동으로 대응하며, 보안 위협에 신속히 대처할 수 있습니다.

사용 예시

다음은 서버 응답 예시입니다:

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

Browser Agent는 이 헤더를 감지하고 자동으로 해당 URL로 리디렉션합니다.

적용 케이스

케이스 1: 클라이언트 에이전트로 페이지 탐지, 서버 에이전트로 비동기 API 탐지

• 클라이언트 에이전트는 페이지 로드 시 detectOnLoad 기능을 사용하여 페이지 단위 탐지를 수행합니다.
• 서버 에이전트는 비동기 API 호출에 대해 탐지를 수행합니다.
• 추가 설정 필요 없음: 클라이언트 에이전트는 기본적으로 cfg.detectOnLoad가 true로 설정되어 있으므로 페이지 단위 탐지의 추가 설정이 필요하지 않습니다.

케이스 2: 탐지 역할 분리

• 클라이언트 에이전트는 셀레니움 사용, 개발자 도구 활성화, 클릭 행위 분석 등 클라이언트 측 탐지 이벤트만 처리합니다.
• 서버 에이전트는 페이지 탐지와 비동기 API 호출 탐지를 모두 처리합니다.
• 설정 필요: 클라이언트 에이전트가 페이지 탐지를 수행하지 않도록 스니펫 cfg.detectOnLoad = false로 설정해야 합니다.