Shipeasy
SDKsReferenceRuby

Advanced

Experiment exposure is automatic: universe(name).assign logs a single exposure event the moment a unit is enrolled — reading is the exposure, so there is no…

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

Exposure logging (auto)

Experiment exposure is automatic: universe(name).assign logs a single exposure event the moment a unit is enrolled — reading is the exposure, so there is no separate log_exposure call.

# construct once per callsite (cheap; binds the user)
flags = Shipeasy::Client.new(current_user)

flags.universe("checkout").assign   # enrolled → one exposure POSTed (fire-and-forget)

The exposure is deduped per process per (unit, experiment, group), so repeated assign calls in one server don't spam /collect. It's a no-op when the unit isn't enrolled and under configure_for_testing / configure_for_offline.

Private attributes

Pass c.private_attributes to Shipeasy.configure to strip the named keys from every outbound event (track props and see extras) before it leaves the process (privateAttributes). The server evaluates locally, so private attrs still drive targeting — they just never reach /collect:

Shipeasy.configure do |c|
  c.api_key            = ENV.fetch("SHIPEASY_SERVER_KEY")
  c.private_attributes = ["email", "ssn"]
end

Matched keys (string or symbol) are dropped from egress; targeting still uses them in-process.

Sticky bucketing

Pass c.sticky_store to configure to pin a user's experiment assignment across allocation changes. Shipeasy::SDK::InMemoryStickyStore is built in; implement your own (get(unit) / set(unit, exp, entry)) for a durable backend (e.g. Redis):

Shipeasy.configure do |c|
  c.api_key      = ENV.fetch("SHIPEASY_SERVER_KEY")
  c.sticky_store = Shipeasy::SDK::InMemoryStickyStore.new
end

Absent a store, bucketing is deterministic (MurmurHash3 over the unit).

Bucketing unit (bucketBy)

The bucketing unit per experiment is server-driven: an experiment can be configured to bucket on a non-default attribute (e.g. company_id) in the dashboard, and the SDK reads it from the experiment definition — falling back to user_id then anonymous_id. Make sure that attribute is present in the user map you pass.

Anonymous-id bucketing (Rack middleware)

For logged-out traffic you need a stable unit so a fractional rollout buckets the same on the server and the browser. In Rails this is automatic: a Railtie mounts Shipeasy::SDK::RackMiddleware, which mints the shared __se_anon_id first-party cookie for any request without one. Evaluations then default to it with no per-call wiring:

# current_user is nil → buckets on the __se_anon_id cookie automatically
Shipeasy::Client.new({}).get_flag("new_checkout")

An explicit user_id / anonymous_id always wins. The id is also on the Rack env as request.env["shipeasy.anon_id"]. The cookie is non-HttpOnly by design so the browser SDK buckets identically (cross-SDK contract — see 18-identity-bucketing.md).

For Sinatra / Hanami / bare Rack (no Railtie), mount it yourself:

use Shipeasy::SDK::RackMiddleware

DevTools overrides on server reads

When a teammate is signed in to the Shipeasy DevTools overlay, every override they set in the browser (including the ?se_gate_<name>=true URL state) is mirrored into a signed se_ov cookie. Cookies reach the server on every same-origin request — page loads and GraphQL/XHR alike — so server-side reads can honour them. Shipeasy::SDK::RackMiddleware (auto-mounted by the Rails Railtie; add use Shipeasy::SDK::RackMiddleware for Sinatra / bare Rack) verifies the cookie once per request and scopes the result to that request. Every Shipeasy::Client read inside it then resolves:

  1. a programmatic override (Shipeasy.override_flag and friends), then
  2. the signed cookie override, then
  3. normal evaluation.
readcookie override
get_flag / get_flag_detailgate value, reason OVERRIDE
get_killswitch(name)the same gate namespace (whole-switch read only; per-key switch_key reads are untouched)
get_configreplaces the value (your decoder still runs)
universe(name).assignforces that experiment's group (variant params from the blob)

Outside Rack (a job, a GraphQL executor, a custom server) scope it yourself:

# cookie_header: the raw Cookie header, or the bare se_ov value
Shipeasy.with_request_overrides(request.headers["Cookie"]) do
  Shipeasy::Client.new(current_user).get_flag("new_checkout")
end

It is stored in fiber storage (Ruby 3.2+, inherited by child fibers such as GraphQL::Dataloader) or fiber-local state on older Rubies, so concurrent requests never bleed, and it is cleared when the block / request ends.

Fail closed. The cookie is only trusted when Shipeasy served your project's override key to the SDK, the HMAC signature verifies, the key id matches, and it has not expired; anything else is ignored and reads evaluate normally. A bare ?se_gate_ URL parameter with no signed-in DevTools session never reaches the server — it stays client-only by design.

Local dev: ?se_gate_x=true without signing in

On a dev machine you can skip DevTools sign-in. The browser SDK mirrors the page's ?se_gate_ / se_ks_ / se_config_ / se_exp_ URL params into an unsigned se_ov_dev cookie (non-production browser builds only), and the server reads it when you opt in:

Shipeasy.configure do |c|
  c.dev_overrides = true   # default false
end

