API reference

@fixback/sdk reference

The complete API of @fixback/sdk. For a narrative walkthrough, see the Web SDK guide.

Exports

ts

import { init, Fixback, LAUNCH_EVENT } from "@fixback/sdk";const fixback = await init({ key: "pk_live_…" });await fixback.signIn();   // open Connectfixback.destroy();

init(options) — boots the SDK; returns a Promise resolving to an instance.
Fixback — a module-level object with signIn() / signOut() / identity() that delegate to the most recent init instance, so a host app can start a Connect from its own UI.
LAUNCH_EVENT — the name of the fixback:launch event the SDK dispatches when the launcher is activated — see the launch event.

init(options)

Returns a promise that resolves to an instance. All options other than key are optional.

Option	Type	Default	Description
`key`	`string`	—	The publishable key of one of your Project's environments (an identifier, not a secret). It decides which environment reports land in and whose Gate applies — there is no environment option.
`apiUrl`	`string`	`https://api.fixback.dev`	The Fixback API origin. Override for a self-hosted or local deployment.
`hostIdentity`	`string`	—	A Host identity token minted by your server with a secret key of the same environment as `key`, for trusted reporters that already have a login.
`anonymousId`	`string`	a persisted per-browser id	A stable first-party id for an anonymous reporter.
`target`	`HTMLElement`	`document.body`	Where to mount the launcher.
`reduceMotion`	`boolean`	`false`	Still the launcher's pulse and motion, and the Walkthrough recorder's (a short fade stands in). The OS reduced-motion setting does the same on its own.
`draggable`	`boolean`	`true`	Let the visitor drag the Feedback pill to any of the four screen corners, where it snaps; the corner is remembered per key. Set `false` to pin it, e.g. when your page positions it itself.
`autoCapture`	`boolean`	`true`	Automatic error capture — file uncaught errors with no prompt. Set `false` to turn it off.
`capture`	`{ console?, network?, replay? }`	served per-project	Console / network Trace capture and session replay. On by default and normally governed per-project; set a stream here to override (e.g. `{ network: false }`).
`propagateTo`	`string[]`	`[]` — same-origin only	Cross-origin APIs that also receive the Correlation id header, as origins — e.g. `["https://api.example.com"]`. Same-origin requests always carry it.
`enabled`	`boolean`	`true`	Master switch. `false` mounts nothing and captures nothing — keep the call in place and switch it off per build, e.g. in local dev.
`release`	`string`	—	The build identifier of the running app. Match it to the release you upload sourcemaps under so errors symbolicate.
`scrub`	`boolean`	`true`	Run the built-in URL / PII scrubbers before `beforeSend`.
`beforeSend`	`(report) => report \| null`	—	Reshape or drop (`null`) any report before transport. Not called for a Walkthrough's uploads, which stream pieces, not reports.
`beforeBreadcrumb`	`(crumb) => crumb \| null`	—	Filter or edit Trace entries at the source — including every crumb a Walkthrough streams.
`trace`	`{ budgets?, maxAgeMs?, consoleLevels? }`	SDK defaults	Tune the Trace ring buffer. `maxAgeMs` takes one number for every stream or a per-stream record (network 3 min, console and breadcrumbs 15). To turn a stream off, use `capture`.
`replay`	`{ windowMs?, … }`	SDK defaults	Tune the buffered session-replay window. To turn replay off, use `capture.replay`.

The Correlation id

Every fetch and XMLHttpRequest the SDK records to your own origin goes out with a freshly minted W3C traceparent header (00-<32-hex id>-<16-hex parent>-01), and the request's network entry records that 32-hex id. When your backend runs @fixback/node, it adopts the same id for any error the request causes, so the browser Issue for a failed request and the server Issue behind it show the same Correlation id — in the expanded request row of one and the server request row of the other — and Fixback links the two: the browser Issue names the server error behind its request, and the server Issue lists the browser Issues it was seen from, whichever was captured first.

