Widget API

Script tag

<script
  src="https://cdn.gutternote.com/v1/widget.js"
  data-gutternote-key="pk_live_..."
  defer
></script>

Attribute	Required	Description
data-gutternote-key	yes	Public project key. Also triggers auto-boot.
data-gutternote-api	no	Override the API origin. Used for self-hosted deployments.
data-gutternote-open	no	Start with the comment layer active.

Programmatic

Skip data-gutternote-key to boot manually — necessary when you want to pass a signed-in identity from the host page.

await Gutternote.init({
  key: 'pk_live_...',
  author: {
    id: 'u_8123',
    kind: 'user',
    displayName: 'Dana Reed',
    email: 'dana@acme.com',
    avatarUrl: 'https://acme.com/avatars/dana.png',
  },
})

Export	Description
init(options?)	Boots the widget. Idempotent; returns the existing instance if already running.
destroy()	Removes the widget and its listeners.
version	The bundled version string.

When you don’t supply an author, Gutternote generates a stable per-browser guest identity in localStorage. That path matters more than it sounds: most preview feedback comes from people with no account anywhere in your stack.

Deployment metadata

The browser can’t read Vercel’s build environment, so pass it through:

<meta name="gutternote:branch" content="fix/nav" />
<meta name="gutternote:commit" content="3ab19f2" />
<meta name="gutternote:pr" content="42" />

Without these the widget falls back to parsing the Vercel preview hostname, which is lossy — fix-nav and fix/nav produce the same hostname.

How anchors survive a redeploy

Each comment records three things: a CSS selector, a text quote of the target, and an offset stored as a fraction of the element’s own box. On load the widget tries them in order:

1. selector — exact, but brittle across refactors
2. text quote — survives markup changes, breaks when copy is edited
3. coordinates — always resolves to something, may be visually wrong

A pin that only resolved by coordinates is outlined in amber, because its target no longer exists on the page and the position is a guess.

Give elements you expect to receive a lot of feedback a data-gutternote-id; it’s the most durable anchor available and survives changes nothing else does.