npm - @elevateab/sdk - Versions diffs - 1.2.2 → 1.2.4 - Mend

@elevateab/sdk 1.2.2 → 1.2.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/README.md CHANGED Viewed

@@ -47,37 +47,33 @@ That's it. Analytics events are tracked automatically when users view pages, pro
 ### 2. Add Anti-Flicker (Recommended)
-Prevents content flash while tests load. Add this script to `<head>` before any other scripts:
+Prevents content flash while tests load:
 ```tsx
 // app/root.tsx
+import { ElevateProvider, ElevateAnalytics, AntiFlickerScript } from "@elevateab/sdk";
 export default function Root() {
   return (
     <html>
       <head>
-        <script
-          dangerouslySetInnerHTML={{
-            __html: `(function(){var d=document.documentElement;d.style.opacity='0';d.style.transition='opacity 0.2s';window.__eabReveal=function(){d.style.opacity='1'};setTimeout(window.__eabReveal,2000)})();`,
-          }}
-        />
-        {/* other head elements */}
+        <AntiFlickerScript />
       </head>
-      <body>{/* ... */}</body>
+      <body>
+        <ElevateProvider
+          storeId="mystore.myshopify.com"
+          storefrontAccessToken={env.PUBLIC_STOREFRONT_API_TOKEN}
+          preventFlickering={true}
+        >
+          <ElevateAnalytics />
+          <Outlet />
+        </ElevateProvider>
+      </body>
     </html>
   );
 }
 ```
-Then pass `preventFlickering` to the provider:
-```tsx
-<ElevateProvider
-  storeId="mystore.myshopify.com"
-  storefrontAccessToken={env.PUBLIC_STOREFRONT_API_TOKEN}
-  preventFlickering={true}
->
-```
 ---
 ## Next.js Setup
@@ -88,18 +84,13 @@ Next.js requires manual tracking since it doesn't have Shopify's analytics syste
 ```tsx
 // app/layout.tsx
-import { ElevateNextProvider } from "@elevateab/sdk/next";
+import { ElevateNextProvider, AntiFlickerScript } from "@elevateab/sdk/next";
 export default function RootLayout({ children }) {
   return (
     <html>
       <head>
-        {/* Anti-flicker script (optional but recommended) */}
-        <script
-          dangerouslySetInnerHTML={{
-            __html: `(function(){var d=document.documentElement;d.style.opacity='0';d.style.transition='opacity 0.2s';window.__eabReveal=function(){d.style.opacity='1'};setTimeout(window.__eabReveal,2000)})();`,
-          }}
-        />
+        <AntiFlickerScript />
       </head>
       <body>
         <ElevateNextProvider
@@ -159,6 +150,54 @@ async function handleAddToCart() {
 }
 ```
+### 4. Other Tracking Events
+```tsx
+import {
+  trackRemoveFromCart,
+  trackCartView,
+  trackSearchSubmitted,
+  trackCheckoutStarted,
+  trackCheckoutCompleted,
+} from "@elevateab/sdk";
+// Remove from cart
+await trackRemoveFromCart({
+  productId: product.id,
+  variantId: variant.id,
+  productPrice: 99.99,
+  productQuantity: 1,
+});
+// Cart view
+await trackCartView({
+  cartTotalPrice: 199.99,
+  cartTotalQuantity: 2,
+  currency: "USD",
+  cartItems: [
+    { productId: "123", variantId: "456", productPrice: 99.99, productQuantity: 1 },
+  ],
+});
+// Search
+await trackSearchSubmitted({ searchQuery: "blue shirt" });
+// Checkout started
+await trackCheckoutStarted({
+  cartTotalPrice: 199.99,
+  currency: "USD",
+  cartItems: [...],
+});
+// Checkout completed (order placed)
+await trackCheckoutCompleted({
+  orderId: "order_123",
+  cartTotalPrice: 199.99,
+  currency: "USD",
+  cartItems: [...],
+});
+```
 ---
 ## Using A/B Tests
