@elevateab/sdk 1.4.8 → 1.4.10

package/README.md

@@ -9,6 +9,7 @@ npm install @elevateab/sdk
 ```
 
 **Peer Dependencies:**
+
 - `react` >= 18.0.0 or >= 19.0.0
 - `@shopify/hydrogen` >= 2023.10.0 (Hydrogen only)
 - `next` >= 13.0.0 (Next.js only)
@@ -19,22 +20,57 @@ npm install @elevateab/sdk
 
 Hydrogen uses automatic analytics tracking via Shopify's `useAnalytics()` hook.
 
+### 1. Content Security Policy (CSP) Setup (first)
+
+If your store uses a strict CSP, allow Elevate domains before wiring the provider.
+
+```tsx
+// app/entry.server.tsx
+import { createContentSecurityPolicy } from "@shopify/hydrogen";
+
+const { nonce, header, NonceProvider } = createContentSecurityPolicy({
+  shop: {
+    checkoutDomain: context.env.PUBLIC_CHECKOUT_DOMAIN,
+    storeDomain: context.env.PUBLIC_STORE_DOMAIN,
+  },
+  scriptSrc: [
+    "'self'",
+    "https://cdn.shopify.com",
+    "https://ds0wlyksfn0sb.cloudfront.net",
+  ],
+  connectSrc: [
+    "https://ds0wlyksfn0sb.cloudfront.net",
+    "https://bitter-river-9c62.support-67d.workers.dev",
+    "https://d339co84ntxcme.cloudfront.net",
+    "https://configs.elevateab.com",
+  ],
+});
+```
+
+### 2. Add Elevate Provider + Hydrogen Analytics
+
 ```tsx
 // app/root.tsx
