Skip to main content

Application of the browser agent

To use the WhaTap monitoring service, after Sign up, create a project and then apply the WhaTap browser agent to web applications.

See the following video guide.

Installing the WhaTap browser agent​

Follow the instructions on the agent installation screen to apply the WhaTap browser agent code to your web application.

WhaTap Browser Agent Installation

Data collection sampling​

The WhaTap browser agent collects data based on the user session. You can set the percentage of all sessions collected from 0 to 100.

WhaTap browser agent script​

The WhaTap browser agent is provided in the form of an inline script. Add the script code provided by the installation guide to the top in the <head> tag of any HTML page to monitor.

Select one of the following two methods to apply the agent.

  • Async (Asynchronous Load): Loads the WhaTap browser agent asynchronously in your web application.

    • It does not affect the load performance of your web application.

    • There may be missing data such as AJAX or errors that occurred before loading the browser agent.

  • Sync (Synchronous Load): Loads the WhaTap browser agent synchronously in your web application.

    • It is recommended if you want to collect all data when loading your web application.

    • It may affect the load performance of your web application.

Setting the WhaTap browser agent's options​

It sets the options to apply to the WhaTap browser agent. The options can be set in the Config object of the installation script. You can set the project access keys, percentage of all user sessions, resource domains to exclude from collection, and such.

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

Option parameters​

projectAccessKey String required

It is a project access key. You can see in the project installation guide (Management > Agent Installation).

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

pcode Number required

It is a project access key. You can see in the project installation guide (Management > Agent Installation).

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

sampleRate Number required

You can set the ratio of user sessions to be collected. You can set it from 0 to 100.

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

proxyBaseUrl String required

The URL that the agent sends collected data to. The value differs by project region, so use the value from the script provided on the Management > Agent installation screen of the WhaTap monitoring service.

This is not the same as the agent script file address (<script src>). If you set it incorrectly, the collected data is not sent.

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

ignorePageUrls Array<string | RegExp> optional

It is a list of page URLs to exclude from collection. String matching is performed using the startsWith method.

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

It is a list of resource URLs to exclude from collection. String matching is performed using the startsWith method.

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

It is a list of browser errors to exclude from collection. String matching is performed using the includes method.

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

collectUserClick Boolean optional

Default false

It can collect user click events. For the method to find the collected data, see the following.

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

sessionReplaySampleRate Number optional

Default 0

It is the ratio of sessions to collect the session replay data. You can set from 0 to 100 for user sessions to collect.

For example, if sampleRate is set to 50 and sessionReplaySampleRate to 20, 50% of all sessions are collected, and for only 20% of those sessions, the session replay data is collected.

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

sessionReplayMaskAllTexts Boolean optional

Default true

If you set the value to false, all text data is collected without masking.

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

sessionReplayMaskAllInputs Boolean optional

Default true

If you set the value to false, the data in all input fields is collected without masking.

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

sessionReplayCollectAllBrowser Boolean optional

Default false

The session replay data is collected even in the browsers that do not support requestIdleCallback(). e.g. Safari, Safari on iOS

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

ignoreStatusZero Boolean optional

Default false

This option excludes data from collection when the status code of the AJAX request is 0.

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

  • For more information about the session replay, see the following.

  • For more information about the browsers that support session replay collection, see the following.

Other initialization options​

In addition to the option parameters above, some options require a decision based on your runtime environment. The default values and behavior confirmed in the canonical documents of the browser agent source repository (README.md, docs/webview-integration.md) are as follows.

OptionTypeDefaultDescription
isWebViewbooleanfalseTransport switch that delegates data transmission to the WhaTap mobile agent
webViewHttpFallbackbooleantrueFalls back to standard HTTP transmission when the bridge cannot be reached. Supported from browser agent 3.2.0
allowIframebooleanfalseAllows execution inside an iframe. If false, initialization inside an iframe is blocked
enableHealthCheckbooleanfalsePerforms a project health check at initialization. The agent stops if it fails
collectAgentErrorbooleanfalseCollects the agent's internal errors
hashRoutingbooleanfalseCollects screen transitions of hash routing in the #/path form as route changes
ignoreLocalhostbooleanfalseExcludes requests targeting localhost from collection
cookieSecurebooleanfalseSets the secure flag on the agent cookie

