Configuration reference (BugCapturerConfig)

Everything the widget does is controlled by one global object, window.BugCapturerConfig, which must be defined before the SDK script tag (the SDK reads it while loading). This page lists every field with its type, default and behaviour.

<script>
  window.BugCapturerConfig = {
    key: "bcpk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", // required
    // everything below is optional
  };
</script>
<script src="https://api.bugcapturer.com/sdk/bugcapturer.js" async></script>

Fields

Field	Type	Default	Description
key	string	— (required)	The project’s public SDK key (bcpk_ prefix). Identifies the project; authorization comes from the project’s domain whitelist, not from key secrecy
api	string	https://api.bugcapturer.com	API origin. Only override for self-hosted / proxy deployments; must not end with a slash
position	string	bottom-right	Initial corner of the floating ball: bottom-right / bottom-left / top-right / top-left. Once the visitor drags the ball, their chosen position is remembered per site (localStorage) and wins over this value
requireContact	boolean	false	Ask anonymous visitors for contact info before submitting. Server-side project settings enforce the same rule — keep them consistent
reporter	object	{ uid: "", name: "", email: "" }	Identity attached to every report. Leave empty for anonymous sites; for signed-in users fill it per user (server-rendered) or call identify() — never hardcode one person’s identity
lang	string	browser language	Widget UI language: zh or en. Any value not starting with zh falls back to en
tipDelay	number	5	Seconds the visitor must stay on the page before the tip bubble pops up. 0 shows it immediately after load
tipDuration	number	5	How long the tip bubble stays visible, in seconds
tipOnce	boolean	true	Show the tip only once per visitor (remembered in localStorage). Set false to show it on every page load
exposeReporter	boolean	true	Whether BugCapturer.getReporter() (and therefore the BugCapturer extension) may read the reporter identity passed to this page. Set false for a stricter privacy stance; reports are unaffected, only the local read API is blocked

Notes and gotchas

key is public, and that is fine

The SDK key travels in plain sight (it is in the page source by definition). Anyone can load the widget on a whitelisted domain; nobody can submit from a domain you did not allow, and everyone is rate-limited. Rotate a key by deleting and re-creating the project.

requireContact is a two-sided switch

The embed flag controls what the form asks for; the project’s Widget settings are enforced server-side as well. If the project requires contact but a report arrives without one, the server rejects it — so when you toggle this, change it in both places (or just in the project settings, and mirror the value in the snippet).

reporter vs identify()

Both set the same identity; the last write wins. Rules of thumb:

• Server-rendered page → template reporter per user
• SPA / client-side session → call identify() after login
• No login → leave it empty (anonymous)

Timing

The SDK reads the config once, when the script executes. Defining the config after the SDK tag (or conditionally, later) is the most common cause of a widget that never appears. The tag order in the snippet above is required.

Minimal configurations

Anonymous marketing site:

<script>
  window.BugCapturerConfig = { key: "bcpk_…" };
</script>

Signed-in UAT environment (server-rendered, contact not required):

<script>
  window.BugCapturerConfig = {
    key: "bcpk_…",
    position: "bottom-left",
    reporter: { uid: "${user.id}", name: "${user.name}", email: "${user.email}" }
  };
</script>

See also

• Reporter identity — filling reporter correctly