@elevateab/sdk 1.2.2 → 1.2.3
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.
- package/README.md +67 -129
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -51,15 +51,13 @@ Prevents content flash while tests load. Add this script to `<head>` before any
|
|
|
51
51
|
|
|
52
52
|
```tsx
|
|
53
53
|
// app/root.tsx
|
|
54
|
+
import { getFlickerPreventionScript } from "@elevateab/sdk";
|
|
55
|
+
|
|
54
56
|
export default function Root() {
|
|
55
57
|
return (
|
|
56
58
|
<html>
|
|
57
59
|
<head>
|
|
58
|
-
<script
|
|
59
|
-
dangerouslySetInnerHTML={{
|
|
60
|
-
__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)})();`,
|
|
61
|
-
}}
|
|
62
|
-
/>
|
|
60
|
+
<script dangerouslySetInnerHTML={{ __html: getFlickerPreventionScript() }} />
|
|
63
61
|
{/* other head elements */}
|
|
64
62
|
</head>
|
|
65
63
|
<body>{/* ... */}</body>
|
|
@@ -89,17 +87,14 @@ Next.js requires manual tracking since it doesn't have Shopify's analytics syste
|
|
|
89
87
|
```tsx
|
|
90
88
|
// app/layout.tsx
|
|
91
89
|
import { ElevateNextProvider } from "@elevateab/sdk/next";
|
|
90
|
+
import { getFlickerPreventionScript } from "@elevateab/sdk";
|
|
92
91
|
|
|
93
92
|
export default function RootLayout({ children }) {
|
|
94
93
|
return (
|
|
95
94
|
<html>
|
|
96
95
|
<head>
|
|
97
|
-
{/* Anti-flicker script (
|
|
98
|
-
<script
|
|
99
|
-
dangerouslySetInnerHTML={{
|
|
100
|
-
__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)})();`,
|
|
101
|
-
}}
|
|
102
|
-
/>
|
|
96
|
+
{/* Anti-flicker script (recommended) */}
|
|
97
|
+
<script dangerouslySetInnerHTML={{ __html: getFlickerPreventionScript() }} />
|
|
103
98
|
</head>
|
|
104
99
|
<body>
|
|
105
100
|
<ElevateNextProvider
|
|
@@ -159,6 +154,54 @@ async function handleAddToCart() {
|
|
|
159
154
|
}
|
|
160
155
|
```
|
|
161
156
|
|
|
157
|
+
### 4. Other Tracking Events
|
|
158
|
+
|
|
159
|
+
```tsx
|
|
160
|
+
import {
|
|
161
|
+
trackRemoveFromCart,
|
|
162
|
+
trackCartView,
|
|
163
|
+
trackSearchSubmitted,
|
|
164
|
+
trackCheckoutStarted,
|
|
165
|
+
trackCheckoutCompleted,
|
|
166
|
+
} from "@elevateab/sdk";
|
|
167
|
+
|
|
168
|
+
// Remove from cart
|
|
169
|
+
await trackRemoveFromCart({
|
|
170
|
+
productId: product.id,
|
|
171
|
+
variantId: variant.id,
|
|
172
|
+
productPrice: 99.99,
|
|
173
|
+
productQuantity: 1,
|
|
174
|
+
});
|
|
175
|
+
|
|
176
|
+
// Cart view
|
|
177
|
+
await trackCartView({
|
|
178
|
+
cartTotalPrice: 199.99,
|
|
179
|
+
cartTotalQuantity: 2,
|
|
180
|
+
currency: "USD",
|
|
181
|
+
cartItems: [
|
|
182
|
+
{ productId: "123", variantId: "456", productPrice: 99.99, productQuantity: 1 },
|
|
183
|
+
],
|
|
184
|
+
});
|
|
185
|
+
|
|
186
|
+
// Search
|
|
187
|
+
await trackSearchSubmitted({ searchQuery: "blue shirt" });
|
|
188
|
+
|
|
189
|
+
// Checkout started
|
|
190
|
+
await trackCheckoutStarted({
|
|
191
|
+
cartTotalPrice: 199.99,
|
|
192
|
+
currency: "USD",
|
|
193
|
+
cartItems: [...],
|
|
194
|
+
});
|
|
195
|
+
|
|
196
|
+
// Checkout completed (order placed)
|
|
197
|
+
await trackCheckoutCompleted({
|
|
198
|
+
orderId: "order_123",
|
|
199
|
+
cartTotalPrice: 199.99,
|
|
200
|
+
currency: "USD",
|
|
201
|
+
cartItems: [...],
|
|
202
|
+
});
|
|
203
|
+
```
|
|
204
|
+
|
|
162
205
|
---
|
|
163
206
|
|
|
164
207
|
## Using A/B Tests
|
|
@@ -236,29 +279,10 @@ if (isPreviewMode()) {
|
|
|
236
279
|
|
|
237
280
|
---
|
|
238
281
|
|
|
239
|
-
## Geo-Targeting
|
|
240
|
-
|
|
241
|
-
Get user's country for location-based tests:
|
|
242
|
-
|
|
243
|
-
```tsx
|
|
244
|
-
import { getUserCountry } from "@elevateab/sdk";
|
|
245
|
-
|
|
246
|
-
const country = getUserCountry(); // "US", "CA", "GB", etc.
|
|
247
|
-
```
|
|
248
|
-
|
|
249
|
-
Country is detected from:
|
|
250
|
-
1. `localization` cookie (set by Shopify)
|
|
251
|
-
2. Cloudflare `CF-IPCountry` header
|
|
252
|
-
3. Falls back to `null` if unavailable
|
|
253
|
-
|
|
254
|
-
---
|
|
255
|
-
|
|
256
282
|
## Cart Attribute Tagging
|
|
257
283
|
|
|
258
284
|
Orders are attributed to A/B tests via cart attributes. This happens automatically when you provide `storefrontAccessToken` and `cartId`.
|
|
259
285
|
|
|
260
|
-
### Automatic (Recommended)
|
|
261
|
-
|
|
262
286
|
For Hydrogen, pass `storefrontAccessToken` to the provider:
|
|
263
287
|
|
|
264
288
|
```tsx
|
|
@@ -279,17 +303,7 @@ trackAddToCart({
|
|
|
279
303
|
});
|
|
280
304
|
```
|
|
281
305
|
|
|
282
|
-
|
|
283
|
-
|
|
284
|
-
```tsx
|
|
285
|
-
import { updateCartAttributes } from "@elevateab/sdk";
|
|
286
|
-
|
|
287
|
-
await updateCartAttributes(cartId, {
|
|
288
|
-
storefrontAccessToken: process.env.NEXT_PUBLIC_STOREFRONT_TOKEN,
|
|
289
|
-
});
|
|
290
|
-
```
|
|
291
|
-
|
|
292
|
-
The Storefront Access Token is safe to use client-side. It's a public token designed for browser use.
|
|
306
|
+
The Storefront Access Token is safe to use client-side - it's a public token designed for browser use.
|
|
293
307
|
|
|
294
308
|
---
|
|
295
309
|
|
|
@@ -300,53 +314,12 @@ The Storefront Access Token is safe to use client-side. It's a public token desi
|
|
|
300
314
|
```tsx
|
|
301
315
|
import { extractShopifyId, isShopifyGid } from "@elevateab/sdk";
|
|
302
316
|
|
|
303
|
-
// Extract numeric ID from GID
|
|
304
317
|
extractShopifyId("gid://shopify/Product/123456"); // "123456"
|
|
305
|
-
|
|
306
|
-
|
|
307
|
-
// Check if string is a GID
|
|
308
|
-
isShopifyGid("gid://shopify/Product/123"); // true
|
|
309
|
-
isShopifyGid("123456"); // false
|
|
318
|
+
isShopifyGid("gid://shopify/Product/123"); // true
|
|
310
319
|
```
|
|
311
320
|
|
|
312
321
|
Note: Tracking functions automatically extract IDs, so you rarely need these directly.
|
|
313
322
|
|
|
314
|
-
### Visitor & Session
|
|
315
|
-
|
|
316
|
-
```tsx
|
|
317
|
-
import { getVisitorId, getSessionId, getTestList } from "@elevateab/sdk";
|
|
318
|
-
|
|
319
|
-
getVisitorId(); // Persistent visitor UUID
|
|
320
|
-
getSessionId(); // Session UUID
|
|
321
|
-
getTestList(); // { "test-1": "variant-a", "test-2": "control" }
|
|
322
|
-
```
|
|
323
|
-
|
|
324
|
-
### Device & Traffic Detection
|
|
325
|
-
|
|
326
|
-
```tsx
|
|
327
|
-
import { getDeviceType, getTrafficSource } from "@elevateab/sdk";
|
|
328
|
-
|
|
329
|
-
getDeviceType(); // "desktop" | "tablet" | "mobile"
|
|
330
|
-
getTrafficSource(); // "facebook" | "google" | "instagram" | "direct" | "other"
|
|
331
|
-
```
|
|
332
|
-
|
|
333
|
-
---
|
|
334
|
-
|
|
335
|
-
## Analytics Events
|
|
336
|
-
|
|
337
|
-
The SDK tracks these events:
|
|
338
|
-
|
|
339
|
-
| Event | Hydrogen | Next.js |
|
|
340
|
-
|-------|----------|---------|
|
|
341
|
-
| `page_viewed` | Automatic | Automatic (via provider) |
|
|
342
|
-
| `product_viewed` | Automatic | `ProductViewTracker` or `trackProductView()` |
|
|
343
|
-
| `product_added_to_cart` | Automatic | `trackAddToCart()` |
|
|
344
|
-
| `product_removed_from_cart` | Automatic | `trackRemoveFromCart()` |
|
|
345
|
-
| `cart_viewed` | Automatic | `trackCartView()` |
|
|
346
|
-
| `search_submitted` | Automatic | `trackSearchSubmitted()` |
|
|
347
|
-
| `checkout_started` | Automatic | `trackCheckoutStarted()` |
|
|
348
|
-
| `checkout_completed` | Automatic | `trackCheckoutCompleted()` |
|
|
349
|
-
|
|
350
323
|
---
|
|
351
324
|
|
|
352
325
|
## API Reference
|
|
@@ -359,57 +332,22 @@ interface ElevateProviderProps {
|
|
|
359
332
|
storefrontAccessToken?: string; // For cart attribute tagging
|
|
360
333
|
preventFlickering?: boolean; // Enable anti-flicker (default: false)
|
|
361
334
|
hasLocalizedPaths?: boolean; // True if homepage is at /en-us/, /fr-ca/, etc.
|
|
362
|
-
workerUrl?: string; // Custom analytics endpoint
|
|
363
335
|
children: React.ReactNode;
|
|
364
336
|
}
|
|
365
337
|
```
|
|
366
338
|
|
|
367
|
-
###
|
|
368
|
-
|
|
369
|
-
All tracking functions accept Shopify GIDs directly - they're converted automatically.
|
|
339
|
+
### Analytics Events Summary
|
|
370
340
|
|
|
371
|
-
|
|
372
|
-
|
|
373
|
-
|
|
374
|
-
|
|
375
|
-
|
|
376
|
-
|
|
377
|
-
|
|
378
|
-
|
|
379
|
-
|
|
380
|
-
|
|
381
|
-
|
|
382
|
-
// Add to cart
|
|
383
|
-
trackAddToCart({
|
|
384
|
-
productId: "123",
|
|
385
|
-
variantId: "456",
|
|
386
|
-
productPrice: 99.99,
|
|
387
|
-
productQuantity: 1,
|
|
388
|
-
currency: "USD",
|
|
389
|
-
cartId: "gid://shopify/Cart/abc", // Optional: enables cart tagging
|
|
390
|
-
});
|
|
391
|
-
|
|
392
|
-
// Other events
|
|
393
|
-
trackRemoveFromCart({ productId, variantId, ... });
|
|
394
|
-
trackCartView({ cartTotalPrice, cartItems, ... });
|
|
395
|
-
trackSearchSubmitted({ searchQuery });
|
|
396
|
-
trackCheckoutStarted({ cartTotalPrice, cartItems, ... });
|
|
397
|
-
trackCheckoutCompleted({ orderId, cartTotalPrice, cartItems, ... });
|
|
398
|
-
```
|
|
399
|
-
|
|
400
|
-
---
|
|
401
|
-
|
|
402
|
-
## Cookies & Storage
|
|
403
|
-
|
|
404
|
-
**Cookies (1 year):**
|
|
405
|
-
- `eabUserId` - Visitor ID
|
|
406
|
-
- `ABTL` - Test assignments
|
|
407
|
-
- `ABAU` - Unique test views
|
|
408
|
-
- `eabUserPreview` - Preview mode flag
|
|
409
|
-
|
|
410
|
-
**Session Storage:**
|
|
411
|
-
- `eabSessionId` - Session ID
|
|
412
|
-
- `ABAV` - Session test views
|
|
341
|
+
| Event | Hydrogen | Next.js |
|
|
342
|
+
|-------|----------|---------|
|
|
343
|
+
| Page view | Automatic | Automatic |
|
|
344
|
+
| Product view | Automatic | `ProductViewTracker` |
|
|
345
|
+
| Add to cart | Automatic | `trackAddToCart()` |
|
|
346
|
+
| Remove from cart | Automatic | `trackRemoveFromCart()` |
|
|
347
|
+
| Cart view | Automatic | `trackCartView()` |
|
|
348
|
+
| Search | Automatic | `trackSearchSubmitted()` |
|
|
349
|
+
| Checkout started | Automatic | `trackCheckoutStarted()` |
|
|
350
|
+
| Checkout completed | Automatic | `trackCheckoutCompleted()` |
|
|
413
351
|
|
|
414
352
|
---
|
|
415
353
|
|