ApexDocsOpen Apex
Developer

Runtime API

Reference the Apex SDK runtime functions for initialization, tracking, consent, flags, diagnostics, and assignment state.

Import runtime functions from @drip-apex/sdk, or call the browser globals after the hosted script has loaded. The hosted script exposes window.drip, window.Drip, window.Apex, and window.apexTools compatibility surfaces.

Initialization and state

FunctionSignatureUse
init(config: InitConfig) => Assignment[]Initialize the SDK with inline experiments or fetched config.
reInit(forceReapply?: boolean) => Assignment[]Re-evaluate assignments manually, optionally forcing mutations to reapply.
recheckPrerequisites() => voidRe-run project prerequisite gates and start or stop analytics if consent or state changed.
getAssignments() => Assignment[]Read current active assignments.
getExperiments() => Experiment[]Read loaded experiment configs.
getRuntimeTools() => ApexRuntimeToolsGet the runtime tools object used by custom JS and page triggers.
getDiagnostics() => SdkDiagnosticsRead public diagnostics; debug-only fields appear only when debug mode is enabled.
getCartAttributes() => CartAttributeEntry[]Build the authoritative cart-attribute attribution stamp for a headless Shopify cart.
getCartMetafields(options?: { namespace?: string }) => Array<{ key: string; type: string; value: string }>Build an optional BI mirror for cartMetafieldsSet. key is composite (namespace.attributeKey); namespaces accept 2–255 ASCII letters, digits, _, or -, and invalid values fall back to apex. See the headless integration guide.
getCartMetafieldStaleKeys(options?: { namespace?: string }) => string[]Return every mirrorable composite key missing from the current getCartMetafields() output. Pass these keys to cartMetafieldDelete to clear stale optional mirror values. Use the same namespace option for both helpers.

Tracking

FunctionSignatureUse
track(type: string, data?: Record<string, unknown>, experimentId?: string, variationId?: string) => voidSend a custom event and trigger matching custom goals. Defaults to the first active assignment when IDs are omitted.
trackStep(name: string, data?: Record<string, unknown>) => voidSend a virtual funnel step as funnel_step; dedupes once per session unless data.oncePerSession is false.
trackGoal(goalId: string, data?: Record<string, unknown>) => voidTrigger a configured Apex goal by ID for current assignments.
trackRevenue(revenue: number, data?: RevenueEventData) => voidSend a revenue goal with goal ID __revenue__ for every active assignment.
flush() => Promise<void>Start analytics if ready and flush queued events. Resolves immediately when no tracker exists.
ts
import { flush, track, trackGoal, trackRevenue, trackStep } from "@drip-apex/sdk";
 
track("add_to_cart", { product_id: "example-product", value: 49 });
trackStep("postcode_submitted");
trackGoal("checkout-started");
trackRevenue(119, { orderId: "order-example-1002", currency: "EUR" });
 
await flush();
FunctionSignatureUse
setConsent(granted: boolean) => voidPersist consent state, clear storage when denied, and recheck assignment/tracking prerequisites.

Feature flags

FunctionSignatureUse
evaluateFlag(flagId: string, context?) => booleanReturn true when the visitor is assigned to a non-control variation.
evaluateFlagValueevaluateFlagValue<T>(flagId, fallback?, context?)Return the assigned variation value, or the fallback when unavailable.
ts
import { evaluateFlag, evaluateFlagValue } from "@drip-apex/sdk";
 
const enabled = evaluateFlag("checkout-progress-ui");
const ctaCopy = evaluateFlagValue("checkout-cta-copy", "Continue to checkout");

Diagnostics

ts
import { getDiagnostics } from "@drip-apex/sdk";
 
const diagnostics = getDiagnostics();
console.log({
  initialized: diagnostics.initialized,
  assignments: diagnostics.assignments,
  configSource: diagnostics.configSource,
  runtime: diagnostics.runtime
});

getDiagnostics() is safe for support tooling because it redacts consent and tracking-block details unless SDK debug mode is enabled.