Capture browser incidents

Create one browser agent for each application runtime. The agent has no import-time side effects and binds listeners only after start().

Start browser capture

Pass the ingest endpoint, project key, and ingest token. The transport sends the token through x-faultatlas-token and never writes it into an envelope.

import { createAgent } from "@faultatlas/browser-agent";

const agent = createAgent({
  ingestUrl: "/api/incidents",
  projectKey: "project_demo",
  ingestToken: "your_ingest_token_here",
});

agent.start();
agent.captureException(new Error("Checkout failed"));
await agent.flush();
agent.stop();

Enable console capture, user interface breadcrumbs, host gating, and Web Vitals through explicit configuration. The agent redacts data before buffering, persistence, or transport.

What the agent captures

• Uncaught browser errors and unhandled promise rejections after start.
• Exceptions passed explicitly to the capture method.
• Optional console, network, UI breadcrumb, and Web Vitals signals that you enable in configuration.

The agent does not inspect application stores and does not record sessions or the DOM. UI breadcrumbs keep only a safe element tag; visible text and arbitrary attributes are excluded.

Delivery and privacy

Every event is normalized and redacted before it enters the bounded buffer. The agent strips query strings from captured network URLs, excludes its own ingest request, retries only retryable transport failures, and reports dropped-event counts through the configured callback.

Use a project-scoped ingest token. Never place account sessions, API keys, customer identifiers, or raw request bodies into event context.

Troubleshooting

If no incident appears, verify that start ran once, the ingest URL is reachable, the project key matches the token scope, and the current hostname passes your host gate. Flush during a controlled test and inspect the returned transport outcome rather than logging the token or full payload.

See protocol contracts for the envelope and transport outcomes.