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.

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.13.1/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 →

Hosts and endpoints

Glossary