Options that can be set only at initialization​

The following options are determined only once, at initialization. To change a value, modify the installation script of the page and then reload the page.

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

The agent's own communication is not collected​

Requests whose address contains /rum/ or /whatap/ are regarded by the agent as its own communication and excluded from collection. If your service API path contains one of these strings, those requests do not appear in the resource data or the AJAX data.

Using it in a mobile app WebView​

When you collect the WebView screens of a mobile app together with the WhaTap mobile agent, separate settings are required on the browser agent side as well. For the installation and WebView registration procedure carried out in the app, see Applying the Android agent and Applying the iOS agent. This section covers only the browser agent settings applied to the web page.

The integration requires the v2 bundle​

WebView integration works on browser agent 3.2.0 or later. The bridge for the integration is not included in the v1 bundle, so specify the script address with the v2 path.

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

You can check the version of the applied file with the WhatapRUM.VERSION value.

isWebView is case-sensitive​

The option name that turns the integration on is isWebView, with an uppercase W. If you write it with a lowercase v, as in isWebview, it is treated as an unknown key and ignored without any warning. In that case data is still collected, but the integration does not take effect and the dashboard classifies it as a regular browser. Cases have been reported where the snippet copied from the installation guide screen is filled in as isWebview, so check the spelling after pasting it.

OptionDefaultRecommendedDescription
proxyBaseUrl-RequiredIf it is not set, data transmission stops even when the integration is applied
sampleRate-100 while verifying the setupOn a 0–100 scale. The criterion differs from that of the mobile agent
isWebViewfalsetrueDelegates transmission to the mobile agent
webViewHttpFallbacktrueKeep the defaultSet it to false on a closed network where the WebView cannot reach the collection server
enableHealthCheckfalseKeep falseOn failure the whole agent stops without a retry
collectAgentErrorfalseKeep falseCommunicates directly with the collection server without going through the mobile agent bridge
sessionReplayCollectAllBrowserfalsetrue when using replayRecords regardless of the WebView engine type
sessionReplaySampleRate0Specify a value when using replayThe default 0 collects nothing
allowIframefalsetrue when loading inside an iframeIf it is not set, initialization inside an iframe is blocked
ignoreLocalhostfalseKeep falseA cause of missing collection in Capacitor and Ionic environments
hashRoutingfalsetrue when using hash routingCollects #/path screen transitions
cookieSecurefalsetrue only when the screen address is https://Cookies may be invalidated on capacitor://, ionic://, and the like
Note

The health check performed by enableHealthCheck communicates directly with the collection server. If there is no response or it fails, the browser agent stops without a retry, so leave the default false as is in a WebView environment. Remote settings delivered over the same path are also unavailable when the integration is applied. Specify all the options you need directly in the installation script.

Next steps​

  • Collecting custom events

    To identify the web service issues and improve user experience through browser monitoring, it provides an interface that allows developers and operators to additionally collect desired events that occur on web pages. For more information about custom events, see the following.

  • Setting the actual user ID

    In the browser monitoring, you can collect data by setting the user ID via the actual user's login ID or email address. You can check the user session performance and event information based on the actual login ID, and then check the browser's errors to identify problems. For more details, see the following.

  • Configuring the session replay

    Session replay is a feature that allows to record and replay all events performed by users on the website. This feature allows you to reproduce user behaviors such as clicking, scrolling, typing, and page switching. This helps you understand exactly how users actually interact with the website. For more details, see the following.

  • Starting the monitoring

    Go to WhaTap Monitoring Service and then start the browser monitoring. Select a created project and then go to Dashboard > Browser Monitoring Dashboard. You can see the monitoring status. For more information about Browser Monitoring Dashboard, see the following.

Last updated on