Developer

`init()` and InitConfig reference

Reference every supported Apex SDK InitConfig field with its type, default, and intended use.

Call init(config) once per page load or app shell. The SDK accepts inline experiments through experiments, or it fetches running experiments when both shopId and endpoint are present.

import { init } from "@drip-apex/sdk";
 
const assignments = init({
  shopId: "demo-shop",
  endpoint: "https://events.drip-apex.com",
  antiFlickerMode: "scoped",
  trackingStart: "idle"
});

init() returns the assignments available immediately. When the SDK fetches config asynchronously, the first return value can be an empty array; read later assignments with getAssignments() or listen for the drip_initialized browser event.

Core fields

Field	Type	Default	When to use
`experiments`	`Experiment[]`	Not set	Provide inline, code-owned experiments instead of fetching by `shopId`. An empty array is valid and still initializes analytics.
`signals`	`RuntimeSignalDefinition[]`	`[]`	Define custom runtime signals that targeting can capture from URLs, DOM, globals, data layer events, or SDK events.
`shopId`	`string`	Not set	Fetch published config from the Worker and attribute events to an Apex shop. Required for hosted config fetches.
`endpoint`	`string`	Not set	Base Worker URL for `/config`, `/events`, handover minting, and order identity calls. A trailing `/events` is normalized away.
`auditEndpoint`	`string`	Apex production audit endpoint	Override signed storefront audit snapshots when using the audit build. Most installs leave this unset.
`editorBundleUrl`	`string`	Derived from the installed SDK script	Versioned URL for the lazy on-site editor bundle. Apex-hosted snippets provide this automatically; custom delivery setups can point it at their matching `editor.js` asset.
`ingestShopId`	`string`	`shopId`	Send a different shop identifier in event ingestion headers when Worker-delivered config needs a separate ingest identity.
`ingestSignature`	`string`	Not set	Sign event ingestion, handover minting, and order identity requests when the Worker provides a signature. Do not hardcode secrets in page code.
`attributes`	`Record<string, unknown>`	`{}`	Add targeting attributes for this page or visitor, merged with runtime signal-derived attributes.
`userId`	`string`	Generated visitor ID	Override the visitor/bucketing identity, for example with a stable logged-in user identifier.
`url`	`string`	`location.href`	Evaluate targeting against a supplied URL instead of the current browser location. Useful for tests and controlled rendering.
`autoTrack`	`boolean`	`true`	Set to `false` when you do not want automatic assignment exposure events. Manual event calls still work when tracking is available.
`configCache`	`boolean`	`true`	Set to `false` to disable localStorage config cache for fetched shop config. Cache is also disabled when storage is blocked.
`configCacheTtlMs`	`number`	`300000`	Change the freshness window for cached fetched config. Values must be positive numbers.
`lateConfigPolicy`	`"skip"` or `"apply"`	`"skip"`	Choose whether fetched config that arrives after the anti-flicker reveal deadline should still apply. QA and screenshot forcing uses `"apply"`.
`onExperimentViewed`	`(assignment: Assignment) => void`	Not set	Run a callback for each viewed assignment after the SDK has assigned and started exposure tracking.

Runtime modes

Field	Type	Default	When to use
`executionMode`	`"auto"`, `"edge"`, or `"client"`	`"auto"`	Keep `"auto"` for edge-first delivery with client fallback. Use `"edge"` only when an edge runtime has already initialized the page.
`platformHint`	`"auto"`, `"shopify"`, `"spa"`, or `"shopware"`	Auto-detected	Hint platform-specific router and surface behavior when auto-detection cannot identify the storefront.
`routerMode`	`"auto"`, `"history"`, `"navigation"`, or `"none"`	`"auto"`	Top-level SPA route observation mode. `spa.routerMode` takes priority when present.
`activationMode`	`"auto"`, `"observer"`, or `"manual"`	`"observer"`	Top-level mutation activation mode. `spa.activationMode` takes priority when present.
`antiFlickerMode`	`"scoped"`, `"full"`, `"custom"`, or `"off"`	`"scoped"`	Control how Apex hides content before variants apply. Use `custom` with `antiFlickerCustomCss`.
`antiFlickerTimeoutMs`	`number`	`1200`	Auto-reveal timeout for anti-flicker protection. Non-positive or invalid values fall back to `1200`.
`antiFlickerCustomCss`	`string`	Not set	CSS injected only when `antiFlickerMode` is `"custom"`.
`trackingStart`	`"idle"` or `"immediate"`	`"idle"`	Decide whether analytics setup waits for idle time or starts immediately after initialization.
`trackingIdleTimeoutMs`	`number`	`2000`	Fallback timeout for `trackingStart: "idle"`. Non-positive or invalid values fall back to `2000`.
`customJsPolicy`	`"strict"`, `"hybrid"`, or `"flex"`	`"hybrid"`	Control variation and project custom JavaScript execution. Use `"strict"` to block custom JS in production-sensitive installs.
`requireConsent`	`boolean`	`false`	Gate tracking and persistent storage until consent is granted. Variants can still render under strict consent mode.
`hasConsent`	`boolean`	Consent cookie or provider state	Seed the initial consent state when using `requireConsent` or custom consent controls.
`deferTracking`	`boolean`	Deprecated alias	Deprecated. `true` maps to `trackingStart: "idle"` and `false` maps to `"immediate"`.
`antiFlicker`	`boolean`	Deprecated alias	Deprecated. `true` maps to `antiFlickerMode: "full"` and `false` maps to `"off"`.
`antiFlickerTimeout`	`number`	Deprecated alias	Deprecated. Maps to `antiFlickerTimeoutMs`.

