Identity & bucketing

Every fractional rollout and every experiment buckets on a unit id. Get the unit right and a visitor sees a consistent experience across SSR, the browser, and your backend — in every language. This page is the contract.

The unit: user_id, then anonymous_id

When you don't pass an explicit unit, the SDK resolves it in this order:

unitId = user.user_id ?? user.anonymous_id

• user_id — your stable identifier for an authenticated user. It comes through the bound Client — new Client({ user_id }).getFlag(name) on the server, or the same new Client(user) on the browser.
• anonymous_id — a stable id for a logged-out visitor so they still bucket consistently.

The hash is identical across the whole stack, so bucketing agrees everywhere as long as every surface feeds the same unit string for the same visitor.

anonymous_id — a first-party cookie

The anonymous unit lives in a single first-party cookie, __se_anon_id. It's an opaque stable UUID — treat it as opaque, never parse it.

Because it's a plain HTTP cookie, it's language-agnostic: any server runtime reads it off the request, any browser reads it off document.cookie. The cookie is the interface — no SDK needs to know about any other SDK.

Minted by middleware on HTML routes

Mint the cookie as early as possible so the first request already has an id and nothing flickers:

Identity stitching — alias on identify

When an anonymous visitor logs in, tie the two ids together so analytics and experiment attribution don't split the same person in two:

// Client SDK — call right after authentication
flags.identify({
  user_id: authenticatedUser.id,
  anonymous_id: currentAnonId, // the UUID that did the anonymous bucketing
});

This emits an identify (alias) event. The analysis pipeline resolves the alias before aggregation, so pre-login and post-login activity roll up to one user. Bucketing is locked at first exposure — once an anonymous_id is stitched to a user_id, the original group assignment is preserved and the user is not re-bucketed. After login, live bucketing keys on user_id; the anon cookie stays around for logged-out surfaces.

bucketBy — bucket on something other than the user

Sometimes the right unit isn't the individual. Roll a feature out to 20% of companies (everyone at a company flips together) or bucket by session instead of user. That's bucketBy:

// Bucket this gate / experiment on company_id instead of user_id —
// the whole company moves together.
const flags = new Client({ user_id: userId, company_id: "acme-co" });
flags.getFlag("new-billing-ui");

With bucketBy: "company_id", the hash keys on the company attribute, so every user at acme-co lands in the same bucket. Common units: company_id (org-level rollout), session_id (per-session experiments), device_id. The named attribute just has to be present on the user you pass.

Sticky bucketing

By default, bucketing is stateless — recomputed from the hash every time, which is deterministic and needs no storage. Sticky bucketing instead persists a user's first assignment so they keep the same variant even if you later change allocation, weights, or the salt.

Reach for it when re-bucketing would be jarring mid-experiment — e.g. you widen a group's weight and don't want already-enrolled users to jump variants. Sticky state is shared between SSR and the browser through a first-party __se_sticky cookie, the same way __se_anon_id keeps anonymous bucketing in agreement.