AppSignal for Browser configuration options

Browser monitoring is a beta AppSignal 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.

Pass configuration to init() as one object. Only key is required. A second init() call is ignored until you call destroy(). Most applications change options in their next build.

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>",
  tracePropagationTargets: ["api.example.com/**"],
  errors: { sampleRate: 1.0 },
  breadcrumbs: { console: false },
  privacy: {
    queryParamsAllowlist: ["utm_*", "page"],
    networkBlocklist: ["api.stripe.com/**"],
    dom: { blockElement: ["#card-form"] },
  },
});

`key`

Type: string
Required

Your application’s 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. If you proxy AppSignal traffic through your domain, leave it unset to use the current 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 for the first init() call. When false, initialization returns without changing the page, starting timers, or making requests. A second init() call cannot switch off an SDK that is already running. 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:

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

`appVersion`

Type: string

The release tag, commit SHA, or deploy ID of the running build. It tags errors and web vitals for the Browser views’ version filters. It also selects the sourcemaps for backtraces. Read more in our deploy markers guide.

`serviceName`

Type: string
Default value: "Browser"

AppSignal uses this value as the service label for browser errors in a trace. For example, serviceName: "Checkout UI" shows Checkout UI instead of the default Browser in the trace timeline. Use a different value for each front end you monitor. The SDK sends it with every error report. See distributed tracing for Browser.

`tracePropagationTargets`

Type: string[]
Default value: []

Use this list to choose which API requests carry a traceparent header. Each pattern needs a host and a path. For example, ["api.example.com/**"] matches every path on api.example.com. api.example.com alone matches nothing. If a matching request returns a 5xx response or times out, the SDK reports a browser error. To see back-end spans in its trace, instrument the receiving service to read the header. The default empty list adds no traceparent headers. See distributed tracing for Browser for setup and examples.

`beforeError`

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

Called for errors that pass sampling and the global rate limit, before an error breadcrumb or report is created. Return null to drop the error, or change its fields to redact them. Read more in filtering errors. 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 and before beforeError runs.

`breadcrumbs.network`

Type: boolean
Default value: true

Record breadcrumbs for fetch and XMLHttpRequest calls, except canceled requests. This option does not control the initial document-load breadcrumb. The SDK does not read request or response bodies.

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

`privacy.networkBlocklist`

Type: string[]
Default value: []

Glob URL patterns for fetch and XMLHttpRequest calls that are not recorded as breadcrumbs or failed request errors. Matched against host and path. The calls still happen. This option does not filter the initial document-load breadcrumb.

`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

Except for init(), these functions do nothing until the SDK has initialized with active: true.

Function	Description
`init(config)`	Start collection. Call once, as early as possible. Subsequent calls are ignored.
`captureError(error)`	Report a caught error. The optional context argument is not included in ordinary error reports in this beta. Read more in error tracking.
`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.
`flush()`	Send buffered web vitals now.
`destroy()`	Flush pending data and stop collection. Another `init()` call can start it again, including on the same page.

SDKs & telemetry

Language SDKs

Telemetry tools

AppSignal for Browser configuration options

`key`

`endpoint`

`active`

`appVersion`

`serviceName`

`tracePropagationTargets`

`beforeError`

`beforeBreadcrumb`

`errors.enabled`

`errors.sampleRate`

`privacy.queryParamsAllowlist`

`privacy.networkBlocklist`

`privacy.dom.maskText`

`privacy.dom.blockElement`

API reference

​key

​endpoint

​active

​appVersion

​serviceName

​tracePropagationTargets

​beforeError

​beforeBreadcrumb

​errors.enabled

​errors.sampleRate

​breadcrumbs.network

​breadcrumbs.console

​breadcrumbs.clicks

​breadcrumbs.longTasks

​privacy.queryParamsAllowlist

​privacy.networkBlocklist

​privacy.dom.maskText

​privacy.dom.blockElement

​API reference

`key`

`endpoint`

`active`

`appVersion`

`serviceName`

`tracePropagationTargets`

`beforeError`

`beforeBreadcrumb`

`errors.enabled`

`errors.sampleRate`

`breadcrumbs.network`

`breadcrumbs.console`

`breadcrumbs.clicks`

`breadcrumbs.longTasks`

`privacy.queryParamsAllowlist`

`privacy.networkBlocklist`

`privacy.dom.maskText`

`privacy.dom.blockElement`

API reference