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