Shipeasy
SDKsReferenceTypeScript / JavaScript

Advanced

Advanced features. All are set as options on configure() (or on shipeasy() for SSR), or read through the bound Client.

Generated from the SDK's own /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 at assign() 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 with assign({ logExposure: false }) and re-assign() with logging on at render, or make suppression the default for every read with disableAutoExposure: true on configure() and opt back in per callsite with assign({ 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 devtools

Inside 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.

Was this page helpful?
Updated July 26, 2026

On this page