`init()` and InitConfig reference

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

Note: Data layer triggers were extended in the release 6f8189c to support curated named-event properties, mapping transforms, and ordered fallback paths. See the SDK "triggers" runtime-settings and trigger-simulation fixtures in the repository for behavior and examples.

Runtime modes

Settings objects

Data layer trigger mappings

Each dataLayerTriggers[].when entry is a payload condition: { path, op, value? } with op one of eq, neq, gt, lt, exists, or not_exists. A trigger may carry one to five entries; all of them must match before the trigger maps signals, queues a replay, or tracks an event. path is a payload-only dot path with the same property and numeric-index grammar as mapping paths. eq, neq, gt, and lt require value (gt/lt a number; the SDK converts the payload value to the configured type before comparison); exists and not_exists forbid it.

exists matches values other than undefined and null. not_exists matches undefined or null. A missing or unconvertible path fails eq, neq, gt, and lt. Thus, neq does not fire a trigger when the configured path is missing.

Number conditions use the same conversion as signal mappings. They accept comma decimals such as 19,90 and grouped comma decimals such as 1.234,56.

Each dataLayerTriggers[].mappings[].from value reads a path from the matching data layer entry. The mapping writes that value to the runtime signal named by to. Use an array of one to five paths for ordered fallback. Apex uses the first path with a raw value. It selects that path before value transforms or type conversion.

Named events and pageviews can define a top-level properties array. When this array exists, the event contains only source, dataLayerEvent, and resolved mapped properties. Without this array, Apex keeps the full data layer payload. Mappings cannot replace source or dataLayerEvent.

Revenue and named-event property mappings use payload paths by default. Prefix a property source with signal: to read a stored or runtime signal instead:

dataLayerTriggers: [{
  eventName: "purchase",
  trackEventName: "purchase_complete",
  properties: [
    {
      from: ["customer.type", "signal:customer_type"],
      to: "customerType",
      valueType: "string",
      transform: {
        trim: true,
        lowercase: true,
        map: { vip: "wholesale" },
        default: "retail"
      }
    }
  ],
  trackRevenue: {
    enabled: true,
    revenueFrom: ["ecommerce.value", "value"],
    properties: [
      {
        from: ["order.margin", "signal:estimated_margin"],
        to: "margin",
        valueType: "number",
        transform: { scale: 0.01 }
      }
    ]
  }
}]

A mapping transform runs in this order: resolve the raw path or signal, trim and lowercase strings, apply map, convert to valueType, apply numeric scale, then use a converted default if no value remains. A map accepts at most 20 exact-match entries. Map keys and values accept at most 100 characters. A scale must be finite and non-zero.

Number conversion accepts standard JavaScript numeric strings. It also accepts comma decimals such as 19,90 and grouped comma decimals such as 1.234,56. Ambiguous forms such as 1,2,3 stay unresolved.

A plain path such as customer_type reads only the matching data layer entry. Missing sources do not add a property unless the mapping defines a valid default.

Custom dimensions from dataLayer

The SDK can now capture configured custom dimensions from matching dataLayer entries and stamp their current values onto analytics events (dimensions are sent as event-level metadata). Configure these captures via your runtime signals and dataLayerTriggers mappings; the SDK resolves the mapped value at event time and includes it on any tracked event that matches the trigger. See the release ddf5a2c for the implementing change and ticket #4184.

The signal: prefix does not apply to mappings[], revenueFrom, orderIdFrom, currencyFrom, costFrom, or profitFrom. Each element in these fallback arrays must be a payload path. Mapping transforms never apply to the five revenue anchors.

Redirect experiments

Redirect experiments run before visual mutations. Apex persists the assigned arm, queues an experiment_viewed exposure using navigation-safe delivery, preserves the source query string and hash (destination parameters win), and then replaces the current location. A loop guard keeps a visitor on the page when it already matches the destination.

Mutations, variation CSS, and variation JavaScript may coexist with a redirect destination, but they are source-page artifacts only. If the assignment is preserved on the destination for attribution, the SDK does not apply those artifacts there: the destination document itself is the treatment.

For destinations on another hostname, Apex adds the temporary _apex_assignment query parameter with the fresh visitor and assignment handover. This name is reserved for Apex redirect tests. Do not add _apex_assignment to merchant-authored destination URLs; when it is already present, Apex preserves the merchant value and does not add its assignment carry. Carry is consumed only on the configured destination entry path, not on other pages of the same host. The destination must install the same shop's Apex snippet so the SDK can import that identity and assignment, keep conversion attribution sticky, and avoid rebucketing or recording a second exposure. Consent mode deliberately omits this cross-origin carry until consent is granted: the destination mints its own visitor identity. Activity across the two origins before consent is granted cannot be linked. If the destination config is temporarily unavailable, Apex retains an eligible carry in session storage only until a later config can validate it or the handover TTL expires.

Related pages

• Consent modes
• SPA and router modes
• Anti-flicker modes
• Migration notes for deprecated aliases