> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appsignal.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AppSignal for Browser configuration options

<Note>
  Browser monitoring is a beta [AppSignal Labs](/labs) feature. The
  `@appsignal/browser` package is published under the `beta` tag on npm, and its
  configuration and API may still change between beta releases. Share feedback
  in our [Discord community](https://discord.gg/EjF6ykYx63).
</Note>

Every option is passed to `init()` as a single object. Only `key` is required. Configuration is read once, when `init()` runs, so changing an option means deploying a new build.

<CodeGroup>
  ```js appsignal.js theme={null}
  import { init } from "@appsignal/browser";

  init({
    key: "<YOUR_FRONTEND_API_KEY>",
    endpoint: "https://appsignal-endpoint.net",
    active: process.env.NODE_ENV === "production",
    appVersion: "<YOUR_APP_REVISION>",
    errors: { sampleRate: 1.0 },
    breadcrumbs: { console: false },
    privacy: {
      queryParamsAllowlist: ["utm_*", "page"],
      networkBlocklist: ["api.stripe.com/**"],
      dom: { blockElement: ["#card-form"] },
    },
  });
  ```
</CodeGroup>

## `key`

* **Type:** `string`
* **Required**

Your application's [Front-end API key](/browser/installation#find-your-front-end-api-key), which is meant to be exposed in public. It is not one of the Push keys your back-end integrations use.

## `endpoint`

* **Type:** `string`
* **Default value:** the current page's origin

Where data is sent. Set it to `https://appsignal-endpoint.net` unless you proxy AppSignal traffic through your own domain, in which case leaving it unset posts to your own origin. A trailing slash is stripped.

Errors are sent to `POST /ingest/browser/errors`, and web vitals to `POST /ingest/browser`. The key rides along as an `api_key` query parameter, which is worth knowing if you maintain a `connect-src` allowlist.

## `active`

* **Type:** `boolean`
* **Default value:** `true`

The main on/off switch. When it is `false`, `init()` returns straight away and does nothing at all: it changes nothing on the page, starts no timers, and makes no requests. Every other function does nothing too, so you can call them anywhere without checking first.

Set this from your build environment so development, test, and CI runs send nothing:

<CodeGroup>
  ```js JavaScript theme={null}
  init({
    key: "<YOUR_FRONTEND_API_KEY>",
    active: process.env.NODE_ENV === "production", // or import.meta.env.PROD
  });
  ```
</CodeGroup>

## `appVersion`

* **Type:** `string`

The release tag, commit SHA, or deploy ID of the running build. Errors and web vitals are tagged with it, which drives the version filters in the Browser views and the [sourcemap](/browser/error-tracking#sourcemaps) lookup for backtraces. Read more in our [deploy markers guide](/application/markers/deploy-markers).

## `beforeError`

* **Type:** `(event: IncomingError) => IncomingError | null`

Called once per error, before anything else happens to it. Return `null` to drop the error, or mutate fields on the event to redact them. Read more in [filtering errors](/browser/privacy#filtering-errors-and-breadcrumbs).

This callback must be synchronous. A returned promise is detected, logged as a `console.error`, and the error is dropped.

## `beforeBreadcrumb`

* **Type:** `(breadcrumb: Breadcrumb) => Breadcrumb | null`

Runs once for every breadcrumb, as it is recorded. Return `null` to throw it away, or change `message` and `data` to remove sensitive text. This runs often, so keep it fast.

## `errors.enabled`

* **Type:** `boolean`
* **Default value:** `true`

Whether errors are reported at all. When `false`, the SDK still listens for them but sends nothing.

## `errors.sampleRate`

* **Type:** `number` between `0` and `1`
* **Default value:** `1.0`

What share of errors to report. The choice is made at random for each error, so `0.25` reports roughly a quarter of them. This happens before the [rate limits](/browser/error-tracking#rate-limits) and before `beforeError` runs.

## `breadcrumbs.network`

* **Type:** `boolean`
* **Default value:** `true`

Record a breadcrumb for every `fetch` and `XMLHttpRequest` call. Request and response bodies are never captured.

## `breadcrumbs.console`

* **Type:** `boolean`
* **Default value:** `true`

Record a breadcrumb for `console.warn` and `console.error`. `console.log` is not patched.

## `breadcrumbs.clicks`

* **Type:** `boolean`
* **Default value:** `true`

Record a breadcrumb when a user selects an element.

## `breadcrumbs.longTasks`

* **Type:** `boolean`
* **Default value:** `true`

Record a breadcrumb when the main thread is blocked for more than 50 ms.

## `privacy.queryParamsAllowlist`

* **Type:** `string[]`
* **Default value:** `[]`

The query parameters to keep in recorded URLs. Use `*` to match several names at once, so `"utm_*"` keeps every UTM parameter. The default list is empty, which removes all of them. Read more in [privacy and filtering](/browser/privacy#urls-and-query-parameters).

## `privacy.networkBlocklist`

* **Type:** `string[]`
* **Default value:** `[]`

Glob URL patterns whose requests are never recorded as breadcrumbs. Matched against host and path. The request still happens. It is not recorded.

## `privacy.dom.maskText`

* **Type:** `string[]`
* **Default value:** `[]`

CSS selectors whose text content is replaced with `[masked]` in `click` breadcrumbs. The breadcrumb is still recorded, so you keep the fact that an interaction happened.

## `privacy.dom.blockElement`

* **Type:** `string[]`
* **Default value:** `[]`

CSS selectors whose interactions are not recorded at all. Use this for card forms and other fields that should never surface.

## API reference

Every function below does nothing until `init()` has run with `active` set to `true`.

| Function                                      | Description                                                                                              |
| --------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `init(config)`                                | Start collection. Call once, as early as possible. Subsequent calls are ignored.                         |
| `captureError(error, context?)`               | Report a caught error. Read more in [error tracking](/browser/error-tracking#reporting-errors-manually). |
| `addBreadcrumb({ category, message, data? })` | Add your own breadcrumb to the timeline.                                                                 |
| `setRouteTemplate(template)`                  | Declare the route the user is on, for example `/users/:id`. Pass `null` to clear it.                     |
| `setTags(tags)`                               | Attach tags to every error reported from now on. Merges with existing tags.                              |
| `clearTags()`                                 | Remove all tags. Tags outlive a reload, so call this on sign-out.                                        |
| `destroy()`                                   | Stop all collection for the rest of the page. Does not persist across a reload.                          |