Settings objects

Field	Type	Default	When to use
`profile`	`ConfigProfile`	Not set	Server-provided profile metadata. The SDK currently reads `profile.platform` after `platformHint`.
`projectPrerequisites`	`ProjectPrerequisites`	No prerequisite rules	Gate variation display and tracking with project-level `showVariationsRule` and `startTrackingRule` expressions.
`consentMode`	`ConsentModeSettings`	Disabled	Configure provider-backed consent detection for custom, OneTrust, Usercentrics, Cookiebot, or CCM19.
`debug`	`DebugSettings`	Disabled	Enable restricted SDK console diagnostics by query parameter, user ID, always-on mode, or active server state.
`spa`	`SpaSettings`	Auto router, observer activation	Configure SPA router observation, DOM re-evaluation, debounce timing, iframe allowance, and reinit-only mode.
`pageTrigger`	`PageTriggerSettings`	`{ defaultMode: "direct" }`	Switch initial activation and route behavior to URL change, DOM change, or manual page triggers.
`externalTracking`	`ExternalTrackingSettings`	Disabled	Preserve bucketing across external checkout, booking, or lead-flow domains by rewriting configured links and forms.
`dataLayerTriggers`	`DataLayerTriggerSettings[]`	`[]`	Listen to data layer events, map event fields into runtime signals, re-evaluate assignments, and optionally track pageviews or revenue.
`exposureDestinations`	`ExposureDestinationsSettings`	Disabled	Send assignment exposure metadata to `dataLayer`, Hotjar, or custom queue globals.
`projectCode`	`ProjectCodeSettings`	Disabled	Apply advanced project-level CSS, helper JS, or startup JS before or after assignments.
`environments`	`RuntimeEnvironmentSettings`	Production	Select an environment key for fetched config and config-cache isolation.
`bucketingCleanup`	`BucketingCleanupSettings`	Enabled with `180` day retention	Clean stale Apex goal and config-cache storage. Set `enabled: false` to opt out.
`dataProtection`	`DataProtectionSettings`	`localStorage`, no encoding, DNT off	Choose visitor storage mode, encoded storage values, Do Not Track behavior, and cookie domain.
`semanticTracking`	`SemanticTrackingSettings`	Disabled	Capture sampled semantic visibility or click events for configured selectors.
`runtimeControl`	`RuntimeControlSettings`	Enabled runtime	Server-authoritative kill-switch state. When `disabled` is true, runtime diagnostics show the disabled state.
`deliveryState`	`"no_visual_tests"`, `"non_critical_visual"`, `"critical_visual"`, `"edge_managed"`, or `string`	Not set	Worker/snippet metadata included in SDK performance telemetry.
`scriptCacheSource`	`"edge"`, `"kv"`, `"origin"`, `"precompile"`, `"precompiled"`, or `string`	Not set	Worker/cache source label included in SDK performance telemetry.
`installSurface`	`"direct_script"`, `"shopify_app_embed"`, `"legacy_shopify_redirect"`, or `string`	Not set	Install surface label included in SDK performance telemetry.
`sdkVersion`	`string`	Not set	Worker-provided immutable SDK artifact version for release-attributed performance telemetry.
`sdkDeliveryMode`	`"global"`, `"pinned"`, `"canary"`, or `string`	Not set	Worker-provided SDK policy mode for release-attributed performance telemetry.
`sdkDeliverySource`	`"embedded"`, `"external"`, or `string`	Not set	Worker-provided artifact source for distinguishing embedded and immutable external delivery.
`sdkPolicyRevision`	`string`	Not set	Worker-provided global SDK delivery policy revision used to compile the snippet.
`runtimeProfile`	`"full"`, `"empty_project"`, `"nonvisual_assignment"`, or `string`	`"full"`	Server-authoritative runtime profile included in performance telemetry. Unknown profiles retain full behavior.
`delivery`	`SnippetDeliveryManifest`	Not set	Worker-compiled delivery manifest for precompiled critical mutation delivery. Most hand-written installs omit it.
`runtimeFeatures`	Runtime feature profile object	Not set	Worker-selected feature profile for live, heatmap, debug, QA, harness, or audit builds.
`perfFlags`	`PerfFeatureFlags`	All current perf flags enabled	Runtime kill-switch flags for staged performance features.

Core fields

Runtime modes

Settings objects

Related pages