Install Apex on a headless React storefront

For headless React storefronts, Apex still starts with the global SDK snippet. The snippet handles anti-flicker protection, assignment, persistence, pageview tracking, and event delivery before your React tree finishes rendering. Use the npm React bindings when a test needs native branch rendering for cart logic, product modules, or state-coupled UI. Apex owns the assignment and stats; your components only read the active variation or flag.

Add the script to your app shell

Place the shop-specific snippet once in the root document head, such as Next.js app/layout.tsx or the Hydrogen app shell. Load it synchronously so the anti-flicker guard can protect the first paint before React hydrates.

<script src="<worker>/s/<shopId>.js"></script>

SPA navigation

The SDK observes browser history changes, popstate, hashchange, and the Navigation API automatically. Install the snippet in the global shell rather than adding it per route. For React route transitions that re-render product or cart modules, set routerMode to history, navigation, or auto and enable spa.domChangeTrigger when Apex should re-assert eligible changes after DOM updates.

Consent tools

Apex integrates with OneTrust, Cookiebot, Usercentrics, and CCM19 through consentMode: { enabled: true, provider: "..." }. For any other CMP, use the custom provider with a getter that returns whether tracking consent is currently granted. Keep Apex behind the same consent policy you apply to testing and analytics scripts, then run a granted-consent test visit during verification.

Branch rendering in React (npm package)

Install @drip-apex/sdk, wrap your app in DripProvider, and read useVariation(experimentId) or useFeatureFlag(flagId) inside components. This is the right path for tests that need native React state, cart behavior, or module-scoped rendering while Apex handles assignment, persistence, and stats. See the React SDK reference for every provider prop and hook.

import { DripProvider, useFeatureFlag, useVariation } from "@drip-apex/sdk/react";
 
export function StorefrontProviders({ children }: { children: React.ReactNode }) {
  return (
    <DripProvider shopId="<shopId>" endpoint="https://events.drip-apex.com">
      {children}
    </DripProvider>
  );
}
 
function ProductOffer() {
  const trustBadge = useVariation("product-trust-badge");
  const showBundle = useFeatureFlag("bundle-module");
 
  return (
    <>
      {trustBadge?.id === "instant-access" ? <InstantAccessBadge /> : null}
      {showBundle ? <BundleUpsell /> : <DefaultProductDetails />}
    </>
  );
}

Purchase attribution with Storefront API carts

Headless carts must carry Apex attribution into Shopify. When you call cartCreate or cartAttributesUpdate, append the attributes from window.drip.getCartAttributes() to the Storefront API attributes input. The method returns Array<{key, value}>, matching Shopify Storefront API AttributeInput. Orders can then attribute server-side through Shopify order webhooks.

const apexAttributes = window.drip?.getCartAttributes?.() ?? [];
 
await storefrontClient.mutate(CART_ATTRIBUTES_UPDATE, {
  variables: {
    cartId,
    attributes: [...existingAttributes, ...apexAttributes],
  },
});

Confirm events arrive

1. Publish the snippet to the headless storefront.
2. Open the live storefront and visit a tracked page.
3. If consent is required, grant consent in the banner during the test visit.
4. Return to Apex onboarding or Installation and run the verification check.

Related

• Install Apex on a custom storefront
• Install Apex on Shopify