A cross-origin API receives the header only when you list its origin:

ts

await init({  key: "pk_live_…",  // Your API on another origin — it must allow the header in its CORS preflight.  propagateTo: ["https://api.example.com"],});

Why opt-in cross-origin: a custom header makes the browser send a CORS preflight, so the listed API must answer it with Access-Control-Allow-Headers: traceparent. Nothing cross-origin is touched by default, so a third-party API never sees a preflight it would refuse.
Entries are bare origins — scheme://host[:port]. A path, a query, or a wildcard makes an entry mean something the SDK does not do, so it is ignored with a console warning.
Never breaks a request. The SDK never reads a header value and never overrides one: a traceparent your page already sets (OpenTelemetry's, say) is left alone, and that request records no id. A request whose header cannot be set — a no-cors request, a Request with immutable headers — simply goes out without it.
The sampled flag is 01, so a parent-based OpenTelemetry sampler on your server records these requests rather than dropping them.
sendBeacon cannot carry a header, so beacons are never stamped; with network capture off (capture: { network: false }) nothing is injected at all.
Repeats keep their ids. A captured error that happens again is counted and sent later as a light update with no Trace; that update carries just the Correlation ids of the requests made before the repeats, so Fixback records every occurrence's requests, not only the first one's.
The id is random: it identifies one request, never a person or a session.

The instance & `Fixback`

init resolves to an instance; the module-level Fixback object exposes the same Connect methods against the most recent instance.

Member	Description
`destroy()`	Tears the launcher and overlay down and removes the SDK's handlers.
`signIn()`	Open Connect — the platform's connect page in a popup (a full redirect when it is blocked) — and bind the person's Account to this site as a Reporter session. Resolves to the resulting identity.
`signOut()`	Revoke the Reporter session and forget the token — the person becomes anonymous again.
`identity()`	The current identity: `{ status: "anonymous" }` or `{ status: "connected", name, email, tier }`.

Page shortcuts

The launcher listens for a few shortcuts from anywhere on the page, in the capture phase, so a menu your page has open survives them. The Reporter turns them all off with the Page shortcuts switch in the panel's settings.

Shortcut	What it does
`⌥` `⇧` `F`	Open the report panel.
`⌥` `⇧` `E`	Open it and pick an element. While a Walkthrough records: Pick.
`⌥` `⇧` `S`	Open it and capture a screenshot. While a Walkthrough records: Circle.
`⌥` `⇧` `W`	Start a Walkthrough — only for a Reporter who may start one.

While a Walkthrough records, the single keys P (Pick), C (Circle), Z (remove the last mark) and Esc (leave the tool) work too — never while focus is in a field, so your page's inputs keep every key. See Marking, and the keys.

The launch event

Activating the launcher dispatches a bubbling, composed fixback:launch (LAUNCH_EVENT) from the SDK's host element, so listeners outside its Shadow DOM hear it. Its detail says how:

via — "click" for the pill, "shortcut" for a page shortcut.
action — for a shortcut, which one: "open" (⌥ ⇧ F), "pick" (⌥ ⇧ E), "capture" (⌥ ⇧ S) or "walkthrough" (⌥ ⇧ W).

Connect

A reporter is an Account. The overlay's identity chip shows "Anonymous · Sign in"; clicking it (or calling Fixback.signIn()) opens the platform's connect page, signs the person in with Google, GitHub, Apple, or an email magic link, and returns them to your page as their Account — the chip then shows their name and tier. Behind an Invited or Internal Gate nothing is shown to a signed-out visitor; entry is a Fixback-issued link's ?fixback= code or a host call to Fixback.signIn().

ts

await init({ key: "pk_live_…" }); // mounts the launcher + identity chip where the key's environment is Open// From your own UI, e.g. a "Report a bug" menu item behind an Invited or Internal Gate:await Fixback.signIn();