Skip to main content
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.
If you are adding a new application to AppSignal, follow the installation guide first.

​
Find your Front-end API key

Browser monitoring uses your application’s Front-end API key, listed under “Front-end error monitoring” on the “Push & deploy” page of your application’s settings. This key is app-specific, so a staging and a production app each have their own. It is meant to be exposed in public, so it is safe to include in your front-end bundle. It is not one of the Push keys your back-end integrations use. Those are on the same page, listed as the Organization Push key and the App environment Push key, and they are write-only keys that must stay secret. If you ever need to replace the Front-end API key, that page has a button to cycle it. Cycling generates a new key and invalidates the old one in a single step, and you cannot undo it, so deploy the new key promptly. Anything still sending the old key stops reporting in the meantime.

​
Install the package

While browser monitoring is in beta, install from the beta tag. Without it, package managers resolve to the latest stable release, and there is not one yet.

​
Initialize the SDK

Call init() once, as early in the page lifecycle as you can. Anything that throws before init() runs is not captured. Create an appsignal.js file next to your application’s entry point:
Then import that file as the first import in your entry point, before your application code and before other libraries:
Three of those options matter on the first install:
  • active ties collection to your build environment, so development, test, and CI runs stay quiet. When it is false, init() 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.
  • appVersion is the release tag, commit SHA, or deploy ID of the running build. Errors and web vitals are tagged with it, which is what makes the version filters and sourcemap lookups work.
  • endpoint is where data is sent. Use https://appsignal-endpoint.net unless you proxy AppSignal traffic through your own domain. When you leave it out, the SDK posts to the current origin, which is the setting you want if you do proxy.
For the full list, see the configuration options.

​
Install without a bundler

If you add JavaScript to your pages with a plain <script> tag rather than building it with a bundler, use the UMD build. It provides the same functions on a global called AppsignalBrowser:
Pin the version in the URL rather than using a floating tag, so a new release cannot change what your users download.

​
Report the current route

Single-page applications should tell the SDK which route template the user is on, for example /users/:id rather than /users/42:
Call it every time your router navigates. Both errors and web vitals are grouped by whatever route you report. A template keeps a thousand order pages together, instead of splitting them into a thousand routes with one visit each. If you never call it, AppSignal works out a template from the URL itself by replacing anything that looks like an ID. That works, but the groups it produces are rougher than the ones you get from telling it directly. For React Router, Next.js, and other React setups, see AppSignal for Browser with React.

​
Verify the installation

  1. Deploy a build with active set to true, or temporarily set active: true in development.
  2. Open your application and throw an error from the browser console, for example setTimeout(() => { throw new Error("AppSignal test error") }). Throwing from the console directly is caught by the console itself and never reaches window.
  3. Open the Errors view in the Browser section of your application in AppSignal. The error arrives within a few seconds.
Web vitals take longer to appear. They are batched and flushed when the page is hidden or the route changes, so navigate away or switch tabs before checking the Performance view. If nothing arrives, work through the troubleshooting page.

​
Content Security Policy

If your application sends a Content Security Policy header, add the AppSignal endpoint to connect-src, or requests are blocked:

​
Assets hosted on a CDN

When a script loaded from another domain throws an error, the browser refuses to share the details. Your page sees only the message Script error., with no stack trace and no line number. There is nothing there to debug, so the SDK throws those away. To get the real errors from scripts on a CDN, serve them with an Access-Control-Allow-Origin header and add the crossorigin attribute to the script tags:
📖 Continue with our installation guide.

​
Uninstall

  1. Remove the import "./appsignal" line from your entry point, and delete appsignal.js.
  2. Remove @appsignal/browser from your package.json, then run npm install or yarn install to update your lockfile. Alternatively, run npm uninstall @appsignal/browser or yarn remove @appsignal/browser.
  3. Commit and deploy. Your application stops sending browser data as soon as the new build is live.
  4. Optionally, remove the app in AppSignal.
To stop collection for the rest of the current page without a redeploy, call destroy(). It takes effect immediately, but does not persist: the next page load starts collecting again.
📖 Continue with our uninstall guide.