-import { ElevateProvider, ElevateAnalytics } from "@elevateab/sdk";
-import { Analytics } from "@shopify/hydrogen";
+import { Analytics, useNonce } from "@shopify/hydrogen";
+import { ElevateProvider } from "@elevateab/sdk";
+import { ElevateHydrogenAnalytics } from "@elevateab/sdk/hydrogen";
+import { Outlet, useLoaderData } from "@remix-run/react";
 
 export default function Root() {
   const data = useLoaderData<typeof loader>();
+  const nonce = useNonce();
 
   return (
     <Analytics.Provider cart={data.cart} shop={data.shop} consent={data.consent}>
+      {/* ElevateProvider must be inside Analytics.Provider */}
       <ElevateProvider
         storeId="mystore.myshopify.com"
-        storefrontAccessToken={env.PUBLIC_STOREFRONT_API_TOKEN}
+        storefrontAccessToken={data.consent?.storefrontAccessToken}
         preventFlickering={true}
+        nonce={nonce}
       >
-        <ElevateAnalytics />
+        {/* ElevateHydrogenAnalytics must be inside ElevateProvider */}
+        <ElevateHydrogenAnalytics />
         <Outlet />
       </ElevateProvider>
     </Analytics.Provider>
@@ -76,6 +112,7 @@ export default function RootLayout({ children }) {
 ```
 
 The `ElevateNextProvider` automatically:
+
 - Tracks page views on route changes
 - Initializes analytics globally
 - Prevents content flicker (when `preventFlickering={true}`)
@@ -109,12 +146,12 @@ import { trackAddToCart } from "@elevateab/sdk";
 async function handleAddToCart() {
   // Shopify GIDs are automatically converted to numeric IDs
   await trackAddToCart({
-    productId: product.id,           // "gid://shopify/Product/123" works
-    variantId: variant.id,           // "gid://shopify/ProductVariant/456" works
+    productId: product.id, // "gid://shopify/Product/123" works
+    variantId: variant.id, // "gid://shopify/ProductVariant/456" works
     productPrice: 99.99,
     productQuantity: 1,
     currency: "USD",
-    cartId: cart.id,                 // For cart attribute tagging
+    cartId: cart.id, // For cart attribute tagging
   });
 }
 ```
@@ -144,7 +181,12 @@ await trackCartView({
   cartTotalQuantity: 2,
   currency: "USD",
   cartItems: [
-    { productId: "123", variantId: "456", productPrice: 99.99, productQuantity: 1 },
+    {
+      productId: "123",
+      variantId: "456",
+      productPrice: 99.99,
+      productQuantity: 1,
+    },
   ],
 });
 
@@ -156,7 +198,9 @@ await trackSearchSubmitted({ searchQuery: "blue shirt" });
 
 ## Using A/B Tests
 
-### useExperiment Hook
+### useExperiment Hook (optional)
+
+> **Note:** `useExperiment` is only needed if you want to write conditional logic in your components based on which variant a user is in. Most test types (content, custom code, split URL, price) run automatically — you don't need this hook for those.
 
 ```tsx
 import { useExperiment } from "@elevateab/sdk";
@@ -169,7 +213,7 @@ function PricingSection() {
   if (variant?.isControl) {
     return <Price amount={99.99} />;
   }
-  
+
   return <Price amount={79.99} />;
 }
 ```
@@ -179,13 +223,13 @@ function PricingSection() {
 ```tsx
 const { variant } = useExperiment("test-id");
 
-variant?.isControl  // true if control group
-variant?.isA        // true if variant A
-variant?.isB        // true if variant B
-variant?.isC        // true if variant C
-variant?.isD        // true if variant D
-variant?.id         // variant ID
-variant?.name       // variant name
+variant?.isControl; // true if control group
+variant?.isA; // true if variant A
+variant?.isB; // true if variant B
+variant?.isC; // true if variant C
+variant?.isD; // true if variant D
+variant?.id; // variant ID
+variant?.name; // variant name
 ```
 
 ### Multiple Variants
@@ -213,6 +257,7 @@ https://yourstore.com/?eabUserPreview=true&abtid=<test-id>&eab_tests=<short-id>_
 ```
 
 Example:
+
 ```
 https://yourstore.com/products/shirt?eabUserPreview=true&abtid=abc123&eab_tests=c123_12345
 ```
@@ -265,7 +310,7 @@ The Storefront Access Token is safe to use client-side - it's a public token des
 import { extractShopifyId, isShopifyGid } from "@elevateab/sdk";
 
 extractShopifyId("gid://shopify/Product/123456"); // "123456"
-isShopifyGid("gid://shopify/Product/123");        // true
+isShopifyGid("gid://shopify/Product/123"); // true
 ```
 
 Note: Tracking functions automatically extract IDs, so you rarely need these directly.
@@ -278,25 +323,25 @@ Note: Tracking functions automatically extract IDs, so you rarely need these dir
 
 ```tsx
 interface ElevateProviderProps {
-  storeId: string;                    // Required: your-store.myshopify.com
-  storefrontAccessToken?: string;     // For cart attribute tagging
-  preventFlickering?: boolean;        // Enable anti-flicker (default: false)
-  flickerTimeout?: number;            // Max wait time in ms (default: 3000)
+  storeId: string; // Required: your-store.myshopify.com
+  storefrontAccessToken?: string; // For cart attribute tagging
+  preventFlickering?: boolean; // Enable anti-flicker (default: false)
+  flickerTimeout?: number; // Max wait time in ms (default: 3000)
   children: React.ReactNode;
 }
 ```
 
 ### Analytics Events Summary
 
-| Event | Hydrogen | Next.js |
-|-------|----------|---------|
-| Page view | Automatic | Automatic |
-| Product view | Automatic | `ProductViewTracker` |
-| Add to cart | Automatic | `trackAddToCart()` |
-| Remove from cart | Automatic | `trackRemoveFromCart()` |
-| Cart view | Automatic | `trackCartView()` |
-| Search | Automatic | `trackSearchSubmitted()` |
-| Checkout started | Automatic | `trackCheckoutStarted()` |
+| Event              | Hydrogen  | Next.js                    |
+| ------------------ | --------- | -------------------------- |
+| Page view          | Automatic | Automatic                  |
+| Product view       | Automatic | `ProductViewTracker`       |
+| Add to cart        | Automatic | `trackAddToCart()`         |
+| Remove from cart   | Automatic | `trackRemoveFromCart()`    |
+| Cart view          | Automatic | `trackCartView()`          |
+| Search             | Automatic | `trackSearchSubmitted()`   |
+| Checkout started   | Automatic | `trackCheckoutStarted()`   |
 | Checkout completed | Automatic | `trackCheckoutCompleted()` |
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevateab/sdk",
-  "version": "1.4.8",
+  "version": "1.4.10",
   "description": "Elevate AB Testing SDK for Hydrogen and Remix frameworks",
   "type": "module",
   "main": "./dist/index.cjs",