# 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](https://betterstack.com/docs/errors/js-tag/configure/).

## 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:

```html
[label Install JavaScript tag]
<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, as 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:

| Option | Type | Default | Description |
|---|---|---|---|
| `environment` | `string` | `undefined` | Environment name (e.g., `'production'`, `'staging'`). Passed to error tracking for filtering. |
| `release` | `string` | `undefined` | App version or release identifier. Useful for tracking regressions across deployments. |
| `autoPageview` | `boolean` | `true` | Automatically track page views. Set to `false` to track navigation manually. |
| `debug` | `boolean` | `false` | Log internal activity to the browser console. Useful during development. |

Example:

```javascript
[label Start data collection]
betterstack('init', {
  environment: 'production',
  release: '1.4.2',
});
```

## 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.

```javascript
[label Identify known 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` in the example above, they're stored alongside the user data.

Call this after sign-in. The association persists for the page session. To clear it at sign-out:

```javascript
[label Clear user at 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:

```javascript
[label Track a custom event]
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](https://betterstack.com/docs/errors/js-tag/events/).

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:

```javascript
[label Customize configuration]
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](https://docs.sentry.io/platforms/javascript/configuration/options/).

All other keys are merged with the init configuration.

This can also be managed remotely from the Frontend tab: see [Custom configuration](https://betterstack.com/docs/errors/js-tag/configure/).

## Verify installation

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

## Next steps

- [Configuration](https://betterstack.com/docs/errors/js-tag/configure/): UI settings, collection toggles, sampling, session replays, sessions, batching, and more.
- [Events reference](https://betterstack.com/docs/errors/js-tag/events/): schema of all captured events.