ブラウザエージェントの適用

WhaTap Browser Monitoringサービスを使用するには、会員登録後、プロジェクトを作成し、WebアプリケーションにWhaTap Browser Monitoringエージェントを適用する必要があります。

次の動画ガイドを参照してください。

WhaTap Browser Monitoringエージェントのインストール

エージェントのインストール画面の指示に従って、Webアプリケーションに適用するWhaTap Browser Monitoringエージェントのコードを適用します。

WhaTap Browser Monitoringエージェントのインストール

データ収集サンプリング

WhaTap Browser Monitoringエージェントは、ユーザーセッションを基準にデータを収集します。収集する全体セッションの割合を0から100の範囲で設定できます。

WhaTap Browser Monitoringエージェントスクリプト

WhaTap Browser Monitoringエージェントは、インラインスクリプトの形式で提供します。インストールガイドで提供するスクリプトコードを、モニタリング対象のすべてのHTML ページの<head>タグの先頭に追加します。

次の2つの方法のいずれかを選択して、エージェントを適用します。

Async(非同期ロード): WebアプリケーションにWhaTap Browser Monitoringエージェントを非同期形式でロードします。
- ウェブアプリケーションのロード性能に影響しません。
- Browser Monitoringエージェントがロードされる前に発生したAJAX、エラーなどのデータが欠落する可能性があります。
Sync(同期ロード): WebアプリケーションにWhaTap Browser Monitoringエージェントを同期形式でロードします。
- ウェブアプリケーションのロード時にすべてのデータを収集することをお勧めします。
- ウェブアプリケーションのロードに影響を与える可能性があります。

WhaTap Browser Monitoringエージェントのオプション設定

WhaTap Browser Monitoringエージェントに適用するオプションを設定します。オプションは、インストールスクリプトのConfigオブジェクトで設定できます。プロジェクトアクセスキー、ユーザーセッション全体の割合、収集から除外リソースドメインなどを設定できます。

config example
config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  ignoreOrigins: [ 'https://ignore-site.com/', /^(https?://)([^/]*)(ignore-site.io)(/)(.*)/i ],
}

オプションパラメータ

projectAccessKey String required

プロジェクトアクセスキーです。プロジェクトインストールのご案内(管理 > エージェントインストール)で確認できます。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

pcode Number required

プロジェクトアクセスキーです。プロジェクトインストールのご案内(管理 > エージェントインストール)で確認できます。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

sampleRate Number required

収集するユーザーセッションの割合を設定できます。 0から100まで設定できます。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

proxyBaseUrl String required

エージェントが収集したデータを転送するURLです。プロジェクトのリージョンによって値が異なるため、WhaTapモニタリングサービスの管理 > エージェントインストール画面で提供するスクリプトの値をそのまま使用してください。

エージェントスクリプトファイルのアドレス（<script src>）とは異なる値です。この値を誤って設定すると、収集データが転送されません。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
}

ignorePageUrls Array<string | RegExp> optional

収集から除外するページURLの一覧です。文字列のマッチングはstartsWith方式で行われます。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  ignorePageUrls: ["https://test.webpage.com/", "http://localhost:2003/page1/", /^.localhost.$/i]
}

ignoreResources Array<string | RegExp> optional

収集から除外するリソースURLの一覧です。文字列のマッチングはstartsWith方式で行われます。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  ignoreResources: ["https://test.web.com/yard/api/flush", "http://localhost:2003/whatap-browser-agent.js",  /^.\/path1\/api.$/i]
}

ignoreErrors Array<string | RegExp> optional

収集から除外するブラウザエラーの一覧です。文字列のマッチングはincludes方式で行われます。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  ignoreErrors: ["cannot read", "cors", "basic"]
}

collectUserClick Boolean optional

既定値false

ユーザークリックイベントを収集できます。収集したデータを確認する方法は次の文書を参照してください。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  collectUserClick: true
}

sessionReplaySampleRate Number optional

既定値0

セッションリプレイデータを収集するセッションの割合です。収集対象ユーザーのセッションのうち、0から100まで設定できます。

例えば、sampleRateを50に設定しsessionReplaySampleRateを20に設定すると、全体セッションの50%が収集対象となり、そのうち20%のセッションでのみセッションリプレイデータを収集します。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50
}

sessionReplayMaskAllTexts Boolean optional

既定値 true

