SDK Reference

Complete API reference for the @elevateab/sdk package.

Providers

ElevateProvider

The core provider that loads A/B test configuration and manages variant assignment. Used in Remix and Hydrogen storefronts.

import { ElevateProvider } from "@elevateab/sdk";

Prop	Type	Required	Default	Description
storeId	string	Yes	—	Your Shopify store domain (e.g., "your-store.myshopify.com")
storefrontAccessToken	string	Recommended	—	Storefront API token for cart attribute tagging and order attribution
preventFlickering	boolean	No	false	Hides page content until test configuration loads to prevent variant flash
flickerTimeout	number	No	3000	Maximum time in milliseconds to wait before rendering without test config
nonce	string	Only if strict CSP	—	CSP nonce for inline scripts. Use useNonce() from @shopify/hydrogen
children	React.ReactNode	Yes	—	Your app content

ElevateNextProvider

Extended provider for Next.js that includes automatic page view tracking on route changes. Use this instead of ElevateProvider in Next.js projects.

import { ElevateNextProvider } from "@elevateab/sdk/next";

Accepts the same props as ElevateProvider.

ElevateHydrogenAnalytics

Subscribes to all of Hydrogen's Analytics.Provider events and forwards them to Elevate with A/B test data attached. Hydrogen only — just place it inside Analytics.Provider and all event tracking is handled automatically. No manual tracking calls needed.

import { ElevateHydrogenAnalytics } from "@elevateab/sdk";

No props. Place it as a child of ElevateProvider:

<Analytics.Provider cart={cart} shop={shop} consent={consent}>
  <ElevateProvider storeId="..." storefrontAccessToken="...">
    <ElevateHydrogenAnalytics />
    <Outlet />
  </ElevateProvider>
</Analytics.Provider>

---

Hooks

useExperiment

Returns variant assignment for a given experiment. The experiment must be created on the Elevate dashboard first.

import { useExperiment } from "@elevateab/sdk";

const { isControl, isA, isB, isC, isD, variant, isLoading } = useExperiment("abc123");

Parameter:

Name	Type	Description
testId	string	The experiment ID from your Elevate dashboard URL (elevateab.app/<test-id>)

Return values:

Property	Type	Description
isControl	boolean	true if the visitor is in the control group
isA	boolean	true if the visitor is in Variant A
isB	boolean	true if the visitor is in Variant B
isC	boolean	true if the visitor is in Variant C
isD	boolean	true if the visitor is in Variant D
variant	object | null	Full variant object (see below)
isLoading	boolean	true while the test configuration is being fetched

Variant object properties:

Property	Type	Description
id	string	Variant ID
name	string	Variant name
isControl	boolean	Whether this is the control variant
isA	boolean	Whether this is Variant A
isB	boolean	Whether this is Variant B
isC	boolean	Whether this is Variant C
isD	boolean	Whether this is Variant D

useElevateConfig

Access the raw configuration and credentials from the provider.

import { useElevateConfig } from "@elevateab/sdk";

const { config, storeId, storefrontAccessToken } = useElevateConfig();

Property	Type	Description
config	object	Raw A/B test configuration
storeId	string	The store domain passed to the provider
storefrontAccessToken	string	The storefront token passed to the provider

---

Tracking Functions

These functions are used for manual event tracking in Next.js and Remix. Since these frameworks don't have Shopify's Analytics.Provider, events need to be sent manually so Elevate can track conversions. In Hydrogen, all of these events are tracked automatically by ElevateHydrogenAnalytics.

All tracking functions are imported from @elevateab/sdk:

import {
  trackPageView,
  trackProductView,
  trackAddToCart,
  trackRemoveFromCart,
  trackCartView,
  trackSearchSubmitted,
  trackCheckoutStarted,
  trackCheckoutCompleted,
} from "@elevateab/sdk";

trackPageView

Tracks a page view. Called automatically by ElevateNextProvider on route changes in Next.js.

trackPageView();

No parameters.

trackProductView

Tracks a product page view.

trackProductView({
  productId: "123456789",
  productPrice: 29.99,
  productVendor: "Brand Name",  // optional
  currency: "USD",              // optional
});

Parameter	Type	Required	Description
productId	string	Yes	Shopify product ID (GIDs accepted)
productPrice	number	Yes	Product price
productVendor	string	No	Product vendor/brand
currency	string	No	Currency code (e.g., "USD")

trackAddToCart

Tracks an add-to-cart event and tags the cart with A/B test data for order attribution.

await trackAddToCart({
  productId: "123456789",
  variantId: "987654321",
  productPrice: 99.99,
  productQuantity: 1,
  currency: "USD",
  cartId: "gid://shopify/Cart/abc123",
});

Parameter	Type	Required	Description
productId	string	Yes	Shopify product ID (GIDs accepted)
variantId	string	Yes	Shopify variant ID (GIDs accepted)
productPrice	number	Yes	Product price
productQuantity	number	Yes	Quantity added
currency	string	No	Currency code
cartId	string	Recommended	Cart ID for order attribution

