Set up BugShot

Install

1. Sign in and create a project. You get a project key.
2. Paste the snippet before the closing </body> tag on every page.
3. Press Send a test report on the project page, or open your site and tap the ladybug.

<script src="https://bugshot-cloud.thatfellowinc.workers.dev/bugshot.js"
        data-endpoint="https://bugshot-cloud.thatfellowinc.workers.dev/i/YOUR_PROJECT_KEY"
        defer></script>

Frameworks

The script tag works everywhere. If you would rather start it from your own code:

React or Next.js

// app/layout.tsx (Next.js App Router)
import Script from 'next/script'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Script src="https://bugshot-cloud.thatfellowinc.workers.dev/bugshot.js"
          data-endpoint="https://bugshot-cloud.thatfellowinc.workers.dev/i/YOUR_PROJECT_KEY"
          strategy="afterInteractive" />
      </body>
    </html>
  )
}

Vue or Nuxt

// nuxt.config.ts
export default defineNuxtConfig({
  app: {
    head: {
      script: [{
        src: 'https://bugshot-cloud.thatfellowinc.workers.dev/bugshot.js',
        'data-endpoint': 'https://bugshot-cloud.thatfellowinc.workers.dev/i/YOUR_PROJECT_KEY',
        defer: true,
      }],
    },
  },
})

Any bundler

import { init, identify } from 'bugshot'

init({ endpoint: 'https://bugshot-cloud.thatfellowinc.workers.dev/i/YOUR_PROJECT_KEY' })
identify({ id: user.id, plan: user.plan })

Options

Set them as attributes on the script tag, or as camelCase keys passed to init().

JavaScript API

BugShot.open()                                   // open the reporter yourself
BugShot.close()
BugShot.identify({ id: 'usr_88', plan: 'pro' })  // who is reporting
BugShot.setContext({ flags: ['new-checkout'] })  // app state for every report
BugShot.destroy()                                // remove it and restore patched globals

Use data-launcher="none" and call BugShot.open() from your own "Report a problem" menu item.

Privacy markup

<div data-bugshot-mask>Blurred in the screenshot</div>
<div data-bugshot-ignore>Left out of the screenshot entirely</div>

The classes bugshot-mask and bugshot-ignore work the same way.

Destinations

Every report is saved to your inbox. On a project's page you can also forward them:

• Slack: an incoming webhook URL. Each new report posts with the screenshot and the technical details.
• GitHub Issues: a repository and a fine-grained token with Issues read and write. A new bug opens one GitHub issue; if a resolved bug comes back, BugShot comments on it.
• Linear: a personal API key and a team id. A new bug opens one Linear issue.
• Webhook: any URL that accepts JSON, optionally signed.

Secrets are encrypted before they are stored and are never shown again.

Webhook payload

POST https://your-app.example/bugshot
content-type: application/json
x-bugshot-signature: sha256=<hex HMAC of the raw body, using your signing secret>

{
  "project": "Pantry",
  "issue": { "url": "...", "title": "...", "reportCount": 3 },
  "screenshotUrl": "https://.../s/...",
  "report": { "message": "...", "page": {...}, "env": {...},
              "console": [...], "network": [...], "breadcrumbs": [...] }
}

Verify the signature by computing an HMAC SHA-256 of the raw request body with your secret and comparing it to the header in constant time.