値をfalseに設定すると、マスキング処理なしですべてのテキストデータを収集します。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50, 
  sessionReplayMaskAllTexts: false
}

sessionReplayMaskAllInputs Boolean optional

既定値 true

値をfalseに設定すると、マスキング処理なしですべて入力(Input)フィールド領域のデータを収集します。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50, 
  sessionReplayMaskAllInputs: false
}

sessionReplayCollectAllBrowser Boolean optional

既定値false

requestIdleCallback()に対応しないブラウザでもセッションリプレイデータを収集します。例え、Safari、Safari on iOS

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}"
  sessionReplaySampleRate: 50, 
  sessionReplayCollectAllBrowser: true
}

ignoreStatusZero Boolean optional

既定値false

AJAXリクエストのステータスコードが0の場合、該当データを収集から除外するオプションです。

config: {
  projectAccessKey: {project_access_key},
  pcode: {pcode},
  sampleRate: 100,
  proxyBaseUrl: "{proxy_base_url}",
  ignoreStatusZero: true
}

ノート

セッションリプレイについての詳細は、次の文書を参照してください。
セッションリプレイ収集に対応するブラウザの詳細は、次の文書を参照してください。

その他の初期化オプション

前述のオプションパラメータのほかに、実行環境に応じて判断が必要なオプションがあります。ブラウザエージェントのソースリポジトリの正本ドキュメント（README.md、docs/webview-integration.md）で確認した初期値と動作は次のとおりです。

Option	Type	Default	Description
`isWebView`	`boolean`	`false`	データ送信をWhaTapモバイルエージェントに委任する送信経路スイッチ
`webViewHttpFallback`	`boolean`	`true`	ブリッジに到達できない場合、標準HTTP送信にフォールバック。ブラウザエージェント3.2.0から対応
`allowIframe`	`boolean`	`false`	iframe内での実行を許可。`false`の場合、iframe内部で初期化がブロックされる
`enableHealthCheck`	`boolean`	`false`	初期化時にプロジェクトのヘルスチェックを実行。失敗するとエージェントが停止
`collectAgentError`	`boolean`	`false`	エージェント内部のエラーを収集
`hashRouting`	`boolean`	`false`	`#/パス`形式のハッシュルーティングによる画面遷移をルート変更として収集
`ignoreLocalhost`	`boolean`	`false`	localhost宛てのリクエストを収集対象から除外
`cookieSecure`	`boolean`	`false`	エージェントのCookieに`secure`フラグを指定

初期化時にのみ設定できるオプション

次のオプションは初期化の時点で一度だけ判定します。値を変更するには、ページのインストールスクリプトを修正したうえでページを再読み込みする必要があります。

isWebView · webViewHttpFallback · allowIframe · enableHealthCheck · collectAgentError · hashRouting · pageLoadEndPoint · maxPageLoadTime · cookieSecure

エージェント自体の通信は収集しません

アドレスに/rum/または/whatap/が含まれるリクエストは、エージェントが自分自身の通信とみなして収集対象から除外します。サービスのAPIパスにこの文字列が含まれている場合、該当するリクエストはリソースデータおよびAJAXデータに表示されません。

モバイルアプリのWebViewで使用する場合

モバイルアプリのWebView画面をWhaTapモバイルエージェントと併せて収集する場合は、ブラウザエージェント側にも別途設定が必要です。アプリ側で行うインストールとWebViewの登録手順は、Androidエージェントの適用ドキュメントおよびiOSエージェントの適用ドキュメントを参照してください。この節では、Webページに適用するブラウザエージェントの設定のみを扱います。

連携にはv2バンドルが必要です

WebView連携はブラウザエージェント3.2.0以上で動作します。連携用のブリッジはv1バンドルには含まれていないため、スクリプトのアドレスをv2のパスで指定してください。

<script src="https://repo.whatap-browser-agent.io/rum/prod/v2/whatap-browser-agent.js"></script>

適用したファイルのバージョンはWhatapRUM.VERSIONの値で確認できます。

isWebViewは大文字と小文字を区別します

連携を有効にするオプション名はisWebViewであり、Wが大文字です。isWebviewのように小文字のvで記述すると、不明なキーとして処理され警告なしに無視されます。この場合、データは収集されますが連携は行われず、ダッシュボードでは通常のブラウザとして分類されます。インストール案内画面からコピーしたスニペットがisWebviewで入力される事例が報告されているため、貼り付けた後に表記を確認してください。

