Runtime controls, SDK, anti-flicker, and consent

Simple terms

The runtime is the code on the storefront that decides eligibility, applies changes, and sends tracking events.

The browser runtime fetches experiment config, assigns visitors, applies variants, tracks goals, respects runtime settings, and batches events.

Routes

• /installation
• /api/exp
• /api/shops/runtime-settings

Implementation behavior

• The lowercase drip runtime global initializes with shop ID and worker URL, then fetches /api/exp for active runtime config.
• Assignment uses traffic allocation, variation weights, targeting, and sticky visitor cookies.
• The mutation engine applies DOM changes and custom code after eligibility is resolved.
• Goal listeners emit pageview, click, custom, revenue, and Shopify-linked events.
• Event batching flushes every five seconds or twenty events; anti-flicker can hide content until variants apply.
• Consent and runtime settings decide when tracking can run and how conservative the SDK should be.

How to use it

• Install the snippet from Store Connection and verify it in Realtime Analytics.
• Use custom tracking calls for non-DOM events.
• Tune anti-flicker only around surfaces that can visibly change.
• Keep the shop ID and worker URL aligned with the active shop.

When not to use it

• Do not bypass consent requirements for analytics tracking.
• Do not use heavy anti-flicker on pages where no visible change can happen.
• Do not use client-side SDK behavior for server-only experiments or secure backend decisions.

Implementation source

• SDK code lives in packages/sdk; Worker ingestion lives in packages/worker; Tinybird schemas and pipes live in packages/tinybird.
• Config is served by /api/exp and runtime settings are read or written through /api/shops/runtime-settings.
• Events are batched by the SDK, sent to the Worker, normalized to NDJSON, and stored in Tinybird.

Data and API

• Packages: packages/sdk, packages/worker, packages/tinybird.
• APIs: /api/exp, /api/shops/runtime-settings, and installation snippet endpoints.
• Tinybird receives normalized NDJSON from the Worker.

Failure modes

• Flicker: anti-flicker missing, selector delayed, or heavy page script contention.
• Assignments change unexpectedly: cookies cleared, visitor ID reset, or weights/status changed mid-test.
• Events missing: consent disabled, network blocked, Worker unavailable, or batching not flushed before navigation.