メインコンテンツまでスキップ

API参照

BotManager Browser Agentは特定機能を通じた検出を実行できるAPIを提供します。

概要​

BotManager Browser Agentはページロード時の基本検出のほか、特定イベント（例：ボタンクリック）と一緒に検出を実行して非同期API呼び出しを保護できます。これを通じてAPIリクエストが検出結果に応じて安全に処理されるように設定できます。

detectPage関数​

特定イベント発生時に検出を実行する関数です。

関数シグネチャ​

BotManager.detectPage(pathname, callback)

パラメータ​

パラメータタイプ必須説明
pathnamestringはい検出するパス（例：/api/login-endpoint）
callbackfunctionいいえ検出結果を処理するコールバック関数

戻り値​

なし（非同期モード）またはコールバックを通じた結果伝達（同期モード）

使用方法​

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：検出役割分離​

  • クライアントエージェントはSelenium使用、開発者ツール有効化、クリック行動分析などクライアント側検出イベントのみ処理します。
  • サーバーエージェントはページ検出と非同期API呼び出し検出をすべて処理します。
  • 設定必要：クライアントエージェントがページ検出を実行しないようにスニペットcfg.detectOnLoad = falseに設定する必要があります。