# Quickstart

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:

```html
<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](./swift.md) — 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`](./examples/react-native/bugtape.ts) | global JS errors, unhandled rejections, breadcrumbs |
| Server / worker / cron | [`docs/examples/server/curl.md`](./examples/server/curl.md) | one `POST /v1/ingest` per failure with `platform: "server"` |

See [platforms.md](./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

```typescript
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

```typescript
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();
```

## Manual report submission (no widget)

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.

```typescript
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

1. Initialize once in a local or staging browser page with your project key. Add `onSuccess` and `onError` callbacks to show the result.
2. Use a button handler to throw a uniquely named error, such as `throw new Error('BugTape onboarding test — checkout')`. Keep automatic error reporting enabled.
3. Wait for `onSuccess`; record the returned issue `id` and, when present, `captureId`. An initialization message is not an ingest acknowledgement.
4. 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

1. Open the floating bug button, or call `bt.open()`.
2. Enter a unique title and submit the report.
3. 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](./sdk-reference.md) — full configuration and method documentation
- [API Reference](./api-reference.md) — HTTP endpoints for server-side integration
- [Authentication](./authentication.md) — key types, rotation, and proxy guidance
- [Next.js Example](./examples/nextjs/README.md) — hosted browser module and proxy considerations
- [SaaS Integration Guide](./saas-integration-guide.md) — multi-tenant setup for B2B apps
- [Platforms](./platforms.md) — web, iOS, React Native, server: what each sends and shows
- [Agents](./agents.md) — how your coding agent hears about new bugs (MCP, webhooks, polling)