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:
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:
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:
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:
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:
// 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.
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.