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
• /settings/integrations
• /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.
• Consent provider settings were moved out of Settings → Installation into Settings → Integrations (see the Integrations page for the full configuration UI). A read-only summary of the consent provider remains on the Installation page where the snippet is kept.

• The runtime is aware of organization-level brands and operates at the brand and store granularity. UI surfaces may include a brand selector in the sidebar and a store selector under the page title for brands that contain multiple stores; ensure the runtime shop ID in the installed snippet corresponds to the currently selected store so that runtime config, assignments, and events map to the expected store context.

• When creating tests for a brand, select stores from the store selector so a single test can run in one or more stores. The test page shows store tabs and a single brand-level result alongside per-store results; server-rendered storefronts that rely on forwarded assignments should receive the worker-forwarded visitorId and signed assignments so SSR renders the correct variant without flicker.

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.

GA4 and GTM exposure integration

Enable the GA4 dataLayer exposure recipe in Settings → Integrations. Each eligible exposure pushes apex_experiment_viewed to the configured dataLayer. Map its fields to GA4 event parameters in GTM:

Field	Value
experiment_id, variation_id	Short numeric public IDs, encoded as strings; UUIDs are no longer the primary public identifier
experiment_key	Ticket key (short public key used for reporting); experiment and variation display names are not published to the storefront config
project_id	Shop UUID
variation_index	Zero-based variation index
variation_name	Index-based label computed only from the variation index, such as Variation B
is_control	Whether the assigned variation is the control
experiment_uuid, variation_uuid	Internal UUIDs retained for backward compatibility and internal consumers; they are not the primary public IDs

With includeMetadata: false, only the two ID fields and their two UUID aliases are pushed alongside event. Enabled dataLayer destinations receive public IDs regardless of this setting; older configs without public IDs fall back to UUIDs. Enabled queue destinations receive the full metadata payload.

Migration: experiment_name changes from the UUID to the ticket key. Update existing GA4/GTM mappings to use experiment_uuid and variation_uuid wherever the original UUIDs are required. The two shops already using this destination, Shinie and Men of Mayhem, need this mapping review. By decision, only identifiers are published: experiment titles, variation display names and shop names never enter the public storefront config or the push. variation_name is an index-based label such as Variation B.