Apex SDK

Browser runtime for Apex experiments, feature flags, DOM mutations, consent-aware tracking, and React bindings.

Install

Use the hosted script for most storefronts:

<script async src="https://sdk.drip-apex.com/drip.js"></script>
<script>
  window.Drip.init({
    shopId: "demo-shop",
    endpoint: "https://events.drip-apex.com"
  });
</script>

Use npm for typed app integrations:

npm install @drip-apex/sdk

import { init, trackGoal } from "@drip-apex/sdk";

init({
  shopId: "demo-shop",
  endpoint: "https://events.drip-apex.com"
});

trackGoal("add-to-cart-click");

Strict CSP storefronts

For script-src 'strict-dynamic' sites, prefer the self-initializing shop-specific bundle and render its script tag with the page's per-request nonce; a host allowlist does not authorize it. If you must use the generic hosted drip.js flow above, put the same per-request nonce on every script block, including the inline queue bootstrap and Drip.init call: strict-dynamic does not authorize inline siblings merely because the external loader is nonced. Add https://events.drip-apex.com to connect-src so event POSTs are not blocked. npm imports are compiled into the already-authorized application bundle and do not need a separate Apex loader nonce. An already-nonced Google Tag Manager container can load Apex as an alternative, with later execution and therefore weaker first-paint anti-flicker coverage. See the SDK quickstart for the self-initializing example and fully nonced generic fallback.

Manual callback page triggers

For manual-callback mode, triggerJs retries for up to 10 runs or 10 seconds, whichever comes first; if activation has not occurred by then it stops. Keep it idempotent, install your own listener, or call activate asynchronously when your prerequisite may appear after those bounds.

Hosted-script gift choosers

After the hosted SDK loads, read window.drip.getPendingGiftChoices() when your chooser mounts. This returns current unanswered choices, including choices announced before your script attached. An empty array means no choice is pending. Pass an experiment ID to read only that experiment.

Register apex:gwp:choice before the first read. Request replay with apex:gwp:choice:request to recover prompts during an active cart reconciliation. Keep the listener for future choices. Do not rely on receiving the original event.

// Call after the hosted SDK has loaded and window.drip is available.
function mountGiftChooser(renderChoices) {
  const sdk = window.drip;
  if (!sdk?.getPendingGiftChoices || !sdk?.selectGiftOption) {
    throw new Error("Load the Apex SDK before mounting the gift chooser.");
  }

  let mounted = true;
  function refresh() {
    if (!mounted) return;
    renderChoices(sdk.getPendingGiftChoices(), async (experimentId, variantGid) => {
      await sdk.selectGiftOption(experimentId, variantGid);
      refresh();
    });
  }

  window.addEventListener("apex:gwp:choice", refresh);
  refresh();
  window.dispatchEvent(new CustomEvent("apex:gwp:choice:request"));

  return () => {
    mounted = false;
    window.removeEventListener("apex:gwp:choice", refresh);
  };
}

Supply your own renderChoices(choices, onSelect) function. Replace the displayed choice list on each call, including an empty list. Getter results and replay events can repeat the same prompt. Use each prompt's experimentId, threshold, and options; each option is a Shopify product variant GID. Call onSelect with an offered option, and handle rejected promises in your chooser.

Call the returned cleanup function when the chooser unmounts. The SDK validates the current offer again during selection, so a resolved promise does not prove that an expired choice added a gift. Refresh from the getter after cart updates if your integration needs to remove choices when eligibility changes.

For a separately bundled chooser, import getPendingGiftChoices and selectGiftOption from @drip-apex/sdk/chooser. These wrappers use the hosted window.drip runtime when present, preserving its current gift state.

Docs

• Bundle budget policy and monthly review
• SDK quickstart: https://app.drip-apex.com/docs/sdk/install-quickstart
• InitConfig reference: https://app.drip-apex.com/docs/sdk/init-config
• Runtime API: https://app.drip-apex.com/docs/sdk/runtime-api
• React bindings: https://app.drip-apex.com/docs/sdk/react-bindings
• CLI GitOps push: https://app.drip-apex.com/docs/cli/push-gitops