Install the JavaScript tag

This page covers everything you need to add to your application code. All other settings are managed remotely from the Better Stack UI — see Configuration.

Install the snippet

Navigate to your application's Frontend tab and copy the <script> tag. Place it before the closing </head> tag on every page you want to instrument:

<script>
  !function(b,e,t,r){
    b[t]=b[t]||function(...args){(b[t].q=b[t].q||[]).push(args)};
    b[t].l=+new Date;
    var s=e.createElement('script'); s.async=1; s.crossOrigin='anonymous';
    s.src='https://betterstack.net/b.js?t='+r;
    (e.head||e.getElementsByTagName('head')[0]).appendChild(s);
  }(window,document,'betterstack','YOUR_TOKEN');
  betterstack('init', { environment: 'production' });
</script>

Replace YOUR_TOKEN with the token shown in the Frontend tab.

The snippet loads asynchronously and won't block page rendering. You never need to update it — the remote script (b.js) is always generated with your latest configuration.

Initialize

The betterstack('init', opts) call starts data collection. You can pass the following options:

Example:

betterstack('init', {
  environment: 'production',
  release: '1.4.2',
  debug: false,
});

Identify users

Call betterstack('user', ...) to associate the current session with a known user. Once set, all subsequent errors, events, and session replays are linked to that user.

betterstack('user', {
  id: 'user_123',
  email: 'user@example.com',
  username: 'John Doe',
  plan: 'premium',
});

id, email, and username are standard fields. You can add arbitrary custom properties (like plan above) — they're stored alongside the user data.

Call this after sign-in. The association persists for the page session. To clear (e.g., on sign-out):

betterstack('user', null);

If Auto-capture identified user events is enabled in the Frontend tab, clicks, form submissions, and other interactions are automatically captured for identified users.

Track custom events

Use betterstack('track', eventName, data) to send custom events with an arbitrary payload:

betterstack('track', 'cta-button-click', {
  button_id: 'signup_cta',
  page: '/pricing',
  variant: 'blue',
});

• eventName — a string identifying the event type.
• data — an object with any key-value pairs you want to record.

Events appear in Live tail and can be queried in dashboards. The full event schema is documented in the Events reference.

Custom events respect sampling — if the current session was sampled out of web event tracking, track calls are silently dropped. Events are also gated by the Auto-capture anonymous user events and Auto-capture identified user events toggles depending on whether a user has been identified.

Custom configuration

Use betterstack('config', ...) to set configuration options before init is called:

betterstack('config', {
  environment: 'production',
  release: 'abcdef012345',
  sentry: {
    ignoreErrors: ['TestError'],
  },
});
betterstack('init');

config must be called before init. Calling it after has no effect (a warning is logged if debug is enabled).

The sentry key passes options directly to the underlying error tracking SDK, deep-merged with defaults. Common use cases:

• ignoreErrors — array of error message patterns to suppress.
• denyUrls / allowUrls — filter errors by script URL.
• Any other supported option from the Sentry JavaScript SDK.

All other keys are merged with the init configuration.

This can also be managed remotely from the Frontend tab — see Custom configuration.

Verify installation

1. Open your application in a browser.
2. Go to the Frontend tab and check the Verify data collection section — it shows whether data has been received.
3. Alternatively, open Live tail to see events arriving in real time.

Next steps

• Configuration — UI settings: collection toggles, sampling, session replays, sessions, batching, and more
• Events reference — schema of all captured events