Manual exposure
Suppress the automatic exposure on getExperiment and log it yourself, so an exposure only counts when the user actually sees the variant.
By default, the first getExperiment call for a user queues an exposure event — the record the daily analysis uses to know who was in the test. Usually that's exactly right. But sometimes you resolve a variant well before the user sees it (a server prefetch, a component that may never mount). Manual exposure lets you decouple resolving the variant from counting the exposure.
disableAutoExposure is an Engine construction option. Everyday flag
reads use configure + new Client(user); the per-call
logExposure: false option and logExposure() work on both the bound
Client and the Engine directly.
Suppress the automatic exposure
Pass logExposure: false in the options to resolve a variant without logging:
const result = flags.getExperiment(
"checkout_button",
{ color: "blue" },
{ logExposure: false }, // resolve only — no exposure yet
);To suppress auto-exposure for an entire engine, set disableAutoExposure: true at construction:
import { Engine } from "@shipeasy/sdk/server";
const engine = new Engine({
apiKey: process.env.SHIPEASY_SERVER_KEY!,
disableAutoExposure: true,
});Log the exposure yourself
Call logExposure at the moment the variant is actually rendered:
flags.logExposure("checkout_button");// bound Client — the user is implicit
logExposure(name: string): void;
// Engine — pass the user explicitly
logExposure(user: string | User, name: string): void;On the bound Client (and in the browser, where the visitor is already identified) you pass just the experiment name; on the Engine you pass the user too.
An exposure that fires twice for the same user in the same experiment is deduped by the pipeline,
but the cleanest contract is: suppress the auto-exposure, then call logExposure
exactly once, when the user sees the variant.
When to reach for it
- Server prefetch — you resolve the variant in a loader but the component may never render.
- Lazy UI — a tab or modal that holds the variant but isn't always opened.
- Strict exposure semantics — you want "exposed" to mean "saw it", not "was assigned".
Reacting to changes
onChange fires after a background poll picks up new rules — use it to invalidate caches or re-render when a flag flips.
Multi-context bucketing (bucketBy)
Bucket on company_id, session_id, or any attribute instead of user_id — so a rollout or experiment splits by account, not by individual user.