BugTape docs

Quickstart

Project key, hosted module, first test error.

Connect BugTape to your app and verify the first capture. One project, one key — web, iOS, React Native and server events all land in the same inbox, tagged with the platform they came from.

Prerequisites

A BugTape account at https://app.bugtape.ai/console/
A project with an API key (bt_live_*) — the Setup page mints one and shows it once

Confirm a specific web installation

In Setup, select your project and generate a key. Under Install the SDK, choose Prepare this web installation, select or create an application, and give the installation a label such as “Storefront production.” Enrollment requires a current workspace admin or manager.

Copy the generated snippet into your app. It includes the project's key and the exact registered application/installation IDs. Open the app, reproduce an error or use its BugTape button to send a report. Setup shows Capture received for this installation and Open captured evidence when that installation's first accepted web capture arrives. Samples and captures from another installation cannot complete this check.

The selected project and installation resume after a reload in the same browser tab. A lost enrollment response retries the same saved request. Full API keys are not saved in this progress state; a reloaded snippet uses a placeholder that you must replace with your saved key. A basic snippet remains available if you do not have management access, but it cannot identify a registered installation.

The dated receipt records past delivery. It does not attest a binary/device or prove current connectivity. If evidence expires or is deleted, the receipt remains and the evidence link is removed. Project/installation deletion also removes the receipt. Native and server snippets do not inherit web completion.

Web: hosted ES module

The hosted ES module is served from the same origin as the console. Add it to a browser page after applying your app's consent policy:

<script type="module">
  import { init } from 'https://app.bugtape.ai/bugtape.mjs';
  init({ apiKey: 'bt_live_your_key_here' });
</script>

The public @bugtape/sdk npm package is not currently published. Use the hosted module; do not run an npm install command for that package. Framework-specific instructions are shown in Setup. Initialize only once in a browser context and call the returned instance's destroy() when its owning surface unmounts.

A floating bug button appears in the bottom-right corner. The browser SDK records a bounded context buffer, including DOM replay, network metadata and console output, and can report uncaught errors and failed requests. Verify your own app's recording and scrubbing configuration before production use.

Option C: iOS, React Native, server

The web SDK is browser-only. Other surfaces post to the same ingest endpoint with platform set, so the inbox can tell them apart:

Surface	Start here	What you get
iOS (Swift)	BugTapeCore source package — versioned ZIP, no third-party dependency	consent-controlled handled errors/user reports, explicit breadcrumbs, offline queue and managed delivery receipt; no fatal capture or replay
React Native / Expo	`docs/examples/react-native/bugtape.ts`	global JS errors, unhandled rejections, breadcrumbs
Server / worker / cron	`docs/examples/server/curl.md`	one `POST /v1/ingest` per failure with `platform: "server"`

See platforms.md for the field mapping and what each platform shows in the console.

Try a console sample, then verify your install

On the console Setup page, step 4 has Send console sample. It creates a sample occurrence through the ingest pipeline, tagged with the platform tab you picked. This previews the inbox. It does not verify an SDK install. After installation, trigger a named error in your app and confirm that its matching occurrence arrived in the correct project.

Where is the ten-minute recording?

Open a captured issue, choose its occurrence and inspect Replay. Browser recording starts when the SDK loads. It keeps up to the configured window, subject to event and byte limits; a short session cannot contain ten minutes of history. DOM replay reconstructs captured page state. It is not screen video and cannot recover time before installation. Server-only reports and older reports with no DOM events show their recording limit explicitly.

What happens automatically

Once initialized, the SDK records:

Data	Description
DOM snapshots and mutations	DOM replay via rrweb, subject to capture and privacy limits
Network requests	Fetch, XHR, resource timing — URL, status, duration
Console output	`log`, `warn`, `error`, `info`, `debug`
Uncaught errors	`window.onerror` events with stack traces
Unhandled rejections	`unhandledrejection` events
Rage clicks	Rapid repeated clicks on the same element

All events are stored in a ring buffer (default: last 10 minutes, max 50,000 events). When a user files a report, the buffered events are attached automatically.

Configuration options

init({
  // Required
  apiKey: 'bt_live_xxx',

  // Optional
  endpoint: 'https://app.bugtape.ai/v1/ingest',  // Custom endpoint
  recordingWindow: 10,              // Buffer duration in minutes (default: 10)
  maxEvents: 50000,                 // Max events in buffer (default: 50000)
  position: 'bottom-right',         // Widget: bottom-right|bottom-left|top-right|top-left
  theme: 'dark',                    // Widget: dark|light|auto

  // Disable specific recorders
  disableDomRecording: false,
  disableNetworkRecording: false,
  disableConsoleRecording: false,

  // PII scrubbing (enabled by default)
  pii: {
    enabled: true,                  // Scrub emails, credit cards, SSNs, JWTs, etc.
  },

  // Rage click sensitivity
  rageClickSensitivity: 'medium',   // very-sensitive|medium|low

  // Callbacks
  onSuccess: (response) => { },     // After successful ingest
  onError: (error) => { },          // On submission failure
});

onSubmit replaces default ingestion. Do not add an empty callback: it would prevent reports from reaching BugTape. Use onSuccess to observe an acknowledgement without changing delivery.

Programmatic control

const bt = init({ apiKey: '...' });

// Open the report widget programmatically
bt.open();

// Get all buffered events
const events = bt.getEvents();

// Tear down the SDK
bt.destroy();

To build your own report UI, POST directly to the API with buffered events. A custom onSubmit handler is another option, but it must perform delivery itself.

const response = await fetch('https://app.bugtape.ai/v1/ingest', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-BugTape-Key': 'bt_live_your_key_here',
  },
  body: JSON.stringify({
    title: 'Checkout button unresponsive',
    description: 'User clicked checkout 5 times with no response',
    severity: 'high',
    url: window.location.href,
    userAgent: navigator.userAgent,
    viewport: `${window.innerWidth}x${window.innerHeight}`,
    events: bt.getEvents(),  // Attach buffered events
  }),
});

const result = await response.json();
// { id: "uuid", fingerprint: "abc123...", deduplicated: false, regression: false }

Verify automatic error capture

Initialize once in a local or staging browser page with your project key. Add onSuccess and onError callbacks to show the result.
Use a button handler to throw a uniquely named error, such as throw new Error('BugTape onboarding test — checkout'). Keep automatic error reporting enabled.
Wait for onSuccess; record the returned issue id and, when present, captureId. An initialization message is not an ingest acknowledgement.
Open that issue in the correct project's console. Confirm the matching occurrence, error and captured context. A console sample or a report from another client does not verify this installation.

Verify a manual report

Open the floating bug button, or call bt.open().
Enter a unique title and submit the report.
Check onSuccess and inspect that report in the console. Check replay separately; an ingest acknowledgement alone does not prove replay playback.

Next steps

SDK Reference — full configuration and method documentation
API Reference — HTTP endpoints for server-side integration
Authentication — key types, rotation, and proxy guidance
Next.js Example — hosted browser module and proxy considerations
SaaS Integration Guide — multi-tenant setup for B2B apps
Platforms — web, iOS, React Native, server: what each sends and shows
Agents — how your coding agent hears about new bugs (MCP, webhooks, polling)