trackRemoveFromCart

Tracks a remove-from-cart event.

await trackRemoveFromCart({
  productId: "123456789",
  variantId: "987654321",
  productPrice: 99.99,
  productQuantity: 1,
});

Parameter	Type	Required	Description
productId	string	Yes	Shopify product ID
variantId	string	Yes	Shopify variant ID
productPrice	number	Yes	Product price
productQuantity	number	Yes	Quantity removed

trackCartView

Tracks a cart page view.

await trackCartView({
  cartTotalPrice: 199.99,
  cartTotalQuantity: 2,
  currency: "USD",
  cartItems: [
    { productId: "123", variantId: "456", productPrice: 99.99, productQuantity: 1 },
    { productId: "789", variantId: "012", productPrice: 100.00, productQuantity: 1 },
  ],
});

Parameter	Type	Required	Description
cartTotalPrice	number	Yes	Total cart value
cartTotalQuantity	number	Yes	Total items in cart
currency	string	No	Currency code
cartItems	array	No	Array of cart item objects

Cart item object:

Property	Type	Required	Description
productId	string	Yes	Product ID
variantId	string	Yes	Variant ID
productPrice	number	Yes	Item price
productQuantity	number	Yes	Item quantity

trackSearchSubmitted

Tracks a search query.

await trackSearchSubmitted({ searchQuery: "blue shirt" });

Parameter	Type	Required	Description
searchQuery	string	Yes	The search term

trackCheckoutStarted

Tracks checkout initiation.

await trackCheckoutStarted();

No parameters.

trackCheckoutCompleted

Tracks a completed order.

await trackCheckoutCompleted();

No parameters.

Event Tracking by Framework

Event	Hydrogen	Next.js	Remix
Page view	Automatic	Automatic	Automatic
Product view	Automatic	ProductViewTracker	trackProductView()
Add to cart	Automatic	trackAddToCart()	trackAddToCart()
Remove from cart	Automatic	trackRemoveFromCart()	trackRemoveFromCart()
Cart view	Automatic	trackCartView()	trackCartView()
Search	Automatic	trackSearchSubmitted()	trackSearchSubmitted()
Checkout started	Automatic	trackCheckoutStarted()	trackCheckoutStarted()
Checkout completed	Automatic	trackCheckoutCompleted()	trackCheckoutCompleted()

---

Components

ProductViewTracker (Next.js only)

A drop-in component for tracking product views in Next.js. Fires a trackProductView event when the component mounts.

import { ProductViewTracker } from "@elevateab/sdk/next";

Prop	Type	Required	Description
productId	string	Yes	Shopify product ID
productPrice	number	Yes	Product price
productVendor	string	No	Product vendor/brand
currency	string	No	Currency code

Renders no visible UI.

---

Cart Attribute Utilities

These utilities manage cart attribute tagging for order attribution. In most cases, you won't need to call these directly — trackAddToCart handles tagging automatically when you pass a cartId.

updateCartAttributes

Manually updates a cart with A/B test variant data.

import { updateCartAttributes } from "@elevateab/sdk";

await updateCartAttributes(cartId, { storefrontAccessToken });

Parameter	Type	Required	Description
cartId	string	Yes	The Shopify cart ID
options.storefrontAccessToken	string	Yes	Storefront API token

getCartAttributesPayload

Returns the current A/B test data as a cart attributes payload object. Useful if you have a custom cart implementation and need to tag attributes yourself.

import { getCartAttributesPayload } from "@elevateab/sdk";

const attributes = getCartAttributesPayload();

No parameters. Returns an object with the current A/B test variant data formatted for Shopify cart attributes.

---

Utility Functions

extractShopifyId

Extracts the numeric ID from a Shopify GID string.

import { extractShopifyId } from "@elevateab/sdk";

extractShopifyId("gid://shopify/Product/123456"); // "123456"
extractShopifyId("123456");                        // "123456"

isShopifyGid

Checks whether a string is a Shopify GID format.

import { isShopifyGid } from "@elevateab/sdk";

isShopifyGid("gid://shopify/Product/123"); // true
isShopifyGid("123456");                     // false

isPreviewMode

Checks whether the current page is being viewed in preview mode.

import { isPreviewMode } from "@elevateab/sdk";

if (isPreviewMode()) {
  // Show preview indicator
}

No parameters. Returns true if the URL contains the eabUserPreview=true parameter.

---

CSP Domains

If your site enforces a strict Content Security Policy, add the following domains:

Directive	Domains
script-src	https://ds0wlyksfn0sb.cloudfront.net
script-src-elem	https://ds0wlyksfn0sb.cloudfront.net
connect-src	https://ds0wlyksfn0sb.cloudfront.net https://d339co84ntxcme.cloudfront.net https://configs.elevateab.com

For Hydrogen, pass the nonce from useNonce() to ElevateProvider. See the Shopify Hydrogen guide for a full example.