SDK migration: v1 → v2

The v2 SDK adds hover-pick feedback, Embedded Telemetry and replay clips. Feedback submission is unchanged; read the breaking changes in section 2 before you upgrade.

TL;DR. Your POST /v1/feedback integration and userz.submit keep working. Four things change on upgrade: the widget picks elements on hover by default, telemetry is captured by default, apiUrl is gone, and the iife entry loads from the CDN. Section 2 covers each one.

1. Update the package

The v2 SDK is published as 3.x on npm. @userz-ai/browser and @userz-ai/react now release together at the same version, so upgrade both at once. No import paths change: createUserz, userz.submit, and the React <UserzProvider> / useUserz keep their signatures, apart from the removed apiUrl. Core Web Vitals use the web-vitals library, which installs with the SDK.

Bash

pnpm add @userz-ai/browser@^3     # plain JS, Vue, Svelte, …
pnpm add @userz-ai/react@^3 @userz-ai/browser@^3     # React

2. Breaking changes

apiUrl is removed

The SDK's API and CDN hosts now come from the release channel the SDK was built for. A page can no longer point the SDK at a host of its own. A config that still passes apiUrl fails to type-check. Delete the line.

The default mode is hover

v1 defaulted to mode: 'session'. v2 defaults to 'hover'. Resting the pointer on an element shows a small indicator beside it, and clicking the indicator opens the form for that element. Hover never opens the form by itself, and page clicks are never intercepted. On touch, the bubble starts an explicit tap-to-pick. To keep v1's behaviour, set the mode:

TypeScript

createUserz({ publicKey: 'pub_...', mode: 'session' });   // or 'single' for a plain button

A mode you set explicitly is never changed by the dashboard or by a later upgrade.

The iife entry loads from the CDN

@userz-ai/browser/iife used to be one self-contained file. It is now the script-tag core, which loads each capability from the Userz CDN by an exact-version URL with a Subresource Integrity digest. If you bundle or self-host it, for example in a browser extension, allow the CDN host or use userz.full.js, which inlines everything.

Telemetry runs by default

An upgraded page starts sending telemetry with no code change. Section 3 covers what is captured and where to turn it down. If you followed an earlier version of this guide and added a telemetry: {…} block, configureTelemetry() or <UserzTelemetry>, they are accepted but ignored. Telemetry is configured in your app's SDK settings instead.

3. Telemetry

With no configuration at all, the SDK captures errors, frustration signals (rage, dead and error clicks, form abandonment), Core Web Vitals and slow requests, engagement, autocaptured clicks and pageviews. Events are batched to POST /v1/telemetry/batch. You control telemetry in three places:

Name	Type	Description
Your app’s SDK settings	dashboard	Pause telemetry, set the sampling rate (every session by default) and turn individual categories off.
setConsent(category, state)	per end user	`setConsent('analytics', 'denied')` stops telemetry for this visitor. Consent is `implicit` by default. In `explicit` mode no telemetry is captured until you call `setConsent('analytics', 'granted')`.
The browser	GPC / DNT	Global Privacy Control and Do Not Track are honoured by default; your app’s SDK settings can turn that off.

The SDK reads your app's settings once at start (GET /v1/sdk/config) and applies the stored copy on later page loads before the network answers. If your Content-Security-Policy lists hosts, allow the Userz API host for these requests.

4. Custom signals from your code

TypeScript

// Programmatic signal
userz.signal({ kind: 'export_failed', severity: 'high', data: { rows: 50000 }, tags: ['billing'] });

// Manual error report alongside autocapture
userz.captureError(err, { context: 'csv-export' });

React: declarative funnel steps

TSX

import { UserzFunnel } from '@userz-ai/react';

<UserzFunnel name="checkout" step="3-payment">
  <PaymentForm />
</UserzFunnel>;

5. What does not change

userz.submit, screenshots, and console-log capture. The console tail is now redacted for e-mail addresses, card numbers and similar values before it leaves the page.
Private-mode JWTs (@userz-ai/node) and webhook verification.
The POST /v1/feedback ingest endpoint and existing webhook event names.

6. Privacy & volume

Telemetry captures behavior and errors. It never records input values, and the text of a clicked element is length-capped and scrubbed of card, social-security and bank-account numbers. Events pass through the same PII-redaction as every signal, a server-side bot filter drops crawler traffic at ingest, and replay is evidence, not a session recording: opt-in per app (replay.enabled, off by default), the SDK cuts a short clip around a widget submission, an uncaught error or a rage click, with inputs and text masked by default.

Retention is plan-scoped (Free 1 day → Pro 30 days). Every session is sampled by default. To reduce volume, lower the sampling rate or turn categories off in your app's SDK settings.

7. Rollback

To roll back, pin the last v1 releases, @userz-ai/[email protected] and @userz-ai/[email protected]. Remove the v2-only APIs first, for example userz.signal, <UserzFunnel>, setConsent and identify. A TypeScript build against those versions names every one.