Docs▸Browser SDK

Configuration

The options init takes, how to report errors yourself, and how to filter and scrub events before they leave the browser. Everything here applies to the React and Next.js packages too.

Options

Every option init takes, with its default:

main.ts
init({
  apiKey: "[YOUR_API_KEY]", // required: a browser API key
  appName: "storefront", // required
  environment: "production", // required
  appVersion: "2026.11.05-1", // your release
  endpoint: "https://ingest.vigilon.io",
  ignoreErrors: [], // more errors to drop
  denyUrls: [], // more script URLs whose errors are dropped
  beforeSend: (event) => event, // edit or drop each event
  breadcrumbs: {}, // see Breadcrumbs
  beforeBreadcrumb: (breadcrumb) => breadcrumb,
  sampleRate: 1, // the fraction of errors to send
  maxEventsPerPage: 100,
  debug: false, // log SDK diagnostics to the console
});

appName and environment take 1 to 100 letters, digits, and . _ : / -. Without appVersion, Vigilon cannot tell which release introduced an error, and the SDK warns once. Before 0.2.24, appName and appVersion were called serviceName and serviceVersion. The old names keep working until 0.3.0, with a warning in the console.

Report errors yourself

Report an error you catch, and describe who and what it affected:

settings.ts
import { captureException, setTag, setUser } from "@vigilon/browser";

try {
  await saveSettings();
} catch (error) {
  captureException(error); // the event ID, or null when it was not sent
}

setUser({ id: "user_8f2c" }); // an opaque ID, never an email address
setTag("plan", "pro");

captureException accepts any thrown value; a value that is not an Error becomes the message. An error's cause chain is kept up to five levels. A setUser ID that looks like an email address is dropped, and so are tags whose key looks like a credential.

Pages

Vigilon groups an error's affected pages by route template, such as /users/:id, so a page with IDs in its URL still counts as one page. Without a template, it derives one from the URL path, replacing segments that look like IDs. If your router knows the template, set it on every navigation:

router.ts
import { setRoute } from "@vigilon/browser";

setRoute("/users/:id"); // the template, never the URL; null clears it

The React SDK does this for you with TanStack Router and React Router.

Filter noise

Some noise is dropped by default: Script error. from cross-origin scripts, failed and aborted network requests (Failed to fetch, NetworkError when attempting to fetch resource, Load failed, AbortError), ResizeObserver loop warnings, and errors thrown by browser extensions. The same error repeating within a minute is sent once, so an error loop cannot flood your project.

Drop more with ignoreErrors, matched against the message and against type: message, and denyUrls, matched against the URL of the script that threw. A string matches anywhere in the text; a regular expression is tested as it is:

main.ts
init({
  // ...
  ignoreErrors: ["Non-Error promise rejection captured", /^ChunkLoadError/],
  denyUrls: [/googletagmanager\.com/, "https://widget.example.com/"],
});

Edit or drop events

beforeSend sees each event before it is sent. Return it, an edited event, or null to drop it. An error's message is also the first line of its stack, and each error in its cause chain has a message and stack of its own, so scrub every one of them:

main.ts
// Email addresses, but not the @ in a script URL such as /@scope/package@1.2.3/.
const scrub = (text: string) =>
  text.replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, "[email]");

init({
  // ...
  beforeSend(event) {
    const { exception } = event;
    exception.message = scrub(exception.message);
    if (exception.stack) exception.stack = scrub(exception.stack);
    for (const cause of exception.cause ?? []) {
      cause.message = scrub(cause.message);
      if (cause.stack) cause.stack = scrub(cause.stack);
    }
    return event;
  },
});

Leave the stack's URLs alone: Vigilon reads the stack frames from them, so a pattern that also rewrites a URL loses that frame's source location.

Error messages are sent as they are

A message is free text, so it can contain whatever your code put in it, and Vigilon cannot scrub it reliably. If your messages can carry personal data, scrub them in beforeSend as above, or return null to drop the event. Console breadcrumbs are scrubbed separately, in beforeBreadcrumb.

What the SDK removes

The page URL and every URL in a stack trace lose their query string, fragment, and any user:password@. The session ID is a random value in sessionStorage, one per tab, and the SDK sets no cookies. Vigilon applies the same rules again when it receives an event. Breadcrumbs follow the rules in the Breadcrumbs guide.

Delivery

Events are batched and sent with fetch. When the page is hidden or unloaded, queued events are sent with keepalive, so they outlive the page. The SDK retries only on HTTP 429, HTTP 503, or a network failure, honours Retry-After, and gives up on an event after five attempts or 30 minutes. A retry that arrives within an hour of the first attempt is counted once.

flush() sends queued events now, and close() flushes and stops capturing. Both resolve true when everything was sent.