Advanced
Exposure is automatic but fires on read, not at assign() time: assign() is side-effect free, and the first get(...) on an enrolled assignment POSTs one…
/docs/ — also served raw at https://shipeasy-ai.github.io/sdk-java/pages/advanced.md.Exposure logging
Exposure is automatic but fires on read, not at assign() time:
assign() is side-effect free, and the first get(...) on an enrolled
assignment POSTs one {type:"exposure", experiment, group, user_id, ts} event to
/collect. An assignment that is computed but never read logs nothing. There is
no manual logExposure. Just assign and read at the point you present the
experiment:
// Assumes Shipeasy.configure(...) ran at startup — see Installation.
Client c = new Client(Map.of("user_id", "u_123", "plan", "pro")); // construct once per callsite
Assignment a = c.universe("hero_cta").assign(); // side-effect free
String label = (String) a.get("primary_label", "Sign up"); // first get() logs the exposure
String peeked = (String) a.peek("primary_label", "Sign up"); // read WITHOUT logging an exposureThe exposure is deduped per process and, durably, per
(unit, experiment, group) server-side: repeated reads for the same
(unit, experiment, group) POST only one exposure. Use peek(...) to read a
param without logging at all. No-op in test/snapshot mode or when the unit isn't
enrolled.
Private attributes
Mark attribute names that may be used for targeting but must never be
persisted in analytics (privateAttributes). The server evaluates
locally, so private attrs never leave for evaluation; the only egress is
/collect, and these keys are stripped from every outbound track() payload
(and see() extras):
Shipeasy.configure(Shipeasy.options(System.getenv("SHIPEASY_SERVER_KEY"))
.privateAttributes(List.of("email", "ip")));Bucketing identifier (bucketBy)
bucketBy is a server-side experiment property — it is set on the
experiment in the Shipeasy dashboard (e.g. company_id), and the SDK reads it
from the experiment blob automatically. When set, the experiment buckets on that
attribute instead of user_id/anonymous_id. Make sure the bucketing attribute
is present in the user map you pass. There is no per-call bucketBy knob in the
SDK.
Sticky bucketing
Supply a StickyBucketStore so an enrolled unit stays locked to its
first-assigned variant even if you change allocation % or group weights
(changing the experiment salt is the reshuffle lever). Absent ⇒ deterministic
(fully backward compatible):
import ai.shipeasy.InMemoryStickyStore;
Shipeasy.configure(Shipeasy.options(System.getenv("SHIPEASY_SERVER_KEY"))
.stickyStore(new InMemoryStickyStore()));InMemoryStickyStore is a process-local, thread-safe store (good for tests and
single-process servers). Implement StickyBucketStore (get(unit) /
set(unit, exp, entry)) over a shared cache (Redis, DB) for multi-process
deployments.
Anonymous visitors — AnonIdFilter (zero-config bucketing)
For logged-out traffic you need a stable unit so a fractional rollout buckets
the same on the server and in the browser. AnonIdFilter is a servlet Filter
that mints the shared __se_anon_id first-party cookie for any request without
one; evaluations then default to it as anonymous_id, so a logged-out
request needs no per-call wiring.
// Spring Boot
@Bean
FilterRegistrationBean<AnonIdFilter> shipeasyAnonId() {
var reg = new FilterRegistrationBean<>(new AnonIdFilter());
reg.addUrlPatterns("/*");
return reg;
}// logged-out request → buckets on the __se_anon_id cookie automatically
new Client(Map.of()).getFlag("new_checkout");An explicit user_id/anonymous_id always wins. The cookie is non-HttpOnly
by design so the browser SDK buckets identically. Non-servlet stacks (Ktor,
http4k, Javalin) can use the AnonId primitives directly. The same filter also
scopes signed DevTools overrides to the request (next section).
DevTools overrides on server reads (signed se_ov cookie)
When a developer is signed in to the DevTools overlay, every override they set
(including ?se_gate_x=true URL state) is mirrored into a signed se_ov
cookie, which reaches your server on every same-origin request. Install
AnonIdFilter (it verifies the cookie once per request) or wrap the request in
Shipeasy.withRequestOverrides(...), and Client reads inside the request —
getFlag/getFlagDetail (reason OVERRIDE), getKillswitch (whole-switch),
getConfig and universe(name).assign() — return the overridden value.
// Servlet apps: the AnonIdFilter registered above already does this.
// Any other stack: wrap the request handling yourself.
String cookieHeader = request.getHeader("Cookie"); // raw header, or the bare se_ov value
Shipeasy.withRequestOverrides(cookieHeader, () -> {
Client c = new Client(user); // construct once per callsite
boolean on = c.getFlag("new_checkout"); // honors the signed override
render(on);
});
// Supplier overload returns the body's result:
// String html = Shipeasy.withRequestOverrides(cookieHeader, () -> renderPage(user));Precedence: Shipeasy.overrideFlag(...) (programmatic) beats the signed cookie,
which beats normal evaluation. Outside a scope nothing changes. It is
fail-closed: overrides apply only when Shipeasy serves your project's
override key, the cookie's signature verifies, its key id matches and it has not
expired; anything else is ignored silently. A plain unsigned ?se_gate_ URL
parameter on its own is client-only by design — it never reaches server
reads. The scope is thread-local; if you hand work to another thread, wrap it
again with the same header.
Frontend and API on different subdomains
With the frontend on app.example.com and the API on api.example.com, the
browser SDK scopes the se_ov / se_ov_dev cookies to the registrable domain
(auto-detected, or set overrideCookieDomain in the browser configure()), so
the API receives them like any other cookie and the filter / scope above just
works. For token-auth APIs that do not get cookies, the browser SDK's
getOverrideHeaders() returns an X-Shipeasy-Overrides header (cookie-header
syntax, e.g. se_ov=...; se_ov_dev=...; allow it in the API's CORS
Access-Control-Allow-Headers). AnonIdFilter reads it automatically; for the
manual scope pass it as the second argument. The Cookie header wins per cookie
name, the header fills in when the cookie is absent, and the same verification
and guards apply (a signed value must verify; se_ov_dev is never even parsed
unless devOverrides is on in a non-production process).
Shipeasy.withRequestOverrides(
request.getHeader("Cookie"),
request.getHeader("X-Shipeasy-Overrides"), // optional, may be null
() -> handle(request));Local dev without sign-in — devOverrides (se_ov_dev)
On a local/dev/test stack you can opt in to an unsigned cookie so
?se_gate_x=true reaches server reads without DevTools sign-in. The dev browser
build writes se_ov_dev (base64url JSON {"gates":{},"configs":{},"exps":{}});
the server reads it only when you turn the option on:
Shipeasy.configure(Shipeasy.options(System.getenv("SHIPEASY_SERVER_KEY"))
.devOverrides(true)); // default false
// tests: Shipeasy.configureForTesting(new Shipeasy.TestOptions().devOverrides(true))Two guards, both required: the option is true and the process is
non-production (shipeasy.env system property, then SHIPEASY_ENV / APP_ENV /
ENV; unset means production; test/offline engines count as non-production).
In a production process the option is ignored with one logged warning and the
cookie is never even read, so it is never active in production. Precedence per
name: programmatic overrideFlag > signed se_ov > se_ov_dev > evaluation;
reason stays OVERRIDE.
Server-side rendering (SSR) bootstrap
Emit the request's evaluated flags as a declarative <script> tag so the
browser SDK has them on first paint. bootstrapScriptTag carries the payload in
data-* attributes (no key — the server key must never reach the browser);
the /sdk/runtime.js browser runtime reads them, installs window.shipeasy,
republishes window.__SE_BOOTSTRAP for the npm client SDK and writes the
__se_anon_id cookie so the browser buckets identically to the server:
// Assumes Shipeasy.configure(...) ran at startup — see Installation.
Map<String, Object> user = Map.of("user_id", "u_123");
String head = Shipeasy.bootstrapScriptTag(user, anonId)
+ Shipeasy.i18nScriptTag();Every argument is optional
The tag helpers overload down to a no-argument call: the client key, profile,
project id and CDN base all come from the configure options, and a null
argument (or no user) falls back the same way.
| Helper | No-argument form | Defaults from the options |
|---|---|---|
Shipeasy.i18nScriptTag() | i18nScriptTag(clientKey, profile, baseUrl) | .clientKey, .profile, .cdnBaseUrl |
Shipeasy.bootstrapScriptTag() | bootstrapScriptTag(user, anonId, i18nProfile, baseUrl) | anonymous request, .profile, .cdnBaseUrl |
Shipeasy.devtoolsScriptTag() | devtoolsScriptTag(projectId, clientKey, baseUrl, defer) | .projectId, .clientKey, .cdnBaseUrl |
Shipeasy.configure(Shipeasy.options(System.getenv("SHIPEASY_SERVER_KEY"))
.clientKey(System.getenv("SHIPEASY_CLIENT_KEY")) // PUBLIC key, for the tags
.projectId(System.getenv("SHIPEASY_PROJECT_ID")) // for the devtools tag
.profile("en:prod"));A tag still renders when a value is missing (the browser bundle reports what it needs), but the SDK logs a warning naming the option to fill in — once per option, not once per render.
Devtools overlay tag
Shipeasy.devtoolsScriptTag() emits the hosted devtools overlay bundle —
nothing to install, no overlay code in your artifact. It reads the project id and
public client key off the tag and opens with Shift+Alt+S or on any page
loaded with ?se=1. It is deferred unless you pass defer = false: a developer
tool never belongs on the critical rendering path.
String devtools = Shipeasy.devtoolsScriptTag();Adding it unconditionally is fine: the overlay only opens for someone with a signed-in Shipeasy session, so on a page where nobody has authenticated it renders nothing and says nothing. Gating it on your own staff or environment check is optional — worth it only if you'd rather the bundle not load for end users at all:
String devtools = user.isStaff() ? Shipeasy.devtoolsScriptTag() : "";Identity coherence (no anon to identified flip)
When the user you evaluate carries an identified attribute (a user_id,
email, or any trait other than anonymous_id), the tag also emits a
data-user attribute — the HTML-escaped JSON of those traits, with
anonymous_id and null values dropped. The browser SDK reads it and adopts that
server-known identity on first paint, so a Java backend with a JS frontend never
shows the anonymous-then-identified flip (the same identity buckets flags on both
sides). An anonymous request — only an anonymous_id, or an empty user — emits no
data-user. See Identity & bucketing.
Change listeners
Register a listener that fires after a background poll applies new data (an
HTTP 200, not a 304). onChange returns a cancel Runnable:
// Start the background poll so listeners can fire (configure owns the lifecycle):
Shipeasy.configure(Shipeasy.options(System.getenv("SHIPEASY_SERVER_KEY")).poll(true));
Runnable cancel = Shipeasy.onChange(() -> log.info("flags updated"));
// ... later
cancel.run(); // unsubscribeListeners never fire in local/test/snapshot mode (those do no polling) and a throwing listener is isolated — it's logged, others still run.