@@ -236,29 +275,10 @@ if (isPreviewMode()) {
 ---
-## Geo-Targeting
-Get user's country for location-based tests:
-```tsx
-import { getUserCountry } from "@elevateab/sdk";
-const country = getUserCountry(); // "US", "CA", "GB", etc.
-```
-Country is detected from:
-1. `localization` cookie (set by Shopify)
-2. Cloudflare `CF-IPCountry` header
-3. Falls back to `null` if unavailable
----
 ## Cart Attribute Tagging
 Orders are attributed to A/B tests via cart attributes. This happens automatically when you provide `storefrontAccessToken` and `cartId`.
-### Automatic (Recommended)
 For Hydrogen, pass `storefrontAccessToken` to the provider:
 ```tsx
@@ -279,17 +299,7 @@ trackAddToCart({
 });
 ```
-### Manual (If Needed)
-```tsx
-import { updateCartAttributes } from "@elevateab/sdk";
-await updateCartAttributes(cartId, {
-  storefrontAccessToken: process.env.NEXT_PUBLIC_STOREFRONT_TOKEN,
-});
-```
-The Storefront Access Token is safe to use client-side. It's a public token designed for browser use.
+The Storefront Access Token is safe to use client-side - it's a public token designed for browser use.
 ---
@@ -300,53 +310,12 @@ The Storefront Access Token is safe to use client-side. It's a public token desi
 ```tsx
 import { extractShopifyId, isShopifyGid } from "@elevateab/sdk";
-// Extract numeric ID from GID
 extractShopifyId("gid://shopify/Product/123456"); // "123456"
-extractShopifyId("123456");                        // "123456"
-// Check if string is a GID
-isShopifyGid("gid://shopify/Product/123"); // true
-isShopifyGid("123456");                     // false
+isShopifyGid("gid://shopify/Product/123");        // true
 ```
 Note: Tracking functions automatically extract IDs, so you rarely need these directly.
-### Visitor & Session
-```tsx
-import { getVisitorId, getSessionId, getTestList } from "@elevateab/sdk";
-getVisitorId();  // Persistent visitor UUID
-getSessionId();  // Session UUID
-getTestList();   // { "test-1": "variant-a", "test-2": "control" }
-```
-### Device & Traffic Detection
-```tsx
-import { getDeviceType, getTrafficSource } from "@elevateab/sdk";
-getDeviceType();    // "desktop" | "tablet" | "mobile"
-getTrafficSource(); // "facebook" | "google" | "instagram" | "direct" | "other"
-```
----
-## Analytics Events
-The SDK tracks these events:
-| Event | Hydrogen | Next.js |
-|-------|----------|---------|
-| `page_viewed` | Automatic | Automatic (via provider) |
-| `product_viewed` | Automatic | `ProductViewTracker` or `trackProductView()` |
-| `product_added_to_cart` | Automatic | `trackAddToCart()` |
-| `product_removed_from_cart` | Automatic | `trackRemoveFromCart()` |
-| `cart_viewed` | Automatic | `trackCartView()` |
-| `search_submitted` | Automatic | `trackSearchSubmitted()` |
-| `checkout_started` | Automatic | `trackCheckoutStarted()` |
-| `checkout_completed` | Automatic | `trackCheckoutCompleted()` |
 ---
 ## API Reference
@@ -359,57 +328,22 @@ interface ElevateProviderProps {
   storefrontAccessToken?: string;     // For cart attribute tagging
   preventFlickering?: boolean;        // Enable anti-flicker (default: false)
   hasLocalizedPaths?: boolean;        // True if homepage is at /en-us/, /fr-ca/, etc.
-  workerUrl?: string;                 // Custom analytics endpoint
   children: React.ReactNode;
 }
 ```
-### Tracking Functions (Next.js)
+### Analytics Events Summary
-All tracking functions accept Shopify GIDs directly - they're converted automatically.
-```tsx
-// Page view (auto-tracked by ElevateNextProvider)
-trackPageView();
-// Product view
-trackProductView({
-  productId: "gid://shopify/Product/123",
-  productPrice: 99.99,
-  currency: "USD",
-});
-// Add to cart
-trackAddToCart({
-  productId: "123",
-  variantId: "456",
-  productPrice: 99.99,
-  productQuantity: 1,
-  currency: "USD",
-  cartId: "gid://shopify/Cart/abc",  // Optional: enables cart tagging
-});
-// Other events
-trackRemoveFromCart({ productId, variantId, ... });
-trackCartView({ cartTotalPrice, cartItems, ... });
-trackSearchSubmitted({ searchQuery });
-trackCheckoutStarted({ cartTotalPrice, cartItems, ... });
-trackCheckoutCompleted({ orderId, cartTotalPrice, cartItems, ... });
-```
----
-## Cookies & Storage
-**Cookies (1 year):**
-- `eabUserId` - Visitor ID
-- `ABTL` - Test assignments
-- `ABAU` - Unique test views
-- `eabUserPreview` - Preview mode flag
-**Session Storage:**
-- `eabSessionId` - Session ID
-- `ABAV` - Session test views
+| 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()` |
 ---