@userz-ai/browser

Framework-free core for the Userz feedback widget. Bubble + panel UI in a shadow DOM, console & error capture, screenshot via modern-screenshot, presigned-upload + submit pipeline.

If you use React, you almost certainly want @userz-ai/react on top of this — it adds an idiomatic provider, hook, and <UserzTarget> wrapper. This package is the right entry point for plain HTML, Vue, Svelte, Solid, or vanilla JS.

Install

pnpm add @userz-ai/browser

Or load directly from the CDN — no bundler required:

<script src="https://cdn.userz.ai/v1/userz.js"></script>
<script>
  const userz = Userz.createUserz({
    publicKey: 'pub_...',
  });
</script>

Quick start

import { createUserz } from '@userz-ai/browser';

const userz = createUserz({
  publicKey: 'pub_...',
  // Private mode: return a JWT minted by your backend (see @userz-ai/node).
  getUserToken: async () => sessionStore.getUserzToken(),
});

document.querySelector('#feedback-button')?.addEventListener('click', () => {
  userz.open();
});

That's it. The bubble renders in the bottom-right by default; click it (or call userz.open()) to open the panel. On submit the widget uploads any screenshot to R2 via a presigned URL, then POSTs the report to /v1/feedback.

Configuration

| Field | Default | Notes | |---|---|---| | publicKey | — | App public key from the Userz dashboard. Required. | | apiUrl | https://api.userz.ai | Override only for local dev against a non-prod external-api. | | getUserToken | — | Async getter for the private-mode JWT. Return undefined for public mode. | | bubble | true | Render the floating bubble. Set false to call open() from your own UI. | | showEmailField | true | Show the "your email" input in public mode (auto-hidden in private mode). | | consoleCapacity | 200 | Number of recent console.* events to capture per submission. | | captureErrors | true | Capture error + unhandledrejection events. | | targetingChord | Ctrl+Shift+U | Key combo to toggle the component-targeting overlay. | | initialUser | — | Public-mode identity hint; updatable via setUser(). |

Methods

userz.open();                         // open the panel
userz.close();
userz.toggle();
userz.setUser({ email, name });       // public-mode identity
userz.setMetadata({ route, build });  // arbitrary metadata sent with next submission
userz.setTargetingEnabled(true);      // turn on the targeting overlay programmatically
const blob = await userz.captureScreenshot();
const { id, status } = await userz.submit({ text: 'Wishlist would be great' });
userz.destroy();                      // tear down listeners + DOM

What ships with each submission

• The text body
• A buffered tail of console.log/info/warn/error (truncated per entry, redacted for Authorization, password, JWT-shaped strings, sk_…, ghp_…)
• Captured uncaught errors and unhandled rejections (when captureErrors)
• viewport + userAgent + the current page URL
• Optional screenshot (uploaded directly to R2)
• Optional component target (when triggered via the targeting overlay)
• Optional metadata you've set
• Identity — from setUser() in public mode, or derived from your JWT in private mode

Bundle size

| Build | Size | |---|---| | ESM (./) | ~54 KB gzip | | IIFE (./iife, used by the CDN) | ~48 KB gzip |

The ESM build externalizes modern-screenshot (loaded dynamically the first time captureScreenshot() is called), so your bundler resolves it from node_modules the same way as any other dependency. The CDN IIFE bundle inlines it.

Docs

Full reference at userz.ai/docs/sdk/browser. Source on GitHub.

License

MIT