Configure the JavaScript tag

All settings on this page are managed from the Frontend tab in your application's settings. Changes take effect immediately — no redeployment required.

What should we collect?

Toggle individual collection features on or off:

All features are enabled by default.

Sampling

Three independent sampling rates control how much data the JS tag collects:

Sampling is per-session, not per-event. When a new session starts, a random roll determines whether that session will track web events (and similarly for replays and errors). All events within a sampled-in session are captured; all events in a sampled-out session are dropped.

Error sampling is applied independently — a session can capture errors but not web events, or vice versa.

Data retention

Web events retention controls how long captured events are stored before automatic removal. Configurable in the Frontend tab.

Session replays

Session replays record DOM changes during a user's session, letting you visually replay exactly what they saw and did.

• Enable: Toggle Record session replays in the collection settings.
• Sampling: Configurable under Sampling of session replays. Default is 100%. Decided per-session — if selected, the entire session is recorded.
• Error context: Replays are linked to captured errors. When reviewing an error, you can watch the replay to see what led to it.

Exclude HTML elements

Exclude specific elements from both session replay recording and autocapture (click/form tracking). Useful for sensitive content like password fields or personal data.

Enter CSS selectors under Exclude HTML elements:

input[type=password]
.sensitive-data
#credit-card-form

Matching elements are:

• Blocked in replays — replaced with a placeholder in the recorded DOM.
• Excluded from autocapture — clicks and form interactions on these elements are not tracked.

Custom configuration

JavaScript code entered here runs when the tag loads. This is equivalent to calling betterstack('config', ...) in your application code (see Installation — Custom configuration), but managed remotely.

Example — the placeholder shown in the UI:

betterstack('config', {
  environment: 'production',
});

Use this to set environment, release, or pass advanced error tracking options without modifying your deployed code.

Sessions

A session groups all user activity within a continuous browsing window.

Session timeout in minutes: Sessions expire after a configurable period of inactivity. Default is 30. After the timeout elapses with no interaction, the next user action starts a new session.

Session data is stored in the browser's localStorage under the _bs key — session ID, anonymous user ID, last activity timestamp, and sampling decisions.

At session start, the JS tag captures attribution data automatically:

• UTM parameters (utm_source, utm_medium, utm_campaign, utm_term, utm_content)
• Referrer URL
• Ad click IDs (gclid, fbclid, msclkid, ttclid, li_fat_id, twclid)
• Current page URL

This data is sent with the session-start event and available for querying.

Batching

Events are batched in memory before sending to reduce network requests.

Send events at most every N seconds: Default is 1. Events are flushed at this interval.

Events are also flushed immediately when the page becomes hidden (tab switch, minimize) or on pagehide, ensuring no data is lost when the user navigates away. Events are sent as newline-delimited JSON (application/x-ndjson).

Next steps

• Installation — snippet, init options, identifying users, tracking custom events
• Getting started — overview and prerequisites
• Events reference — full schema of all captured events