Quickstart (classic widget)

Three lines for the headless browser core; a provider + hook if you are on React.

Browser SDK

npm install @uservane/browser

import { UserVane } from "@uservane/browser";

UserVane.init({ key: "uv_pk_live_..." });
UserVane.identify({ userId: "u_123", traits: { plan: "pro" } });
UserVane.survey("nps-q1"); // imperative trigger by survey slug

init is idempotent and SSR-safe (DOM work defers to the client).
identify is repeatable; traits merge. Call it when your auth session is known.
survey(slug) buffers until rules load, then runs the show-decision.

Auto-triggered surveys (configured with trigger: "auto" in the dashboard) appear after a fixed idle delay without an imperative survey() call. Manual surveys need UserVane.survey.

Publishable key only in the browser. See Keys.

React

npm install @uservane/react

"use client";

import { UserVaneProvider, useUserVane } from "@uservane/react";

export function App() {
  return (
    <UserVaneProvider apiKey="uv_pk_live_...">
      <Page />
    </UserVaneProvider>
  );
}

function Page() {
  const { survey, identify } = useUserVane();
  // after auth:
  identify({ userId: "u_123", traits: { plan: "pro" } });
  // on a meaningful event:
  // survey("nps-q1");
  return null;
}

UserVaneProvider is a Client Component ("use client"). In Next.js App Router, import it from a client boundary. Optional props: apiBase, debug.

An internal error boundary wraps the subtree so a UserVane render failure does not take down the host tree.

What happens under the hood

SDK calls POST /v1/sdk/bootstrap with the publishable key and userId.
Server returns survey definitions, the suppression set (answered/dismissed), and single-use show-tokens for eligible surveys.
Client decideShow checks identity, suppression, targeting, sampling, and token presence.
On submit, POST /v1/sdk/responses verifies the token and stores the rating. Caps never discard a tokened answer.