@elevateab/sdk 1.2.0 → 1.2.2
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 +365 -101
- package/dist/ElevateAnalytics-Cp5iR7dJ.d.cts +48 -0
- package/dist/ElevateAnalytics-Cp5iR7dJ.d.ts +48 -0
- package/dist/cartAttributes-4XA3JSEP.js +2 -0
- package/dist/cartAttributes-4XA3JSEP.js.map +1 -0
- package/dist/cartAttributes-NW2TWOYC.js +3 -0
- package/dist/cartAttributes-NW2TWOYC.js.map +1 -0
- package/dist/chunk-4D5I75NE.js +19 -0
- package/dist/chunk-4D5I75NE.js.map +1 -0
- package/dist/chunk-VUGOZ5MR.js +18 -0
- package/dist/chunk-VUGOZ5MR.js.map +1 -0
- package/dist/chunk-XXNIBCJ6.js +2 -0
- package/dist/chunk-XXNIBCJ6.js.map +1 -0
- package/dist/hydrogen.cjs +18 -0
- package/dist/hydrogen.cjs.map +1 -0
- package/dist/hydrogen.d.cts +48 -0
- package/dist/hydrogen.d.ts +48 -0
- package/dist/hydrogen.js +2 -0
- package/dist/hydrogen.js.map +1 -0
- package/dist/index.cjs +40 -1
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +1433 -33
- package/dist/index.d.ts +1433 -33
- package/dist/index.js +24 -1
- package/dist/index.js.map +1 -1
- package/dist/next.cjs +42 -0
- package/dist/next.cjs.map +1 -0
- package/dist/next.d.cts +734 -0
- package/dist/next.d.ts +734 -0
- package/dist/next.js +26 -0
- package/dist/next.js.map +1 -0
- package/package.json +31 -4
package/dist/next.d.ts
ADDED
|
@@ -0,0 +1,734 @@
|
|
|
1
|
+
import React, { ReactNode } from 'react';
|
|
2
|
+
|
|
3
|
+
interface ElevateNextProviderProps {
|
|
4
|
+
/**
|
|
5
|
+
* Shopify store ID (e.g., "your-store.myshopify.com")
|
|
6
|
+
* @required
|
|
7
|
+
*/
|
|
8
|
+
storeId: string;
|
|
9
|
+
/**
|
|
10
|
+
* Storefront Access Token for cart attribute updates (order attribution)
|
|
11
|
+
* Optional but recommended for full functionality.
|
|
12
|
+
*/
|
|
13
|
+
storefrontAccessToken?: string;
|
|
14
|
+
/**
|
|
15
|
+
* Enable flicker prevention (hides content until variant is determined)
|
|
16
|
+
* @default false
|
|
17
|
+
*/
|
|
18
|
+
preventFlickering?: boolean;
|
|
19
|
+
/**
|
|
20
|
+
* Maximum time to wait before showing content (failsafe)
|
|
21
|
+
* @default 3000
|
|
22
|
+
*/
|
|
23
|
+
flickerTimeout?: number;
|
|
24
|
+
/**
|
|
25
|
+
* Default currency for analytics events
|
|
26
|
+
*/
|
|
27
|
+
currency?: string;
|
|
28
|
+
/**
|
|
29
|
+
* Children to render
|
|
30
|
+
*/
|
|
31
|
+
children: ReactNode;
|
|
32
|
+
}
|
|
33
|
+
/**
|
|
34
|
+
* ElevateNextProvider - Next.js App Router compatible provider
|
|
35
|
+
*
|
|
36
|
+
* This is a "use client" wrapper that includes:
|
|
37
|
+
* - ElevateProvider (A/B test config & context)
|
|
38
|
+
* - Automatic page view tracking on route changes
|
|
39
|
+
* - Auto-initialization of analytics (no need to call initAnalytics)
|
|
40
|
+
*
|
|
41
|
+
* @example Basic usage in app/layout.tsx
|
|
42
|
+
* ```tsx
|
|
43
|
+
* import { ElevateNextProvider } from "@elevateab/sdk/next";
|
|
44
|
+
*
|
|
45
|
+
* export default function RootLayout({ children }) {
|
|
46
|
+
* return (
|
|
47
|
+
* <html>
|
|
48
|
+
* <body>
|
|
49
|
+
* <ElevateNextProvider
|
|
50
|
+
* storeId="your-store.myshopify.com"
|
|
51
|
+
* storefrontAccessToken={process.env.NEXT_PUBLIC_STOREFRONT_TOKEN}
|
|
52
|
+
* >
|
|
53
|
+
* {children}
|
|
54
|
+
* </ElevateNextProvider>
|
|
55
|
+
* </body>
|
|
56
|
+
* </html>
|
|
57
|
+
* );
|
|
58
|
+
* }
|
|
59
|
+
* ```
|
|
60
|
+
*
|
|
61
|
+
* @example With anti-flicker
|
|
62
|
+
* ```tsx
|
|
63
|
+
* <ElevateNextProvider
|
|
64
|
+
* storeId="your-store.myshopify.com"
|
|
65
|
+
* preventFlickering={true}
|
|
66
|
+
* flickerTimeout={2500}
|
|
67
|
+
* >
|
|
68
|
+
* {children}
|
|
69
|
+
* </ElevateNextProvider>
|
|
70
|
+
* ```
|
|
71
|
+
*/
|
|
72
|
+
declare function ElevateNextProvider({ storeId, storefrontAccessToken, preventFlickering, flickerTimeout, currency, children, }: ElevateNextProviderProps): React.JSX.Element;
|
|
73
|
+
|
|
74
|
+
interface ProductViewTrackerProps {
|
|
75
|
+
/**
|
|
76
|
+
* Shopify Product ID (GID or numeric - auto-extracted)
|
|
77
|
+
* @example "gid://shopify/Product/123456789" or "123456789"
|
|
78
|
+
*/
|
|
79
|
+
productId: string;
|
|
80
|
+
/**
|
|
81
|
+
* Product vendor/brand name
|
|
82
|
+
*/
|
|
83
|
+
productVendor?: string;
|
|
84
|
+
/**
|
|
85
|
+
* Product price (numeric)
|
|
86
|
+
*/
|
|
87
|
+
productPrice?: number;
|
|
88
|
+
/**
|
|
89
|
+
* Product SKU
|
|
90
|
+
*/
|
|
91
|
+
productSku?: string;
|
|
92
|
+
/**
|
|
93
|
+
* Currency code (e.g., "USD")
|
|
94
|
+
*/
|
|
95
|
+
currency?: string;
|
|
96
|
+
}
|
|
97
|
+
/**
|
|
98
|
+
* ProductViewTracker - Tracks product view events on mount
|
|
99
|
+
*
|
|
100
|
+
* Add this component to your product pages to automatically track product views.
|
|
101
|
+
* Shopify GIDs are automatically converted to numeric IDs.
|
|
102
|
+
*
|
|
103
|
+
* @example In your product page
|
|
104
|
+
* ```tsx
|
|
105
|
+
* import { ProductViewTracker } from "@elevateab/sdk/next";
|
|
106
|
+
*
|
|
107
|
+
* export default function ProductPage({ product }) {
|
|
108
|
+
* return (
|
|
109
|
+
* <>
|
|
110
|
+
* <ProductViewTracker
|
|
111
|
+
* productId={product.id}
|
|
112
|
+
* productVendor={product.vendor}
|
|
113
|
+
* productPrice={parseFloat(product.priceRange.minVariantPrice.amount)}
|
|
114
|
+
* currency={product.priceRange.minVariantPrice.currencyCode}
|
|
115
|
+
* />
|
|
116
|
+
* <div>Product content goes here</div>
|
|
117
|
+
* </>
|
|
118
|
+
* );
|
|
119
|
+
* }
|
|
120
|
+
* ```
|
|
121
|
+
*/
|
|
122
|
+
declare function ProductViewTracker({ productId, productVendor, productPrice, productSku, currency, }: ProductViewTrackerProps): null;
|
|
123
|
+
|
|
124
|
+
interface Test {
|
|
125
|
+
testId: string;
|
|
126
|
+
name: string;
|
|
127
|
+
enabled: boolean;
|
|
128
|
+
type: string;
|
|
129
|
+
variations: Variation[];
|
|
130
|
+
}
|
|
131
|
+
interface Variation {
|
|
132
|
+
id: string;
|
|
133
|
+
name: string;
|
|
134
|
+
weight: number;
|
|
135
|
+
isControl?: boolean;
|
|
136
|
+
productId?: string;
|
|
137
|
+
handle?: string;
|
|
138
|
+
price?: string;
|
|
139
|
+
/** Convenience flag: true if this is variation A (index 0) */
|
|
140
|
+
isA?: boolean;
|
|
141
|
+
/** Convenience flag: true if this is variation B (index 1) */
|
|
142
|
+
isB?: boolean;
|
|
143
|
+
/** Convenience flag: true if this is variation C (index 2) */
|
|
144
|
+
isC?: boolean;
|
|
145
|
+
/** Convenience flag: true if this is variation D (index 3) */
|
|
146
|
+
isD?: boolean;
|
|
147
|
+
}
|
|
148
|
+
interface ElevateConfig {
|
|
149
|
+
tests: Test[];
|
|
150
|
+
selectors?: unknown;
|
|
151
|
+
}
|
|
152
|
+
interface ElevateContextValue {
|
|
153
|
+
config: ElevateConfig | null;
|
|
154
|
+
/** Store ID for tracking */
|
|
155
|
+
storeId: string;
|
|
156
|
+
/** Storefront access token for cart attribute updates (optional) */
|
|
157
|
+
storefrontAccessToken?: string;
|
|
158
|
+
/** Whether preview mode is active */
|
|
159
|
+
isPreviewMode?: boolean;
|
|
160
|
+
/** Current preview test ID if in preview mode */
|
|
161
|
+
previewTestId?: string | null;
|
|
162
|
+
/** User's detected country code */
|
|
163
|
+
countryCode?: string | null;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Product info for cart items
|
|
167
|
+
*/
|
|
168
|
+
interface CartItemInput {
|
|
169
|
+
/** Shopify Product ID (numeric, not GID) */
|
|
170
|
+
productId: string;
|
|
171
|
+
/** Shopify Product Variant ID (numeric, not GID) */
|
|
172
|
+
variantId: string;
|
|
173
|
+
/** Product vendor/brand name */
|
|
174
|
+
productVendor?: string;
|
|
175
|
+
/** Item price (single unit) */
|
|
176
|
+
productPrice?: number;
|
|
177
|
+
/** Quantity in cart */
|
|
178
|
+
productQuantity?: number;
|
|
179
|
+
/** Product SKU */
|
|
180
|
+
productSku?: string;
|
|
181
|
+
/** Discount amount on this item */
|
|
182
|
+
totalDiscount?: number;
|
|
183
|
+
}
|
|
184
|
+
/**
|
|
185
|
+
* Note attribute for checkout
|
|
186
|
+
*/
|
|
187
|
+
interface NoteAttribute {
|
|
188
|
+
key: string;
|
|
189
|
+
value: string;
|
|
190
|
+
}
|
|
191
|
+
/**
|
|
192
|
+
* Base configuration for all tracking events.
|
|
193
|
+
*
|
|
194
|
+
* Note: If you call `initAnalytics()` first (or use ElevateProvider which does this automatically),
|
|
195
|
+
* you don't need to pass storeId to individual tracking calls.
|
|
196
|
+
*/
|
|
197
|
+
interface BaseTrackingConfig {
|
|
198
|
+
/**
|
|
199
|
+
* Shopify store ID (e.g., "mystore.myshopify.com")
|
|
200
|
+
* Optional if initAnalytics() was called or ElevateProvider is used.
|
|
201
|
+
*/
|
|
202
|
+
storeId?: string;
|
|
203
|
+
/**
|
|
204
|
+
* Enable localized path detection (e.g., /en-us/, /fr-ca/)
|
|
205
|
+
* @default false
|
|
206
|
+
*/
|
|
207
|
+
hasLocalizedPaths?: boolean;
|
|
208
|
+
/**
|
|
209
|
+
* Cart/shop currency code (e.g., "USD", "EUR")
|
|
210
|
+
* If not provided, will try to detect from Shopify or omit.
|
|
211
|
+
*/
|
|
212
|
+
currency?: string;
|
|
213
|
+
/**
|
|
214
|
+
* Custom CloudFlare Worker URL (optional)
|
|
215
|
+
*/
|
|
216
|
+
workerUrl?: string;
|
|
217
|
+
}
|
|
218
|
+
/**
|
|
219
|
+
* Parameters for tracking a page view
|
|
220
|
+
* @example After initAnalytics() or inside ElevateProvider (recommended)
|
|
221
|
+
* ```ts
|
|
222
|
+
* await trackPageView(); // No params needed!
|
|
223
|
+
* await trackPageView({ currency: "USD" }); // Optional currency
|
|
224
|
+
* ```
|
|
225
|
+
* @example Standalone (without init)
|
|
226
|
+
* ```ts
|
|
227
|
+
* await trackPageView({ storeId: "mystore.myshopify.com" });
|
|
228
|
+
* ```
|
|
229
|
+
*/
|
|
230
|
+
interface TrackPageViewParams extends BaseTrackingConfig {
|
|
231
|
+
}
|
|
232
|
+
/**
|
|
233
|
+
* Parameters for tracking a product view
|
|
234
|
+
* @example After initAnalytics() or inside ElevateProvider (recommended)
|
|
235
|
+
* ```ts
|
|
236
|
+
* await trackProductView({
|
|
237
|
+
* productId: "123456789",
|
|
238
|
+
* productPrice: 99.99,
|
|
239
|
+
* });
|
|
240
|
+
* ```
|
|
241
|
+
* @example With all optional fields
|
|
242
|
+
* ```ts
|
|
243
|
+
* await trackProductView({
|
|
244
|
+
* productId: "123456789",
|
|
245
|
+
* productVendor: "Nike",
|
|
246
|
+
* productPrice: 99.99,
|
|
247
|
+
* productSku: "NIKE-001",
|
|
248
|
+
* currency: "USD",
|
|
249
|
+
* });
|
|
250
|
+
* ```
|
|
251
|
+
*/
|
|
252
|
+
interface TrackProductViewParams extends BaseTrackingConfig {
|
|
253
|
+
/**
|
|
254
|
+
* Shopify Product ID (numeric string, not GID)
|
|
255
|
+
* @required
|
|
256
|
+
*/
|
|
257
|
+
productId: string;
|
|
258
|
+
/** Product vendor/brand name */
|
|
259
|
+
productVendor?: string;
|
|
260
|
+
/** Product price */
|
|
261
|
+
productPrice?: number;
|
|
262
|
+
/** Product SKU */
|
|
263
|
+
productSku?: string;
|
|
264
|
+
}
|
|
265
|
+
/**
|
|
266
|
+
* Parameters for tracking add to cart
|
|
267
|
+
* @example After initAnalytics() or inside ElevateProvider (recommended)
|
|
268
|
+
* ```ts
|
|
269
|
+
* await trackAddToCart({
|
|
270
|
+
* productId: "123456789",
|
|
271
|
+
* variantId: "987654321",
|
|
272
|
+
* productPrice: 99.99,
|
|
273
|
+
* productQuantity: 1,
|
|
274
|
+
* });
|
|
275
|
+
* ```
|
|
276
|
+
* @example With cart ID for automatic attribute updates
|
|
277
|
+
* ```ts
|
|
278
|
+
* await trackAddToCart({
|
|
279
|
+
* productId: "123456789",
|
|
280
|
+
* variantId: "987654321",
|
|
281
|
+
* productPrice: 99.99,
|
|
282
|
+
* productQuantity: 1,
|
|
283
|
+
* cartId: "gid://shopify/Cart/abc123",
|
|
284
|
+
* });
|
|
285
|
+
* ```
|
|
286
|
+
*/
|
|
287
|
+
interface TrackAddToCartParams extends BaseTrackingConfig {
|
|
288
|
+
/**
|
|
289
|
+
* Shopify Product ID (numeric string, not GID)
|
|
290
|
+
* @required
|
|
291
|
+
*/
|
|
292
|
+
productId: string;
|
|
293
|
+
/**
|
|
294
|
+
* Shopify Product Variant ID (numeric string, not GID)
|
|
295
|
+
* @required
|
|
296
|
+
*/
|
|
297
|
+
variantId: string;
|
|
298
|
+
/** Product vendor/brand name */
|
|
299
|
+
productVendor?: string;
|
|
300
|
+
/** Product price (single unit) */
|
|
301
|
+
productPrice?: number;
|
|
302
|
+
/** Quantity being added */
|
|
303
|
+
productQuantity?: number;
|
|
304
|
+
/** Product SKU */
|
|
305
|
+
productSku?: string;
|
|
306
|
+
/**
|
|
307
|
+
* Cart ID (GID or token) - if provided, cart attributes will be updated automatically
|
|
308
|
+
* @example "gid://shopify/Cart/abc123" or "abc123"
|
|
309
|
+
*/
|
|
310
|
+
cartId?: string;
|
|
311
|
+
/**
|
|
312
|
+
* Storefront Access Token - REQUIRED if cartId is provided
|
|
313
|
+
* ✅ Safe to use client-side - this is a public token
|
|
314
|
+
*/
|
|
315
|
+
storefrontAccessToken?: string;
|
|
316
|
+
}
|
|
317
|
+
/**
|
|
318
|
+
* Parameters for tracking remove from cart
|
|
319
|
+
* @example
|
|
320
|
+
* ```ts
|
|
321
|
+
* await trackRemoveFromCart({
|
|
322
|
+
* productId: "123456789",
|
|
323
|
+
* variantId: "987654321",
|
|
324
|
+
* productQuantity: 1,
|
|
325
|
+
* });
|
|
326
|
+
* ```
|
|
327
|
+
*/
|
|
328
|
+
interface TrackRemoveFromCartParams extends BaseTrackingConfig {
|
|
329
|
+
/**
|
|
330
|
+
* Shopify Product ID (numeric string, not GID)
|
|
331
|
+
* @required
|
|
332
|
+
*/
|
|
333
|
+
productId: string;
|
|
334
|
+
/**
|
|
335
|
+
* Shopify Product Variant ID (numeric string, not GID)
|
|
336
|
+
* @required
|
|
337
|
+
*/
|
|
338
|
+
variantId: string;
|
|
339
|
+
/** Product vendor/brand name */
|
|
340
|
+
productVendor?: string;
|
|
341
|
+
/** Product price (single unit) */
|
|
342
|
+
productPrice?: number;
|
|
343
|
+
/** Quantity being removed */
|
|
344
|
+
productQuantity?: number;
|
|
345
|
+
/** Product SKU */
|
|
346
|
+
productSku?: string;
|
|
347
|
+
}
|
|
348
|
+
/**
|
|
349
|
+
* Parameters for tracking cart view
|
|
350
|
+
* @example
|
|
351
|
+
* ```ts
|
|
352
|
+
* await trackCartView({
|
|
353
|
+
* cartTotalPrice: 199.98,
|
|
354
|
+
* cartTotalQuantity: 2,
|
|
355
|
+
* cartItems: [{ productId: "123", variantId: "456", productPrice: 99.99 }],
|
|
356
|
+
* });
|
|
357
|
+
* ```
|
|
358
|
+
*/
|
|
359
|
+
interface TrackCartViewParams extends BaseTrackingConfig {
|
|
360
|
+
/** Total cart price */
|
|
361
|
+
cartTotalPrice?: number;
|
|
362
|
+
/** Total items in cart */
|
|
363
|
+
cartTotalQuantity?: number;
|
|
364
|
+
/** Cart line items */
|
|
365
|
+
cartItems?: CartItemInput[];
|
|
366
|
+
}
|
|
367
|
+
/**
|
|
368
|
+
* Parameters for tracking search submission
|
|
369
|
+
* @example
|
|
370
|
+
* ```ts
|
|
371
|
+
* await trackSearchSubmitted({ searchQuery: "running shoes" });
|
|
372
|
+
* ```
|
|
373
|
+
*/
|
|
374
|
+
interface TrackSearchSubmittedParams extends BaseTrackingConfig {
|
|
375
|
+
/**
|
|
376
|
+
* Search query string
|
|
377
|
+
* @required
|
|
378
|
+
*/
|
|
379
|
+
searchQuery: string;
|
|
380
|
+
}
|
|
381
|
+
/**
|
|
382
|
+
* Parameters for tracking checkout started
|
|
383
|
+
* @example
|
|
384
|
+
* ```ts
|
|
385
|
+
* await trackCheckoutStarted({
|
|
386
|
+
* cartTotalPrice: 109.98,
|
|
387
|
+
* cartItems: [...],
|
|
388
|
+
* });
|
|
389
|
+
* ```
|
|
390
|
+
*/
|
|
391
|
+
interface TrackCheckoutStartedParams extends BaseTrackingConfig {
|
|
392
|
+
/** Total checkout price (including shipping, tax) */
|
|
393
|
+
cartTotalPrice?: number;
|
|
394
|
+
/** Subtotal (before shipping, tax) */
|
|
395
|
+
cartSubtotalPrice?: number;
|
|
396
|
+
/** Shipping cost */
|
|
397
|
+
cartShippingPrice?: number;
|
|
398
|
+
/** Tax amount */
|
|
399
|
+
cartTaxAmount?: number;
|
|
400
|
+
/** Total discount applied */
|
|
401
|
+
cartDiscountAmount?: number;
|
|
402
|
+
/** Shopify Customer ID */
|
|
403
|
+
customerId?: string;
|
|
404
|
+
/** Checkout line items */
|
|
405
|
+
cartItems?: CartItemInput[];
|
|
406
|
+
}
|
|
407
|
+
/**
|
|
408
|
+
* Parameters for tracking checkout completed (order placed)
|
|
409
|
+
* NOTE: This sends to the orders worker endpoint
|
|
410
|
+
* @example
|
|
411
|
+
* ```ts
|
|
412
|
+
* await trackCheckoutCompleted({
|
|
413
|
+
* orderId: "order_123456",
|
|
414
|
+
* cartTotalPrice: 109.98,
|
|
415
|
+
* cartItems: [...],
|
|
416
|
+
* });
|
|
417
|
+
* ```
|
|
418
|
+
*/
|
|
419
|
+
interface TrackCheckoutCompletedParams extends Omit<BaseTrackingConfig, "workerUrl"> {
|
|
420
|
+
/**
|
|
421
|
+
* Shopify Order ID
|
|
422
|
+
* @required
|
|
423
|
+
*/
|
|
424
|
+
orderId: string;
|
|
425
|
+
/** Total checkout price (including shipping, tax) */
|
|
426
|
+
cartTotalPrice?: number;
|
|
427
|
+
/** Subtotal (before shipping, tax) */
|
|
428
|
+
cartSubtotalPrice?: number;
|
|
429
|
+
/** Shipping cost */
|
|
430
|
+
cartShippingPrice?: number;
|
|
431
|
+
/** Tax amount */
|
|
432
|
+
cartTaxAmount?: number;
|
|
433
|
+
/** Total discount applied */
|
|
434
|
+
cartDiscountAmount?: number;
|
|
435
|
+
/** Shopify Customer ID */
|
|
436
|
+
customerId?: string;
|
|
437
|
+
/** Whether this is customer's first order */
|
|
438
|
+
isFirstOrder?: boolean;
|
|
439
|
+
/** Order note attributes (for A/B test attribution) */
|
|
440
|
+
noteAttributes?: NoteAttribute[];
|
|
441
|
+
/** Checkout line items */
|
|
442
|
+
cartItems?: CartItemInput[];
|
|
443
|
+
/**
|
|
444
|
+
* Custom orders worker URL (optional)
|
|
445
|
+
* Note: Uses different endpoint than other events
|
|
446
|
+
*/
|
|
447
|
+
ordersWorkerUrl?: string;
|
|
448
|
+
}
|
|
449
|
+
|
|
450
|
+
/**
|
|
451
|
+
* Preview Mode Utilities
|
|
452
|
+
*
|
|
453
|
+
* Enables QA/preview functionality for A/B tests via URL parameters.
|
|
454
|
+
*
|
|
455
|
+
* URL Format:
|
|
456
|
+
* ?eabUserPreview=true&abtid=<test_id>&eab_tests=<shortid>_<variation>_<seen>
|
|
457
|
+
*
|
|
458
|
+
* Example:
|
|
459
|
+
* https://store.com/?eabUserPreview=true&abtid=b6e2ecb8-e35a-450e-ae49-bdc560cf0fd7&eab_tests=f0fd7_29913_1
|
|
460
|
+
*/
|
|
461
|
+
/**
|
|
462
|
+
* Preview mode state
|
|
463
|
+
*/
|
|
464
|
+
interface PreviewState {
|
|
465
|
+
/** Whether preview mode is active */
|
|
466
|
+
isPreview: boolean;
|
|
467
|
+
/** The test ID being previewed (full UUID or short ID) */
|
|
468
|
+
previewTestId: string | null;
|
|
469
|
+
/** Forced test assignments from URL params */
|
|
470
|
+
forcedAssignments: Record<string, string>;
|
|
471
|
+
/** Tests that have been marked as "seen" in preview */
|
|
472
|
+
previewedViews: Record<string, boolean>;
|
|
473
|
+
}
|
|
474
|
+
/**
|
|
475
|
+
* Get preview state from URL parameters and cookies
|
|
476
|
+
*/
|
|
477
|
+
declare function getPreviewState(): PreviewState;
|
|
478
|
+
/**
|
|
479
|
+
* Clear preview mode
|
|
480
|
+
*/
|
|
481
|
+
declare function clearPreviewMode(): void;
|
|
482
|
+
/**
|
|
483
|
+
* Check if current session is in preview mode
|
|
484
|
+
*/
|
|
485
|
+
declare function isInPreviewMode(): boolean;
|
|
486
|
+
|
|
487
|
+
/**
|
|
488
|
+
* Get the user's country code from various sources
|
|
489
|
+
* Priority: URL param > Shopify localization > our cookie > localStorage
|
|
490
|
+
*/
|
|
491
|
+
declare function getCountryCode(): string | null;
|
|
492
|
+
/**
|
|
493
|
+
* Check if user matches geo-targeting rules
|
|
494
|
+
* Returns true if user should be included in the test
|
|
495
|
+
*/
|
|
496
|
+
declare function matchesGeoTargeting(rules: {
|
|
497
|
+
includeCountries?: string[];
|
|
498
|
+
excludeCountries?: string[];
|
|
499
|
+
}): boolean;
|
|
500
|
+
|
|
501
|
+
/**
|
|
502
|
+
* Script snippet for inline injection in <head>
|
|
503
|
+
* Use this when you need synchronous flicker prevention before React hydrates
|
|
504
|
+
*
|
|
505
|
+
* @example
|
|
506
|
+
* ```tsx
|
|
507
|
+
* // In your _document.tsx or layout.tsx
|
|
508
|
+
* <script dangerouslySetInnerHTML={{ __html: getFlickerPreventionScript() }} />
|
|
509
|
+
* ```
|
|
510
|
+
*/
|
|
511
|
+
declare function getFlickerPreventionScript(timeout?: number): string;
|
|
512
|
+
|
|
513
|
+
/**
|
|
514
|
+
* Shopify-specific utilities
|
|
515
|
+
*/
|
|
516
|
+
/**
|
|
517
|
+
* Extract numeric ID from a Shopify Global ID (GID).
|
|
518
|
+
*
|
|
519
|
+
* Shopify uses GIDs like "gid://shopify/Product/123456789" or "gid://shopify/ProductVariant/987654321".
|
|
520
|
+
* This utility extracts the numeric ID portion.
|
|
521
|
+
*
|
|
522
|
+
* @param gid - Shopify Global ID or numeric ID string
|
|
523
|
+
* @returns The numeric ID portion (e.g., "123456789")
|
|
524
|
+
*
|
|
525
|
+
* @example
|
|
526
|
+
* ```ts
|
|
527
|
+
* extractShopifyId("gid://shopify/Product/123456789"); // "123456789"
|
|
528
|
+
* extractShopifyId("gid://shopify/ProductVariant/987654321"); // "987654321"
|
|
529
|
+
* extractShopifyId("gid://shopify/Cart/abc123"); // "abc123"
|
|
530
|
+
* extractShopifyId("123456789"); // "123456789" (already numeric)
|
|
531
|
+
* ```
|
|
532
|
+
*/
|
|
533
|
+
declare function extractShopifyId(gid: string | null | undefined): string;
|
|
534
|
+
/**
|
|
535
|
+
* Extract the resource type from a Shopify Global ID.
|
|
536
|
+
*
|
|
537
|
+
* @param gid - Shopify Global ID
|
|
538
|
+
* @returns The resource type (e.g., "Product", "ProductVariant", "Cart")
|
|
539
|
+
*
|
|
540
|
+
* @example
|
|
541
|
+
* ```ts
|
|
542
|
+
* extractShopifyType("gid://shopify/Product/123"); // "Product"
|
|
543
|
+
* extractShopifyType("gid://shopify/ProductVariant/456"); // "ProductVariant"
|
|
544
|
+
* extractShopifyType("123456789"); // null (not a GID)
|
|
545
|
+
* ```
|
|
546
|
+
*/
|
|
547
|
+
declare function extractShopifyType(gid: string | null | undefined): string | null;
|
|
548
|
+
/**
|
|
549
|
+
* Check if a string is a Shopify Global ID.
|
|
550
|
+
*
|
|
551
|
+
* @param value - String to check
|
|
552
|
+
* @returns True if it's a GID
|
|
553
|
+
*
|
|
554
|
+
* @example
|
|
555
|
+
* ```ts
|
|
556
|
+
* isShopifyGid("gid://shopify/Product/123"); // true
|
|
557
|
+
* isShopifyGid("123456789"); // false
|
|
558
|
+
* ```
|
|
559
|
+
*/
|
|
560
|
+
declare function isShopifyGid(value: string | null | undefined): boolean;
|
|
561
|
+
|
|
562
|
+
/**
|
|
563
|
+
* Manual tracking functions for non-Hydrogen frameworks (Next.js, etc.)
|
|
564
|
+
*
|
|
565
|
+
* Initialize once with initAnalytics(), then call tracking functions without params:
|
|
566
|
+
*
|
|
567
|
+
* @example
|
|
568
|
+
* ```tsx
|
|
569
|
+
* // In your layout/provider (once)
|
|
570
|
+
* initAnalytics({
|
|
571
|
+
* storeId: 'your-store.myshopify.com',
|
|
572
|
+
* storefrontAccessToken: 'your-token',
|
|
573
|
+
* });
|
|
574
|
+
*
|
|
575
|
+
* // Then anywhere in your app (no params needed)
|
|
576
|
+
* trackPageView();
|
|
577
|
+
* trackAddToCart({ cartId, productId, ... });
|
|
578
|
+
* ```
|
|
579
|
+
*/
|
|
580
|
+
|
|
581
|
+
/**
|
|
582
|
+
* Track page view event
|
|
583
|
+
* Call this on route changes or in useEffect
|
|
584
|
+
*
|
|
585
|
+
* @example After initAnalytics()
|
|
586
|
+
* ```ts
|
|
587
|
+
* await trackPageView(); // No params needed!
|
|
588
|
+
* ```
|
|
589
|
+
*
|
|
590
|
+
* @example Without init (pass params)
|
|
591
|
+
* ```ts
|
|
592
|
+
* await trackPageView({ storeId: "mystore.myshopify.com" });
|
|
593
|
+
* ```
|
|
594
|
+
*/
|
|
595
|
+
declare function trackPageView(params?: Partial<TrackPageViewParams>): Promise<void>;
|
|
596
|
+
/**
|
|
597
|
+
* Track product view event
|
|
598
|
+
* Call this on product pages
|
|
599
|
+
*
|
|
600
|
+
* @example After initAnalytics()
|
|
601
|
+
* ```ts
|
|
602
|
+
* await trackProductView({ productId: "123", productPrice: 99.99 });
|
|
603
|
+
* ```
|
|
604
|
+
*/
|
|
605
|
+
declare function trackProductView(params: Omit<TrackProductViewParams, "storeId"> & {
|
|
606
|
+
storeId?: string;
|
|
607
|
+
}): Promise<void>;
|
|
608
|
+
/**
|
|
609
|
+
* Track add to cart event
|
|
610
|
+
* Call this when user clicks "Add to Cart"
|
|
611
|
+
*
|
|
612
|
+
* Cart attributes are automatically updated for order attribution if
|
|
613
|
+
* storefrontAccessToken was provided to initAnalytics() or passed here.
|
|
614
|
+
*
|
|
615
|
+
* @example After initAnalytics()
|
|
616
|
+
* ```ts
|
|
617
|
+
* await trackAddToCart({
|
|
618
|
+
* cartId: "gid://shopify/Cart/abc123",
|
|
619
|
+
* productId: "123456789",
|
|
620
|
+
* variantId: "987654321",
|
|
621
|
+
* productPrice: 99.99,
|
|
622
|
+
* productQuantity: 1,
|
|
623
|
+
* });
|
|
624
|
+
* ```
|
|
625
|
+
*/
|
|
626
|
+
declare function trackAddToCart(params: Omit<TrackAddToCartParams, "storeId" | "storefrontAccessToken"> & {
|
|
627
|
+
storeId?: string;
|
|
628
|
+
storefrontAccessToken?: string;
|
|
629
|
+
}): Promise<void>;
|
|
630
|
+
/**
|
|
631
|
+
* Track remove from cart event
|
|
632
|
+
* Call this when user removes item from cart
|
|
633
|
+
*/
|
|
634
|
+
declare function trackRemoveFromCart(params: Omit<TrackRemoveFromCartParams, "storeId"> & {
|
|
635
|
+
storeId?: string;
|
|
636
|
+
}): Promise<void>;
|
|
637
|
+
/**
|
|
638
|
+
* Track cart view event
|
|
639
|
+
* Call this when user views cart page
|
|
640
|
+
*/
|
|
641
|
+
declare function trackCartView(params: Omit<TrackCartViewParams, "storeId"> & {
|
|
642
|
+
storeId?: string;
|
|
643
|
+
}): Promise<void>;
|
|
644
|
+
/**
|
|
645
|
+
* Track search submitted event
|
|
646
|
+
* Call this when user submits a search
|
|
647
|
+
*
|
|
648
|
+
* @example After initAnalytics()
|
|
649
|
+
* ```ts
|
|
650
|
+
* await trackSearchSubmitted({ searchQuery: "running shoes" });
|
|
651
|
+
* ```
|
|
652
|
+
*
|
|
653
|
+
* @example Without init (pass params)
|
|
654
|
+
* ```ts
|
|
655
|
+
* await trackSearchSubmitted({
|
|
656
|
+
* storeId: "mystore.myshopify.com",
|
|
657
|
+
* searchQuery: "running shoes",
|
|
658
|
+
* currency: "USD"
|
|
659
|
+
* });
|
|
660
|
+
* ```
|
|
661
|
+
*/
|
|
662
|
+
declare function trackSearchSubmitted(params: Omit<TrackSearchSubmittedParams, "storeId"> & {
|
|
663
|
+
storeId?: string;
|
|
664
|
+
}): Promise<void>;
|
|
665
|
+
/**
|
|
666
|
+
* Track checkout started event
|
|
667
|
+
* Call this when user starts checkout
|
|
668
|
+
*
|
|
669
|
+
* @example After initAnalytics()
|
|
670
|
+
* ```ts
|
|
671
|
+
* await trackCheckoutStarted({
|
|
672
|
+
* cartTotalPrice: 109.98,
|
|
673
|
+
* cartItems: [...],
|
|
674
|
+
* });
|
|
675
|
+
* ```
|
|
676
|
+
*/
|
|
677
|
+
declare function trackCheckoutStarted(params: Omit<TrackCheckoutStartedParams, "storeId"> & {
|
|
678
|
+
storeId?: string;
|
|
679
|
+
}): Promise<void>;
|
|
680
|
+
/**
|
|
681
|
+
* Track checkout completed event (order placed)
|
|
682
|
+
* Call this when order is placed
|
|
683
|
+
*
|
|
684
|
+
* NOTE: This sends to a different endpoint (orders worker)
|
|
685
|
+
*
|
|
686
|
+
* @example After initAnalytics()
|
|
687
|
+
* ```ts
|
|
688
|
+
* await trackCheckoutCompleted({
|
|
689
|
+
* orderId: "order_123456",
|
|
690
|
+
* cartTotalPrice: 109.98,
|
|
691
|
+
* cartItems: [...],
|
|
692
|
+
* });
|
|
693
|
+
* ```
|
|
694
|
+
*/
|
|
695
|
+
declare function trackCheckoutCompleted(params: Omit<TrackCheckoutCompletedParams, "storeId"> & {
|
|
696
|
+
storeId?: string;
|
|
697
|
+
}): Promise<void>;
|
|
698
|
+
|
|
699
|
+
interface UseExperimentResult {
|
|
700
|
+
/** The full variant object (null if not assigned) */
|
|
701
|
+
variant: Variation | null;
|
|
702
|
+
/** True while loading config */
|
|
703
|
+
isLoading: boolean;
|
|
704
|
+
/** True if assigned to control group */
|
|
705
|
+
isControl: boolean;
|
|
706
|
+
/** True if assigned to variation A (first non-control) */
|
|
707
|
+
isA: boolean;
|
|
708
|
+
/** True if assigned to variation B (second non-control) */
|
|
709
|
+
isB: boolean;
|
|
710
|
+
/** True if assigned to variation C (third non-control) */
|
|
711
|
+
isC: boolean;
|
|
712
|
+
/** True if assigned to variation D (fourth non-control) */
|
|
713
|
+
isD: boolean;
|
|
714
|
+
}
|
|
715
|
+
/**
|
|
716
|
+
* Hook to get assigned variant for a test
|
|
717
|
+
*
|
|
718
|
+
* @example
|
|
719
|
+
* ```tsx
|
|
720
|
+
* const { isControl, isA, isB } = useExperiment('my-test');
|
|
721
|
+
*
|
|
722
|
+
* if (isControl) return <Original />;
|
|
723
|
+
* if (isA) return <VariantA />;
|
|
724
|
+
* if (isB) return <VariantB />;
|
|
725
|
+
* ```
|
|
726
|
+
*/
|
|
727
|
+
declare function useExperiment(testId: string): UseExperimentResult;
|
|
728
|
+
|
|
729
|
+
/**
|
|
730
|
+
* Hook to access Elevate config from context
|
|
731
|
+
*/
|
|
732
|
+
declare function useElevateConfig(): ElevateContextValue;
|
|
733
|
+
|
|
734
|
+
export { type CartItemInput, type ElevateConfig, type ElevateContextValue, ElevateNextProvider, type PreviewState, ProductViewTracker, type TrackAddToCartParams, type TrackPageViewParams, type TrackProductViewParams, type UseExperimentResult, clearPreviewMode, extractShopifyId, extractShopifyType, getCountryCode, getFlickerPreventionScript, getPreviewState, isInPreviewMode, isShopifyGid, matchesGeoTargeting, trackAddToCart, trackCartView, trackCheckoutCompleted, trackCheckoutStarted, trackPageView, trackProductView, trackRemoveFromCart, trackSearchSubmitted, useElevateConfig, useExperiment };
|