@d2c2d/capture

Embeddable capture SDK for collecting bug reports from websites.

Install

npm install @d2c2d/capture

bun add @d2c2d/capture

Quick Start

1. Create a public key

In Crikket, go to Settings -> Public Keys.

Create one public key per owned website or app surface, then add the exact origins where the widget is allowed to run, for example:

• https://example.com
• https://www.example.com
• http://<your-host-ip>:9100 (run bun run env:sync locally to see the IP in generated .env.example)

Copy the generated public key after saving. Public keys are safe to embed in client-side code.

2. Initialize the widget on your site

Call init() from a browser entrypoint in your app:

import { init } from "@d2c2d/capture"

init({
  key: "crk_your_public_key",
  host: "https://api.crikket.io",
})

If you are using Crikket Cloud, host defaults to https://api.crikket.io. If you are self-hosting Crikket, pass your own app origin:

import { init } from "@d2c2d/capture"

init({
  key: "crk_your_public_key",
  host: "https://crikket.your-company.com",
})

That mounts the floating launcher and lets users capture a screenshot or screen recording, fill out the report form, and submit directly from your site.

Pass debugUi: true on init() to show a small fixed panel with live capture state (overlayOpen, view, busy, domPickerActive, etc.) for troubleshooting.

Usage

init() in any browser app

Use init() when you want the smallest integration surface. Run it once in a browser-only entrypoint.

import { init } from "@d2c2d/capture"

init({
  key: "crk_your_public_key",
  host: "https://api.crikket.io",
})

Available options:

• key: required public key from Crikket Settings -> Public Keys
• host: optional Crikket API origin; defaults to https://api.crikket.io
• autoMount: mount automatically on init; defaults to true
• mountTarget: custom element to mount into; defaults to document.body
• submitPath: custom bug report base path; defaults to /api/embed/bug-reports
• zIndex: custom widget stacking order
• debugger.captureElementAttributes: optional white-list of DOM attribute names to capture into action event metadata (default: none). Example: ["aria-label", "data-openreplay-label", "id"]
• debugger.captureElementText: optional element text capture mode for debugger action events (default: none). Example: "innerText"

submitPath is used as the base path for the capture control-plane flow. By default the SDK derives these routes from /api/embed/bug-reports:

• /api/embed/capture-token
• /api/embed/bug-report-upload-session
• /api/embed/bug-report-finalize

The package also exports runtime controls if you need them:

import { close, init, open } from "@d2c2d/capture"

init({
  key: "crk_your_public_key",
})

open()
close()

DOM picker and Markdown bundle

Use the floating Pick DOM button (above Report Issue) in any capture step — it stays available while the report overlay is open. Double-click anywhere on the page exits pick mode without enqueueing an extra pick (the first click of a double-click is cancelled when the second click is detected).

Each single-click records the target element’s outerHTML (the SDK ignores the widget chrome via data-crikket-capture-card, the main launcher, and the floating Pick DOM launcher).

While pick mode is active, the SDK blocks host pointer interaction by setting inline pointer-events: none on a block root and restores the previous inline value on exit. Mark your app content root with data-crikket-dom-pick-block (recommended on <main>). If the attribute is absent, the SDK falls back to the first <main> element, then document.body.

<main data-crikket-dom-pick-block>
  <!-- your app -->
</main>

Pick hit-testing uses document.elementsFromPoint, so highlighting and recording still work while the block root has pointer-events: none. The pick HUD also offers 开启点击 / 关闭点击 to temporarily allow host interaction without exiting pick mode (default: blocking on).

Snapshots are capped in the UI (currently 60). On submit, all picks are merged into one UTF-8 Markdown document (# DOM, ## DOM n, fenced html blocks) and uploaded as a single picked_dom fragment (text/html blob), alongside optional supplementary images. Picks only see the document the widget runs in; content inside cross-origin iframes or closed shadow roots is not reachable.

Capturing element attributes in debugger action events

By default, the SDK captures action events (like click/input/change) but does not include DOM attributes in the payload.

If you want more reliable UI element identification in bug report actions, you can configure a white-list of DOM attribute names to collect into action.metadata.attributes:

import { init } from "@d2c2d/capture"

init({
  key: "crk_your_public_key",
  debugger: {
    captureElementAttributes: ["aria-label", "data-openreplay-label", "id"],
  },
})

Notes:

• Only attributes listed in the white-list are captured.
• Missing or empty attributes are omitted (no empty string placeholders).
• Attribute values are size-bounded (long values are truncated).
• target selection remains unchanged; attributes are an additive metadata enhancement.

Capturing element text in debugger action events

By default, the SDK does not capture element text in action metadata.

If you want more readable UI element identification in bug report actions, you can configure element text capture:

import { init } from "@d2c2d/capture"

init({
  key: "crk_your_public_key",
  debugger: {
    captureElementText: "innerText",
  },
})

This adds two optional fields to action.metadata:

• text: the visible text (innerText) of the interactive element (e.g. closest button/link/input ancestor).
• targetText: the visible text (innerText) of the raw event.target element.

Notes:

• Missing or empty text values are omitted (no empty string placeholders).
• Text values are size-bounded (long values are truncated).
• target selection remains unchanged; text is an additive metadata enhancement.

Next.js 15.3+ with instrumentation-client.ts

For Next.js 15.3 and newer, initialize the SDK once in instrumentation-client.ts so it runs globally in the browser.

import { init } from "@d2c2d/capture"

const capturePublicKey = process.env.NEXT_PUBLIC_CRIKKET_KEY

if (capturePublicKey) {
  init({
    key: capturePublicKey,
    host: process.env.NEXT_PUBLIC_CRIKKET_HOST ?? "https://api.crikket.io",
  })
}

Example file:

// instrumentation-client.ts
import { init } from "@d2c2d/capture"

const capturePublicKey = process.env.NEXT_PUBLIC_CRIKKET_KEY

if (capturePublicKey) {
  init({
    key: capturePublicKey,
    host: process.env.NEXT_PUBLIC_CRIKKET_HOST ?? "https://api.crikket.io",
  })
}

Recommended environment variables:

NEXT_PUBLIC_CRIKKET_KEY=crk_your_public_key
NEXT_PUBLIC_CRIKKET_HOST=https://api.crikket.io

If you are using Crikket Cloud, you can omit NEXT_PUBLIC_CRIKKET_HOST and just pass the public key.

React integration

If you prefer a React-native integration point, use the plugin from @d2c2d/capture/react and mount it once near your app root.

"use client"

import { CapturePlugin } from "@d2c2d/capture/react"

export function AppProviders(): React.JSX.Element {
  return (
    <>
      <CapturePlugin
        host="https://api.crikket.io"
        publicKey="crk_your_public_key"
      />
      {/* rest of your app */}
    </>
  )
}

With environment variables:

"use client"

import { CapturePlugin } from "@d2c2d/capture/react"

export function CaptureProvider(): React.JSX.Element | null {
  const publicKey = process.env.NEXT_PUBLIC_CRIKKET_KEY

  if (!publicKey) {
    return null
  }

  return (
    <CapturePlugin
      host={process.env.NEXT_PUBLIC_CRIKKET_HOST ?? "https://api.crikket.io"}
      publicKey={publicKey}
    />
  )
}

CapturePlugin accepts the same options as init(), except it uses publicKey instead of key.

Notes

• Public keys should be scoped per website or app surface.
• Allowed origins should be exact HTTP(S) origins, including local development origins you want to permit.
• The SDK must run in a browser environment.
• Browser permission prompts for screen capture are expected platform behavior.