Shipeasy
SDKsReferenceKotlin

Advanced

Attribute names usable for targeting but never persisted in analytics (privateAttributes). Since the server evaluates locally, private attrs never leave for…

Generated from the SDK's own /docs/ — also served raw at https://shipeasy-ai.github.io/sdk-kotlin/pages/advanced.md.

Private attributes

Attribute names usable for targeting but never persisted in analytics (privateAttributes). Since the server evaluates locally, private attrs never leave for evaluation at all; the only egress is /collect, and the listed keys are stripped from every outbound track() payload and see() extras.

configure(
    apiKey = System.getenv("SHIPEASY_SERVER_KEY"),
    privateAttributes = listOf("email", "ip"),
)

Sticky bucketing

Pass a StickyBucketStore so universe(name).assign() locks a unit to its first-assigned variant — changing allocation % or weights won't re-bucket enrolled units (changing the experiment salt is the reshuffle lever). Absent ⇒ deterministic (fully backward compatible). A built-in in-memory store is provided:

import ai.shipeasy.InMemoryStickyStore

configure(
    apiKey = System.getenv("SHIPEASY_SERVER_KEY"),
    stickyStore = InMemoryStickyStore(),
)

Implement the StickyBucketStore interface to back it with Redis/DB for multi-process servers.

Anonymous-id bucketing (AnonIdFilter)

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.

// Spring Boot — a default FilterRegistrationBean maps to all paths
@Bean
fun shipeasyAnonId() = FilterRegistrationBean(AnonIdFilter())

// logged-out request → buckets on the __se_anon_id cookie automatically
val flags = Client(loggedOutUser)
flags.getFlag("new_checkout")     // bound Client with no explicit unit

jakarta.servlet-api is compileOnly. Non-servlet stacks (Ktor, http4k, Javalin) can use the AnonId primitives directly. An explicit user_id/anonymous_id always wins. The cookie is non-HttpOnly by design so the browser SDK buckets identically; a request with no unit still resolves a fully-rolled (100%) gate as on. Cookie name + format are a cross-SDK contract — see 18-identity-bucketing.md.

Anonymous id in a mobile app (AnonStore)

AnonIdFilter is for a server request. A shipped Android/JVM client app has no request cookie — ShipeasyClient (see Installation) instead persists the device's __se_anon_id so bucketing is stable across app launches. Without persistence a fresh UUID every cold start silently re-buckets every fractional rollout and experiment.

The core shipeasy-kotlin jar is pure-JVM and Android-free, so persistence is a pluggable AnonStore (get/set, synchronous, best-effort). On Android, the ai.shipeasy:shipeasy-kotlin-android artifact supplies SharedPreferencesAnonStore and a one-call configureAndroid(context, clientKey); elsewhere pass your own:

import ai.shipeasy.AnonStore
import ai.shipeasy.configureClient

val store = object : AnonStore {
    override fun get(key: String): String? = /* read from your storage */ null
    override fun set(key: String, value: String) { /* persist */ }
}
configureClient(clientKey = "pk_live_…", store = store)

An InMemoryAnonStore ships for tests. The stable id is readable as shipeasyClient()?.anonymousId.

Exposure logging

universe(name).assign() is side-effect free. The exposure fires on the first get() read of a param when the unit is enrolled — reading is the exposure, so you don't call anything separately. The unit is derived from the bound Client (its user_id, else anonymous_id):

val flags = Client(currentUser)
val cta = flags.universe("hero_cta").assign() // no exposure yet
cta.get("primary_label", "Sign up")           // enrolled → one deduped exposure fires here

Repeated get() reads for the same (unit, experiment, group) collapse to a single exposure: deduped per process and durably per (unit, experiment, group) server-side. To read a param without logging an exposure — e.g. inspecting a value you aren't presenting — use peek(field, fallback):

cta.peek("primary_label", "Sign up") // read-only — never logs an exposure

See Experiments.

Change listeners — onChange

Subscribe to data-change notifications with the top-level onChange function. The listener fires after a background poll brings new data (HTTP 200, not 304) — not for the initial fetch, and never under configureForTesting / configureForOffline. Requires configure(..., poll = true). Returns an unsubscribe function.

import ai.shipeasy.onChange

val unsubscribe = onChange {
    // rebuild any cached evaluations, warm a downstream cache, etc.
}
// later
unsubscribe()

Each listener runs in a try/catch; a throwing listener is logged and does not affect the others.

Server-side rendering (SSR)

Emit the request's evaluated flags as a declarative <script> tag so the browser SDK has them on first paint. bootstrapScriptTag (a top-level function backed by the global configure() state) carries the payload in data-* attributes (no key); the static loader hydrates window.__SE_BOOTSTRAP and writes the __se_anon_id cookie so the browser buckets identically to the server.

import ai.shipeasy.bootstrapScriptTag
import ai.shipeasy.i18nScriptTag

