Advanced
Advanced features. All are set as options on configure() (or on shipeasy() for SSR), or read through the bound Client.
/docs/ — also served raw at https://shipeasy-ai.github.io/sdk-ts/pages/advanced.md.Advanced features. All are set as options on configure()
(or on shipeasy() for SSR), or read through the bound Client.
Exposure control
One (deduped) exposure beacon is logged per enrolled unit. When it fires differs by entrypoint, and both give you a way to suppress it:
-
Server — exposure fires on the first
get()read of an enrolled assignment, not atassign()time. To read without logging (peek), pass{ exposure: false }; the exposure then fires on the next real read.const flags = new Client(user); // construct once per callsite const cta = flags.universe("hero_cta").assign(); // Peek the params WITHOUT logging an exposure: const preview = cta.get("primary_label", "Sign up", { exposure: false }); // …at the moment you actually render the treatment, read normally to log it: render(cta.get("primary_label", "Sign up")); // logs the single exposure (deduped) -
Browser — exposure fires at
assign()time (the visitor is already resolved). Suppress it withassign({ logExposure: false })and re-assign()with logging on at render, or make suppression the default for every read withdisableAutoExposure: trueonconfigure()and opt back in per callsite withassign({ logExposure: true }).const flags = new Client(visitor); // construct once per callsite const cta = flags.universe("hero_cta").assign({ logExposure: false }); render(cta.get("primary_label", "Sign up")); flags.universe("hero_cta").assign(); // …log the exposure at render (deduped per session)
Either way the exposure is deduped per session and durably per
(unit, experiment, group) server-side.
Private attributes
Attributes you mark private are used for evaluation but stripped from every
outbound track() payload (privateAttributes):
configure({
apiKey: process.env.SHIPEASY_SERVER_KEY!,
privateAttributes: ["email", "ip"],
});On the browser they are still sent to /sdk/evaluate under private_attributes
so the edge can evaluate with them (unavoidable), but they never appear in
tracked event props.
bucketBy — custom bucketing unit
Bucketing hashes on user_id (falling back to anonymous_id) by default. An
experiment can carry its own bucketBy (e.g. company_id) so all users in a
company get the same variant — set on the experiment in the dashboard, no SDK
change needed. When bucketBy is set, the value of that attribute is the hash
unit; if it's missing on the user, evaluation falls back to the standard
identifier. Make sure your attributes transform surfaces the bucketing
attribute:
configure({
apiKey: process.env.SHIPEASY_SERVER_KEY!,
attributes: (u: MyUser) => ({ user_id: u.id, company_id: u.orgId }),
});Sticky bucketing
Lock a unit into the first variant it was assigned even if the experiment's
allocation later changes. On the server, pass a stickyStore to configure()
to persist assignments across requests:
import { configure, createInMemoryStickyStore } from "@shipeasy/sdk/server";
configure({
apiKey: process.env.SHIPEASY_SERVER_KEY!,
stickyStore: createInMemoryStickyStore(), // or a cookie-bridge over __se_sticky
});createInMemoryStickyStore() is process-local (good for a single-process server
or tests); for a multi-process deployment back the StickyBucketStore interface
(get(unit) / set(unit, exp, entry)) with shared storage or a request-cookie
bridge. In the browser, sticky bucketing is on by default (persisted in the
__se_sticky cookie so SSR server eval and the browser agree).
Anonymous-id bucketing
The browser persists an anonymous_id (and the SSR bootstrap mints a matching
__se_anon_id cookie) so a logged-out visitor buckets identically before
and after the server pre-evaluation — no flag flicker on first paint.
Change listeners
The package-level onChange() fires after a background poll returns new data
(HTTP 200, not 304) and returns an unsubscribe callable. It requires
configure({ poll: true }) (no poll thread runs otherwise) and never fires in
test/offline mode:
import { configure, onChange } from "@shipeasy/sdk/server";
configure({ apiKey: process.env.SHIPEASY_SERVER_KEY!, poll: true });
const unsubscribe = onChange(() => { /* re-evaluate / invalidate cache */ });In the browser, onChange() fires after each identify() / override change.
Devtools overlay
Press Shift+Alt+S on any page running the SDK (or append ?se=1). The
Shipeasy devtools panel mounts in a Shadow DOM overlay and lets you flip every
gate / config / experiment / translation for the current session only —
handy for QA, demos, and bug repro. The overlay is delivered as a hosted script
(se-devtools.js) — nothing to install: the browser SDK loads it on demand
when the page has not mounted the tag, see the Browser devtools page. React
Native apps get the same panels from the @shipeasy/react-native-devtools
package.
Signed overrides on the server
When a developer is signed in to the devtools overlay, every override (including
a ?se_gate_… URL one) is mirrored into a signed se_ov cookie that reaches
your server on every same-origin request, page loads and XHR/GraphQL alike. To
let server-side reads see it, wrap request handling in withRequestOverrides:
import { withRequestOverrides, Client } from "@shipeasy/sdk/server";
app.use((req, res, next) => withRequestOverrides(req.headers.cookie, next));
// anywhere inside the request
new Client(user).getFlag("new_checkout"); // true when forced in devtoolsInside the scope Client.getFlag / getFlagDetail (reason OVERRIDE),
getKillswitch (whole-switch reads), getConfig and universe(name).assign()
honour the cookie. Precedence: programmatic overrideFlag etc., then the signed
cookie, then normal evaluation. It is fail-closed: it needs the project's
override key served by Shipeasy, a valid signature and an unexpired cookie, else
real values resolve. Unsigned ?se_gate_… URL params alone stay client-only by
design. Outside a scope, behaviour is unchanged.
Dev-only URL overrides without sign-in
On a local/dev/test stack you can make a plain ?se_gate_x=true reach server
reads without signing in to devtools. In non-production builds the browser SDK
mirrors the current URL's override params into an unsigned se_ov_dev session
cookie (written on init, deleted when the URL has no override params). The
server reads it only when you opt in:
configure({ apiKey: process.env.SHIPEASY_SERVER_KEY!, devOverrides: true });Two guards, both required: devOverrides: true AND a non-production process
(SHIPEASY_ENV / NODE_ENV; configureForTesting() counts as non-production).
In a production process the option is ignored with one warning and the cookie is
never read; the browser writer is compiled out of production bundles. Precedence:
programmatic > signed se_ov > se_ov_dev > evaluation. Never active in
production.
Frontend and API on different subdomains
With the frontend on app.example.com and the API on api.example.com, the
override cookies are written with Domain=.example.com so both hosts receive
them. The domain is auto-detected (the broadest one the browser accepts; no
Domain on localhost / IPs); force one with the browser option
configure({ clientKey, overrideCookieDomain: ".example.com" }). Stale host-only
copies from older SDKs are cleared on every write.
For a token-auth API on another origin that never receives cookies, send them as a header instead:
import { getOverrideHeaders } from "@shipeasy/sdk/client";
fetch("https://api.example.com/graphql", { headers: { ...getOverrideHeaders() } });
// Apollo: new HttpLink({ uri, headers: { ...getOverrideHeaders() } })getOverrideHeaders() returns { "X-Shipeasy-Overrides": "se_ov=…; se_ov_dev=…" }
(or {}). Allow that header in the API's CORS config. On the server, pass it as
the third argument: withRequestOverrides(req.headers.cookie, next, req.headers["x-shipeasy-overrides"]). The Cookie header wins per cookie name;
the same verification and devOverrides guards apply.