# 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.

```tsx
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.

```tsx
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.

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

No props. Place it as a child of `ElevateProvider`:

```tsx
<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.

```tsx
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.

```tsx
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`:

```tsx
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.

```tsx
trackPageView();
```

No parameters.

#### trackProductView

Tracks a product page view.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

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

| Parameter     | Type     | Required | Description     |
| ------------- | -------- | -------- | --------------- |
| `searchQuery` | `string` | Yes      | The search term |

#### trackCheckoutStarted

Tracks checkout initiation.

```tsx
await trackCheckoutStarted();
```

No parameters.

#### trackCheckoutCompleted

Tracks a completed order.

```tsx
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.

```tsx
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.

```tsx
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.

```tsx
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.

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

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

#### isShopifyGid

Checks whether a string is a Shopify GID format.

```tsx
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.

```tsx
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](https://claude.ai/docs/headless/shopify-hydrogen#content-security-policy-csp) for a full example.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.elevateab.com/elevate-helpcenter/headless-integration/sdk-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.