val user = mapOf("user_id" to "u_123")

// Two tags for the document <head>. The PUBLIC client key (not the server key)
// goes on the i18n loader tag — and it comes from configure(), so the callsite
// does not repeat it.
val head = bootstrapScriptTag(user, anonId = anonId) + i18nScriptTag()

Every argument is optional

All three tag functions fall back to what configure() set, so the bare call is the normal one — pass an argument only to override that one tag:

FunctionSignatureDefaults from configure
i18nScriptTag(clientKey?, profile?, baseUrl?)clientKey, profile, cdnBaseUrl
bootstrapScriptTag(user = emptyMap(), anonId?, i18nProfile?, baseUrl?)anonymous request, profile, cdnBaseUrl
devtoolsScriptTag(projectId?, clientKey?, baseUrl?, defer = true)projectId, clientKey, cdnBaseUrl
configure(
    apiKey = 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 configure argument to fill in — once per argument, not once per render.

Devtools overlay tag

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.

import ai.shipeasy.devtoolsScriptTag

val head = 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:

val head = if (user.isStaff) devtoolsScriptTag() else ""

Server-side DevTools overrides (se_ov)

When a developer is signed in to the DevTools overlay, every override they set (including ?se_gate_x=true in the URL) is mirrored into a signed se_ov cookie that rides along on every same-origin request. Once the request is scoped, server-side reads honor it — getFlag / getFlagDetail (reason OVERRIDE), getKillswitch (whole-switch reads; the gate namespace covers kill switches), getConfig, and universe(name).assign() (forces the group).

  • Servlet stacks: register AnonIdFilter (above) — it verifies the cookie once per request and clears it afterwards. Nothing else to wire.
  • Everything else: wrap the request in withRequestOverrides(cookieHeader) { ... }. A suspend variant, withRequestOverridesSuspend, keeps the scope with the coroutine across withContext(Dispatchers.IO) hops.
import ai.shipeasy.withRequestOverrides

withRequestOverrides(call.request.headers["Cookie"]) {
    val flags = Client(currentUser)
    flags.getFlag("new_checkout")   // overridden value if DevTools set one
}

Precedence is overrideFlag(...) (programmatic) > signed cookie > normal evaluation. It is fail-closed: overrides apply only when Shipeasy served your project's override key with the flags, the cookie signature verifies, and it has not expired. Otherwise — or outside a scoped request — reads are unchanged. A bare unsigned ?se_gate_ URL parameter is client-only by design: without the signed cookie the server never trusts it.

Dev-only URL overrides (se_ov_dev)

For a local/dev/test stack where nobody signs in to DevTools, the browser SDK mirrors ?se_gate_x=true style URL overrides into an unsigned se_ov_dev cookie (non-production browser builds only). The server reads it only when both guards hold:

  1. you opted in: configure(apiKey = ..., devOverrides = true) (also accepted by configureForTesting / configureForOffline); default false; and
  2. the process is non-production — the same detection that drives the network / telemetry defaults (shipeasy.env / SHIPEASY_ENV / APP_ENV / ENV, else the env option, which defaults to prod). An unset environment counts as production. configureForTesting / configureForOffline count as non-prod.

With the option on in a production process the cookie is ignored and one warning is logged. When not honored the scope never even looks for the cookie. Precedence is programmatic > signed se_ov > se_ov_dev > evaluation, per name (the signed cookie wins on conflicts); the reason stays OVERRIDE. It is never active in production.

Frontend and API on different subdomains

If the frontend is app.example.com and the API is api.example.com, a host-only cookie never reaches the API. The browser SDK scopes the override cookies to the registrable domain automatically (or to overrideCookieDomain when set), so the API usually sees them. For token-auth APIs that don't take cookies, send the X-Shipeasy-Overrides header — its value is cookie-header syntax (se_ov=...; se_ov_dev=...); the browser SDK's getOverrideHeaders() builds it. AnonIdFilter reads it automatically; otherwise pass it as the second argument:

withRequestOverrides(
    call.request.headers["Cookie"],
    call.request.headers["X-Shipeasy-Overrides"],
) { Client(currentUser).getFlag("new_checkout") }

Per cookie name the Cookie header wins; the header fills in when the cookie is absent. The same verification applies: a signed value must verify, and se_ov_dev is never even parsed unless devOverrides is on in a non-production process. The API's CORS config must allow the X-Shipeasy-Overrides header.

Identity coherence (no anon→identified flip)

When you pass an identified user, the tag also carries that identity as a data-user attribute (the user's traits, minus anonymous_id, as escaped JSON). The browser SDK adopts it on first paint, so a Kotlin-backend + JS-frontend app renders as the identified user immediately — no anonymous-then-identified flip. An anonymous request (only anonymous_id, or an empty user) emits no data-user. See Identity & bucketing.

Was this page helpful?
Updated July 26, 2026

On this page