Two guards, both required: the option is on and the process is non-production (SHIPEASY_ENV, then RAILS_ENV / RACK_ENV / APP_ENV; unset means production; configure_for_testing counts as non-production). In a production process the option is ignored with one warning, and the middleware / scope helper never looks at the cookie, so it is never active in production. Precedence per name: programmatic override, then signed se_ov, then se_ov_dev, then normal evaluation; the reason stays OVERRIDE.

Frontend and API on different subdomains

With the app on app.example.com and the API on api.example.com, the browser SDK and DevTools overlay scope the override cookies to the registrable domain (auto-detected, or set overrideCookieDomain in the browser configure()), so the API receives them and the middleware above just works. For token-auth APIs or origins the cookie cannot reach, the browser also exposes getOverrideHeaders() (from @shipeasy/sdk/client), which returns { "X-Shipeasy-Overrides": "<cookie-header syntax>" }; send it with your requests (your API's CORS must allow that header). RackMiddleware reads it automatically (HTTP_X_SHIPEASY_OVERRIDES), with the same verification and dev-guards as the cookies; the Cookie header wins per cookie name and the custom header fills in when the cookie is absent. Outside Rack:

Shipeasy.with_request_overrides(
  request.headers["Cookie"],
  overrides_header: request.headers["X-Shipeasy-Overrides"],
) do
  Shipeasy::Client.new(current_user).get_flag("new_checkout")
end

Change listeners

Shipeasy.on_change registers a callback fired after a background poll fetches new flag/config data (HTTP 200, not a 304). It requires configure(poll: true), accepts a block or any callable, and returns an unsubscribe proc. Listeners never fire in test/offline mode. A raising listener is isolated and logged, not propagated.

unsubscribe = Shipeasy.on_change { reload_local_cache! }
# ... later
unsubscribe.call

Server-side rendering (SSR)

Emit the request's evaluated flags as a declarative <script> tag so the browser SDK has them on first paint. Shipeasy.bootstrap_script_tag carries the payload in data-* attributes (no key); 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. Every tag helper is package-level — they delegate to the engine configured via configure, so you never touch it directly.

<%# The document <head>, in full. The PUBLIC client key (never the server key)
    goes on the i18n loader tag; the bootstrap tag embeds no key at all. %>
<%= Shipeasy.bootstrap_script_tag(user, anon_id: anon_id) %>
<%= Shipeasy.i18n_script_tag %>

Every argument is optional

All three tag helpers fall back to what Shipeasy.configure already set, so the bare call is the normal one — pass an argument only to override the configured value for that one tag. Under Rails each returns html_safe markup, so <%= … %> renders it without a .html_safe at the callsite.

HelperSignatureDefaults
Shipeasy.i18n_script_tag(client_key = nil, profile:, base_url:)config.public_key, config.profile, config.cdn_base_url
Shipeasy.bootstrap_script_tag(user = nil, anon_id:, i18n_profile:, base_url:)anonymous request, no anon id, config.profile, config.cdn_base_url
Shipeasy.devtools_script_tag(project_id = nil, client_key:, base_url:, defer: true)config.project_id, config.public_key, config.cdn_base_url

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 setting to fill in.

In Rails, the i18n_head_tags view helper renders the inline label blob plus the loader tag from your app config — see i18n.

Devtools overlay tag

Shipeasy.devtools_script_tag emits the hosted devtools overlay bundle — nothing to install, no overlay code in your bundle. 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 by default: a developer tool never belongs on the critical rendering path.

Shipeasy.configure do |c|
  c.api_key    = ENV.fetch("SHIPEASY_SERVER_KEY")
  c.public_key = ENV.fetch("SHIPEASY_CLIENT_KEY")
  c.project_id = ENV.fetch("SHIPEASY_PROJECT_ID")   # for the devtools tag
end
<%= Shipeasy.devtools_script_tag %>

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:

<% if current_user&.staff? %><%= Shipeasy.devtools_script_tag %><% end %>

No anon→identified flip

When you pass an identified user (any trait beyond anonymous_id), the tag also carries that identity as data-user — the user's traits minus anonymous_id, as HTML-escaped JSON. The browser SDK adopts it on first paint, so a Ruby-backend + JS-frontend app never flips from anonymous to identified after hydration; both sides bucket on the same identity from the first render. A purely anonymous request (only anonymous_id, or an empty user) emits no data-user. See Identity & bucketing.

Evaluation internals

  • Gates — modern gates carry an ordered gatekeeper stack: entries are tried top-to-bottom and the gate passes on the first whose rules match and whose rollout bucket hits (each entry buckets at its own rollout %, with a linear ramp supported over time). A gate with no stack falls back to the legacy flat path: rules matched in order, then rollout bucket = murmur3("#{salt}:#{uid}") % 10000 < rollout_pct.
  • Experiments — status == "running", optional targeting gate, universe holdout range, allocation bucket, then group assignment by weight.
  • MurmurHash3 — pure-Ruby x86_32 variant, seed 0.
  • ETag caching — each poll sends If-None-Match; a 304 skips the JSON parse.
  • Poll interval — defaults to 30 s; overridden by the X-Poll-Interval header from the flags endpoint.
Was this page helpful?
Updated July 26, 2026

On this page