Web quickstart

Add the Voidhash browser SDK to a website or web app.

The web SDK runs in the browser. It identifies visitors, evaluates feature flags, records page views and product events, and remembers which campaign or ad brought each visitor to your site. Purchases on the web go through Stripe; the web SDK links the visitor to the Stripe customer so revenue is attributed to the right person and campaign.

Install the SDK

npm install @voidhash/web effect@4.0.3

effect is a peer dependency. The SDK supports effect 4.0.3, so the command pins it.

Create the client

Create one client per page load, as early as possible, with your project's publishable key. Find the key in your project settings in Studio.

src/lib/voidhash.ts

import { createVoidhashClient } from "@voidhash/web";

export const voidhash = createVoidhashClient({
  publishableKey: "vh_pk_…",
});

await voidhash.initialize();

initialize() resolves once the SDK has loaded its local state. It never waits for the network, and no SDK call throws or blocks your page because Voidhash is slow or unreachable. Events are queued in localStorage and sent in the background.

Initializing the client also records the first page view and, when the URL carries campaign parameters, the visitor's campaign. See Page views and attribution.

Identify signed-in users

Until you identify them, visitors have an anonymous id that is stored in localStorage. When a visitor signs in, call identify with your own stable user id. Their earlier anonymous activity, including the campaign that brought them, is linked to that user.

await voidhash.identify("user_123", { email: "ada@example.com" });

Call reset() when the user signs out. The next visitor on the device gets a new anonymous id and a new session.

Track events

await voidhash.track("checkout_started", { plan: "yearly" });

track() never rejects because of the network. Names that begin with $ are reserved for Voidhash's own events.

If your website asks visitors for consent to analytics, start the client with consent pending and pass the visitor's choice once they make it:

const voidhash = createVoidhashClient({
  analyticsConsent: "pending", // "granted" (default), "denied" or "pending"
  publishableKey: "vh_pk_…",
});
await voidhash.initialize();

// When the visitor answers your consent banner:
await voidhash.setAnalyticsConsent("granted"); // or "denied"

While consent is pending or denied, no page views, events or person traits are recorded, stored or sent. Identity and feature flags keep working.
A campaign the visitor arrived from while consent is pending is kept in sessionStorage for the rest of the browser session. If consent is granted in that session, it is sent then, so the campaign is not lost to the consent banner. If consent is denied, it is discarded.
The choice is stored on the device and takes precedence over the analyticsConsent option on later visits. Revoking consent discards every queued event, in every open tab.

React

The @voidhash/web/react entry point provides a provider and hooks.

import { VoidhashProvider } from "@voidhash/web/react";

<VoidhashProvider config={{ publishableKey: "vh_pk_…" }}>
  <App />
</VoidhashProvider>;

Page views of client-side route changes are recorded automatically for any router that uses the History API, including React Router, TanStack Router and Next.js.