Integrate BugCatch

What BugCatch needs from you

Three values, and every integration on this site uses the same three. Sections 1 to 3 below are where each one comes from.

1. Create your workspace

A workspace is your company. It owns the plan, the members, the API keys and the projects. You will make one, once.

1. Sign up

   Go to app.bugcatch.sphoro.com and create an account with your work email. A six-digit code is emailed to that address; type it back to confirm you can read the mailbox.

2. Bind an authenticator — this is not optional

   The moment the code is accepted you are asked to scan a QR code with an authenticator app (1Password, Authy, Google Authenticator, anything TOTP). There is no way past this screen and no window in which the account exists without a second factor.

   Save the recovery codes it gives you. They are shown once. Losing the phone without them means losing the account.

3. Name the workspace

   You land in the dashboard on the Free plan: one project, two members, seven days of retention. Nothing to pay and no card to enter.

What each plan actually gives you

Capture, the widget, the extension, trackers, the REST API and the reporter's thread are on every plan, Free included. So is retention — the window above is enforced by a job that deletes, not merely a number on a page.

Two notes on the paid rows. AI analysis is bring-your-own-key: the plan opens the door, and an Anthropic key in Settings → Integrations → AI Provider walks through it. Automation rules can be configured on any plan and simply do not fire below Team, so you can set them up while evaluating and see exactly what you would get.

Projects are metered on Team because a project is what costs to run: its own retention window, its own duplicate index and its own knowledge base. The first is covered by the member price, and each one after it is $9 a month ($7.50 billed yearly). On Enterprise, projects sit inside the contract and are not metered.

Changing plan keeps everything you already have. Limits apply when you create something new, so a workspace over its new cap is blocked from adding more rather than losing data. Moving onto Team converts existing data in place, and encryption converts back the same way if you leave.

2. Create a project

A project is one product, or one environment of one product. Reports land in exactly one, and it is the unit that carries integrations, automation rules and the reporter sign-in setting.

1. Open Projects

   In the dashboard sidebar, go to Projects → New project.

2. Give it a name and a key

   The name is for humans. The short key (say WEB) prefixes each report's reference, so a bug reads as WEB-3F2A9B01 in a standup rather than as a UUID.

3. Copy the project id

   Open the project, then Project Settings → General. Project ID is listed under the form, with a copy button beside it. This is the projectId every snippet on this site asks for — not the short key, and not the name.

3. Issue an API key

The key authenticates the SDK, the extension and the REST API. It belongs to the workspace and works for every project in it.

1. Open the keys screen

   Workspace Settings → API Keys → Create key.

2. Name it after where it will live

   marketing-site, ios-webview, ci. When you revoke one in a year, the name is the only thing that tells you what breaks.

3. Copy the secret now

   It is shown once. Only a hash and the first few characters are stored, so there is no screen anywhere that can show it to you again — losing it means revoking and issuing another.

bc_live_4f9a2c1e8b7d0a63f5e2c9b184d7a0e3
└──┬──┘└───────────────┬───────────────┘
   │                    └─ 32 random hex characters
   └─ always this prefix; there is no test-mode key

4. Choose how reports get filed

Four ways in. They are not alternatives to each other — most teams end up running two, because the person who finds a bug is sometimes a developer and sometimes a customer.

Whichever you pick, connect your tracker afterwards so the bug lands where your team already works — see Integrations.

5. Quickstart: first report in 5 minutes

The shortest honest path. Paste this into any HTML page you can load in a browser — your product, or a scratch file on your desktop — with your own two values swapped in.

<!-- Pin the version. Without one the CDN serves whatever is latest, so a
     future release changes behaviour on a site nobody redeployed. -->
<script src="https://unpkg.com/@sphoro/bugcatch-web-sdk@0.17.0/dist/bugcatch.umd.js"></script>
<script>
  BugCatch.init({
    apiBase: 'https://api.bugcatch.sphoro.com',
    apiKey: 'bc_live_…',        // Workspace Settings → API Keys
    projectId: '…',               // Project Settings → General
  });
</script>

Load the page. You should now be able to work through this list:

• A Report a bug button sits in the bottom-right corner.
• Clicking it opens a panel with a title, a description and an attach row.
• Filling in a title and pressing Send report closes it with a confirmation.
• The report is in the dashboard within a second or two, under the project you named.
• Opening it shows a Console and a Network tab with what the page was doing.