WebView環境の推奨設定

Option	Default	Recommended	Description
`proxyBaseUrl`	-	必須設定	未設定の場合、連携を適用してもデータ送信が停止する
`sampleRate`	-	適用確認中は`100`	0～100のスケール。モバイルエージェントとは基準が異なる
`isWebView`	`false`	`true`	送信をモバイルエージェントに委任
`webViewHttpFallback`	`true`	初期値を維持	WebViewから収集サーバーにアクセスできない閉域網の場合は`false`
`enableHealthCheck`	`false`	`false`を維持	失敗時に再試行なしでエージェント全体が停止する
`collectAgentError`	`false`	`false`を維持	モバイルエージェントのブリッジを経由せず収集サーバーと直接通信する
`sessionReplayCollectAllBrowser`	`false`	リプレイ使用時は`true`	WebViewエンジンの種類にかかわらず録画
`sessionReplaySampleRate`	`0`	リプレイ使用時は値を指定	初期値`0`では収集しない
`allowIframe`	`false`	iframe内で読み込む場合は`true`	未設定の場合、iframe内部で初期化がブロックされる
`ignoreLocalhost`	`false`	`false`を維持	Capacitor・Ionic環境で収集漏れの原因になる
`hashRouting`	`false`	ハッシュルーティング使用時は`true`	`#/パス`の画面遷移を収集
`cookieSecure`	`false`	画面のアドレスが`https://`の場合のみ`true`	`capacitor://`・`ionic://`などではCookieが無効化されることがある

ノート

enableHealthCheckで実行するヘルスチェックは、収集サーバーと直接通信します。応答がない場合や失敗した場合は再試行なしでブラウザエージェントが停止するため、WebView環境では初期値のfalseをそのままにしてください。同じ経路で配信されるリモート設定も、連携の適用時には使用できません。必要なオプションはすべてインストールスクリプトに直接指定してください。

次のステップ

ユーザー定義イベントを収集する

Browser Monitoringを通じてウェブサービスの問題点を把握し、ユーザー体験を改善するために、ウェブページで発生するイベントのうち、開発者と運営者が希望するイベントを追加で収集できるインターフェースを提供します。ユーザー定義イベントを収集する方法の詳細については、次の文書を参照してください。
実際のユーザーIDを設定する

Browser Monitoringでは、実際のユーザーIDやEメールなどでユーザーIDを設定し、データを収集できます。実際のログインIDに基づいてユーザーセッションの性能とイベントの情報やブラウザのエラー情報を確認して問題を把握できます。詳細については、次の文書を参考にしてください。
セッションリプレイを設定する

セッションリプレイは、ユーザーがウェブサイトで行うすべてのイベントを記録し、再生できる機能です。この機能により、クリック、スクロール、入力、ページ切り替えなどのユーザー行動を再現できます。これにより、ユーザーが実際にウェブサイトとどのように相互作用するかを、正確に把握できます。詳細については、次の文書を参照してください。
モニタリングの開始

WhaTapモニタリングサービスページに移動し、Browser Monitoringを開始します。先に作成したプロジェクトを選択しダッシュボード > ブラウザモニタリングメニューに移動します。モニタリング状況を確認できます。ブラウザモニタリングメニューの詳細については、次の文書を参照してください。

WhaTap Browser Monitoringエージェントのインストール​

データ収集サンプリング​

WhaTap Browser Monitoringエージェントスクリプト​

WhaTap Browser Monitoringエージェントのオプション設定​

オプションパラメータ​

その他の初期化オプション​

初期化時にのみ設定できるオプション​

エージェント自体の通信は収集しません​

モバイルアプリのWebViewで使用する場合​

連携にはv2バンドルが必要です​

isWebViewは大文字と小文字を区別します​

WebView環境の推奨設定​

次のステップ​

WhaTap Browser Monitoringエージェントのインストール

データ収集サンプリング

WhaTap Browser Monitoringエージェントスクリプト

WhaTap Browser Monitoringエージェントのオプション設定

オプションパラメータ

その他の初期化オプション

初期化時にのみ設定できるオプション

エージェント自体の通信は収集しません

モバイルアプリのWebViewで使用する場合

連携にはv2バンドルが必要です

isWebViewは大文字と小文字を区別します

WebView環境の推奨設定

次のステップ