If it did not appear, the answer is almost certainly in SDK troubleshooting — every failure mode that page lists writes something to the browser console.

6. What to do next, in order

A first report proves the wiring. These are the things that make it useful, roughly in the order they pay off.

1. Tell BugCatch who is reporting

   One call — BugCatch.identify({ email }). It threads a person's reports together, and it is the address the "your issue is fixed" mail goes to. Without it every report is anonymous and nobody hears back. How →

2. Connect your tracker

   Jira, GitHub, Linear or Slack, per project, about two minutes each. Then the bug arrives where your team already looks instead of in a second place they have to remember. How →

3. Get the extension to the people who triage

   Support and QA file better reports with it than with the widget, because Rewind catches the thing that already happened. How →

4. Decide what must never leave the browser

   Credentials in URLs are stripped before they are ever buffered, with no configuration. Anything else specific to your product — an internal endpoint, a customer identifier — is a beforeSend filter and a server-side redaction rule. How →

5. Close the loop

   Reporters see status changes and replies inside your app, and can write back with files and voice notes. It is on by default once identify() has an email — mostly this step is deciding whether to render it yourself. How →

What happens after the click

Four steps, and only the first one is yours. Everything after it runs on our side, in the background, and usually finishes in seconds.

1. Capture

   The extension or the in-app button takes a screenshot, a recording or Rewind, and collects the console, network and environment in the same moment.

2. Upload

   Media goes straight to object storage over a presigned URL, so a 60 MB recording never queues behind the API. The report is created the instant the upload lands. The REST API page walks through the same presign, PUT and reference flow.

3. Enrich

   Background workers run the AI analysis, redact secrets, transcode the WebM recording to MP4 so it plays anywhere your team pastes it, and push the issue to your tracker.

4. Triage

   It appears in the queue ranked by severity, with the video, the logs and the repro on one screen. Assign it, comment, resolve it or share a read-only link.

Rewind is the one capture that starts before the click. Once enabled, the extension keeps a rolling buffer of the last two minutes of screen activity in an isolated offscreen document, capped to bound memory, and discards anything older. Nothing is uploaded until someone presses Rewind; if nobody does, nothing leaves the machine.

Security and data handling

A recording of a checkout flow contains a real cart, a real session and sometimes a real card field. Encryption and redaction are the default, not an enterprise upsell.

Encrypted at rest

On Team and Enterprise, every content column is sealed with AES-256-GCM under a per-workspace data key, itself wrapped by a master key. Ciphertext is self-describing, so a plan change or a half-finished backfill stays readable. Redaction runs before encryption, so the sealed row never contains the secret.

Credentials stripped on every plan

Bearer tokens, API keys, cookies and presigned URLs are removed in the browser, again at the API, and once more when an older report is read back, so a public share link cannot leak a key captured before the rule existed. Password fields are masked by default, you can mark elements to blur, and card numbers and your own patterns layer on top.

Workspace-scoped access

Every tenant resource is checked against membership. Projects are public to the workspace or restricted to an explicit member list, enforced inside the guard so no endpoint can ship without the check.

Deliberate sharing

A session is private by default and inherits its project's setting. Share one publicly and the API serves a purpose-built payload at a token URL, never the internal record. The reporter's own thread is built the same way, from a separate, reviewed object: it carries severity, the fact that the report has an owner, and shared replies, and never who the assignee is.

Roles that mean something

Owner, admin, member and viewer, applied per workspace with an audit trail on every triage action. A report can only be edited by the people who own it. SSO/SAML and SCIM provisioning come with Enterprise.

Retention that actually deletes

A sweep prunes past the window on every plan (7 days on Free, 90 on Team, 365 on Enterprise), taking the knowledge-base passages first, then the stored media, then the row. It runs regardless of anything else you configure, because it is the promise the plan already made. Custom windows, data residency and self-hosted deployment are on Enterprise.

Your model, your key

AI analysis uses your own Claude (Anthropic) or ChatGPT (OpenAI) key, billed to your account at cost. The model sees the redacted report: stack traces, failed requests and environment. Without a key, reports are still captured in full and simply are not analysed.

Self-hosting

On Enterprise, BugCatch runs in your own cloud or a dedicated private instance, with your object storage and your key management. The stack is Postgres, Redis and a Node API, deployable with Docker Compose or your own orchestration.

Hosts and endpoints

Glossary