@liquidcommerce/elements-sdk 2.6.0-beta.93 → 2.6.0-beta.95
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/dist/index.checkout.esm.js +7862 -7146
- package/dist/index.esm.js +12759 -11541
- package/dist/types/core/a11y/announcer.service.d.ts +16 -0
- package/dist/types/core/a11y/focus-manager.service.d.ts +21 -0
- package/dist/types/core/a11y/focusable.d.ts +5 -0
- package/dist/types/core/a11y/index.d.ts +3 -0
- package/dist/types/core/base-component.service.d.ts +2 -0
- package/dist/types/core/google-tag-manager.service.d.ts +1 -0
- package/dist/types/interfaces/configs/global.interface.d.ts +2 -0
- package/dist/types/modules/address/address-input.component.d.ts +10 -1
- package/dist/types/modules/cart/components/cart-body.component.d.ts +1 -0
- package/dist/types/modules/cart/components/cart-item-quantity-price.component.d.ts +5 -0
- package/dist/types/modules/cart/components/cart-item.component.d.ts +6 -0
- package/dist/types/modules/checkout/components/checkout-completed.component.d.ts +2 -0
- package/dist/types/modules/checkout/components/checkout-item-quantity.component.d.ts +1 -0
- package/dist/types/modules/checkout/components/checkout-payment.component.d.ts +1 -0
- package/dist/types/modules/checkout/components/checkout-place-order-button.component.d.ts +2 -0
- package/dist/types/modules/product/components/product-drawer.component.d.ts +6 -0
- package/dist/types/modules/product/product.commands.d.ts +2 -2
- package/dist/types/modules/product-list/components/card-components/product-price-and-personalization.d.ts +2 -1
- package/dist/types/modules/product-list/components/card-components/product-sizes-list.d.ts +1 -0
- package/dist/types/modules/product-list/components/filter-components/product-list-fulfillment-filter.d.ts +1 -0
- package/dist/types/modules/product-list/components/product-list-filters.component.d.ts +1 -0
- package/dist/types/modules/product-list/components/product-list-product-pre-cart.component.d.ts +2 -0
- package/dist/types/modules/product-list/product-list.commands.d.ts +1 -1
- package/dist/types/modules/product-list/product-list.component.d.ts +3 -0
- package/dist/types/modules/ui-components/alert/alert.component.d.ts +1 -1
- package/dist/types/modules/ui-components/buttons/buttons-open-cart.component.d.ts +5 -0
- package/dist/types/modules/ui-components/drawer/drawer.component.d.ts +14 -0
- package/dist/types/modules/ui-components/engraving/engraving-form.component.d.ts +2 -0
- package/dist/types/modules/ui-components/engraving/engraving-view.component.d.ts +1 -0
- package/dist/types/modules/ui-components/input/input.component.d.ts +4 -0
- package/dist/types/modules/ui-components/ui.commands.d.ts +3 -1
- package/docs/v1/api/actions/cart-actions.md +9 -2
- package/docs/v1/api/actions/checkout-actions.md +2 -0
- package/docs/v1/api/client.md +84 -6
- package/docs/v1/api/configuration.md +10 -0
- package/docs/v1/api/typescript-types.md +5 -1
- package/docs/v1/getting-started/concepts.md +5 -3
- package/docs/v1/getting-started/installation.md +22 -1
- package/docs/v1/guides/cart-component.md +32 -0
- package/docs/v1/guides/product-component.md +6 -2
- package/docs/v1/guides/product-list-component.md +4 -5
- package/docs/v1/guides/theming.md +10 -0
- package/docs/v1/reference/analytics.md +108 -0
- package/docs/v1/reference/browser-support.md +3 -1
- package/docs/v1/reference/error-handling.md +8 -0
- package/docs/v1/reference/telemetry.md +85 -0
- package/docs/v1/reference/troubleshooting.md +1 -2
- package/package.json +44 -15
|
@@ -178,6 +178,8 @@ interface IInjectCheckoutParams {
|
|
|
178
178
|
|
|
179
179
|
### IInjectCheckoutBuilderParams
|
|
180
180
|
|
|
181
|
+
`simulatePresale` and `presaleExpiresInMinutes` are builder-only preview controls (presale lock defaults to 15 minutes) and only take effect via `ElementsBuilder().injectCheckoutElement()`.
|
|
182
|
+
|
|
181
183
|
```typescript
|
|
182
184
|
interface IInjectCheckoutBuilderParams extends IInjectCheckoutParams {
|
|
183
185
|
simulatePresale?: boolean;
|
|
@@ -293,7 +295,7 @@ interface ILiquidCommerceElementsActions {
|
|
|
293
295
|
|
|
294
296
|
### IElementsCheckoutActions
|
|
295
297
|
|
|
296
|
-
Checkout actions available in the checkout-only client.
|
|
298
|
+
Checkout actions available in the checkout-only client. This is `ICheckoutActions` with `openCheckout`, `closeCheckout`, and `toggleCheckout` omitted -- the checkout-only client renders checkout independently and has no drawer navigation to open, close, or toggle.
|
|
297
299
|
|
|
298
300
|
```typescript
|
|
299
301
|
interface IElementsCheckoutActions extends Omit<ICheckoutActions, 'openCheckout' | 'closeCheckout' | 'toggleCheckout'> {}
|
|
@@ -378,6 +380,8 @@ interface UpdateProductListComponent {
|
|
|
378
380
|
}
|
|
379
381
|
```
|
|
380
382
|
|
|
383
|
+
These `Update*Component` types are the arguments to the `ElementsBuilder()` client's `update*Component` methods; see [Client API](./client.md) for their behavior and usage.
|
|
384
|
+
|
|
381
385
|
See [Configuration Reference](./configuration.md) for detailed theme property descriptions.
|
|
382
386
|
|
|
383
387
|
---
|
|
@@ -96,11 +96,11 @@ The SDK uses a two-phase initialization strategy for optimal performance:
|
|
|
96
96
|
- Store initialization
|
|
97
97
|
- Theme setup
|
|
98
98
|
- Core component registration
|
|
99
|
-
- Telemetry / logger wiring
|
|
99
|
+
- Telemetry / logger wiring (see [Telemetry & Privacy](../reference/telemetry.md))
|
|
100
100
|
- Debug panel (if enabled)
|
|
101
101
|
|
|
102
102
|
**Phase 2: Deferred Services (next macrotask, via `setTimeout(…, 0)`)**
|
|
103
|
-
- Analytics (Google Tag Manager)
|
|
103
|
+
- Analytics (Google Tag Manager — see [Analytics (GTM/GA4)](../reference/analytics.md))
|
|
104
104
|
- Cart pre-loading
|
|
105
105
|
- Heavy component registration
|
|
106
106
|
|
|
@@ -368,10 +368,12 @@ const client = await Elements('YOUR_API_KEY', {
|
|
|
368
368
|
```
|
|
369
369
|
|
|
370
370
|
**Debug Modes:**
|
|
371
|
-
- `'none'` - No debug output (
|
|
371
|
+
- `'none'` - No debug output (default)
|
|
372
372
|
- `'console'` - Log to browser console
|
|
373
373
|
- `'panel'` - Show debug panel on page
|
|
374
374
|
|
|
375
|
+
> **Production note:** `debugMode` has no effect when `env` is `'production'`. All debug output — console logging and the debug panel — is disabled in production regardless of the `debugMode` you pass. `'console'` and `'panel'` only take effect in non-production environments.
|
|
376
|
+
|
|
375
377
|
## Security & API Keys
|
|
376
378
|
|
|
377
379
|
### API Key Protection
|
|
@@ -30,6 +30,16 @@ Add the following script tag to your page's `<head>` section:
|
|
|
30
30
|
></script>
|
|
31
31
|
```
|
|
32
32
|
|
|
33
|
+
> **Note:** The host `elements.reservebar-worker.workers.dev` shown above is an example, partner-specific endpoint. Use the CDN URL provided by your LiquidCommerce representative in place of this host.
|
|
34
|
+
|
|
35
|
+
The path segment selects which bundle is served:
|
|
36
|
+
|
|
37
|
+
| Path | Bundle |
|
|
38
|
+
|------|--------|
|
|
39
|
+
| `/all/elements.js` | Full SDK bundle (product, cart, checkout, and all other elements) |
|
|
40
|
+
| `/checkout/elements.js` | Checkout-only bundle (tree-shaken, smaller) |
|
|
41
|
+
| `/all/beta/elements.js` | Beta channel of the full SDK bundle |
|
|
42
|
+
|
|
33
43
|
### Script Attributes
|
|
34
44
|
|
|
35
45
|
| Attribute | Required | Description |
|
|
@@ -140,7 +150,16 @@ const config: ILiquidCommerceElementsConfig = {
|
|
|
140
150
|
}
|
|
141
151
|
};
|
|
142
152
|
|
|
143
|
-
|
|
153
|
+
// Elements() returns `null` in SSR / non-browser environments, so the
|
|
154
|
+
// client is typed as `ILiquidCommerceElementsClient | null`.
|
|
155
|
+
const client: ILiquidCommerceElementsClient | null = await Elements('YOUR_API_KEY', config);
|
|
156
|
+
|
|
157
|
+
if (client) {
|
|
158
|
+
// Safe to use the client here
|
|
159
|
+
client.injectProductElement([
|
|
160
|
+
{ containerId: 'product-1', identifier: '00619947000020' }
|
|
161
|
+
]);
|
|
162
|
+
}
|
|
144
163
|
```
|
|
145
164
|
|
|
146
165
|
## Framework Integration
|
|
@@ -255,6 +274,8 @@ const client = await Elements('YOUR_API_KEY', {
|
|
|
255
274
|
});
|
|
256
275
|
```
|
|
257
276
|
|
|
277
|
+
> **Note:** `debugMode` is ignored when `env` is `'production'`. Debug logging and the debug panel are only activated in non-production environments (`development` or `staging`).
|
|
278
|
+
|
|
258
279
|
See [Configuration Reference](../api/configuration.md) for complete configuration options.
|
|
259
280
|
|
|
260
281
|
## Verification
|
|
@@ -6,6 +6,7 @@ The Cart component provides a slide-out drawer for managing shopping cart items,
|
|
|
6
6
|
|
|
7
7
|
The Cart component automatically:
|
|
8
8
|
- Displays cart items with images and details
|
|
9
|
+
- Removes white / near-white backgrounds from item images so products blend into the drawer (automatic, not host-configurable)
|
|
9
10
|
- Groups items by retailer
|
|
10
11
|
- Shows real-time pricing and totals
|
|
11
12
|
- Supports quantity updates
|
|
@@ -342,6 +343,17 @@ window.addEventListener('lce:actions.cart_item_quantity_decrease', (event) => {
|
|
|
342
343
|
});
|
|
343
344
|
```
|
|
344
345
|
|
|
346
|
+
### Engraving Updated
|
|
347
|
+
|
|
348
|
+
Fired when a cart line item's engraving is added or edited from the drawer (see [Engraving](#engraving)):
|
|
349
|
+
|
|
350
|
+
```javascript
|
|
351
|
+
window.addEventListener('lce:actions.cart_item_engraving_updated', (event) => {
|
|
352
|
+
const { cartId, itemId, engravingLines, previousEngravingLines } = event.detail.data;
|
|
353
|
+
console.log(`Engraving updated for ${itemId}:`, engravingLines);
|
|
354
|
+
});
|
|
355
|
+
```
|
|
356
|
+
|
|
345
357
|
### Promo Code Events
|
|
346
358
|
|
|
347
359
|
```javascript
|
|
@@ -546,6 +558,26 @@ Items are automatically grouped by retailer in the cart:
|
|
|
546
558
|
└─────────────────────────────────────┘
|
|
547
559
|
```
|
|
548
560
|
|
|
561
|
+
## Order Minimums
|
|
562
|
+
|
|
563
|
+
Retailers can require a minimum purchase amount before their items can be checked out. The cart enforces this per retailer:
|
|
564
|
+
|
|
565
|
+
- When a retailer's minimum is not met, the cart drawer shows a per-retailer alert reading `+$X needed for order minimum`, where `$X` is the remaining amount required for that retailer.
|
|
566
|
+
- The **Checkout** button is disabled until every retailer's minimum is met. (It is also disabled while the cart is loading/updating or when the cart is empty.)
|
|
567
|
+
|
|
568
|
+
No configuration is required — the minimums are defined by each retailer and enforced automatically.
|
|
569
|
+
|
|
570
|
+
## Engraving
|
|
571
|
+
|
|
572
|
+
For engravable items, shoppers can add or edit engraving directly from a cart line item, without leaving the drawer.
|
|
573
|
+
|
|
574
|
+
- If an engravable item has no engraving yet, the line item shows an **Add personalization** action (with the engraving fee) that opens the engraving form.
|
|
575
|
+
- If the item already has engraving, its engraving is shown on the line item with an **Edit** button that reopens the form.
|
|
576
|
+
|
|
577
|
+
The form respects the item's engraving constraints — `maxLines`, `maxCharsPerLine`, and the per-item `fee`. Saving emits [`lce:actions.cart_item_engraving_updated`](#engraving-updated) with the item's `engravingLines` and `previousEngravingLines`.
|
|
578
|
+
|
|
579
|
+
**Note:** This in-drawer editing is distinct from the `engravingLines` array passed to [`addProduct`](#add-product-to-cart), which pre-fills engraving at the time an item is added.
|
|
580
|
+
|
|
549
581
|
## Checkout Navigation
|
|
550
582
|
|
|
551
583
|
### Checkout Drawer (Default)
|
|
@@ -148,6 +148,8 @@ Products with multiple images display in an interactive carousel:
|
|
|
148
148
|
- Thumbnail preview
|
|
149
149
|
- Lazy loading for performance
|
|
150
150
|
|
|
151
|
+
**Background removal:** Product images (the main detail image and the gallery) automatically have their white/near-white background removed so photos blend into the surrounding page background instead of sitting on a white box. The SDK picks the technique per image based on the host background — blending the white away on light backgrounds, or keying it out to true transparency on dark or transparent backgrounds — and skips SVG artwork, which is already transparent. This is applied automatically and is not currently host-configurable.
|
|
152
|
+
|
|
151
153
|
### Size Selection
|
|
152
154
|
|
|
153
155
|
For products with multiple sizes:
|
|
@@ -206,8 +208,8 @@ For products with multiple retailers:
|
|
|
206
208
|
|
|
207
209
|
**Popup View**
|
|
208
210
|
- "See Delivery Options" button (shows the available fulfillment count, e.g. "See Delivery Options (3)")
|
|
209
|
-
-
|
|
210
|
-
-
|
|
211
|
+
- Opens a plain, scrollable list of the available delivery/retailer options
|
|
212
|
+
- No filtering or search — select a retailer from the list to choose it
|
|
211
213
|
|
|
212
214
|
### Personalization/Engraving
|
|
213
215
|
|
|
@@ -366,6 +368,7 @@ const client = await Elements('YOUR_API_KEY', {
|
|
|
366
368
|
showOnlyMainImage: false, // Show all images or just the main one
|
|
367
369
|
showTitle: true,
|
|
368
370
|
showDescription: true,
|
|
371
|
+
descriptionPosition: 'below', // Description placement: 'above' or 'below'
|
|
369
372
|
showQuantityCounter: true,
|
|
370
373
|
showOffHours: true, // Show when retailer is closed
|
|
371
374
|
quantityCounterStyle: 'outlined', // or 'ghost'
|
|
@@ -376,6 +379,7 @@ const client = await Elements('YOUR_API_KEY', {
|
|
|
376
379
|
addToCartButtonShowTotalPrice: true,
|
|
377
380
|
buyNowButtonText: 'Buy Now',
|
|
378
381
|
preSaleButtonText: 'Pre-Order',
|
|
382
|
+
prioritizeEngraving: false, // Show engraving option before add-to-cart
|
|
379
383
|
noAvailabilityText: 'Not available in your area'
|
|
380
384
|
}
|
|
381
385
|
}
|
|
@@ -260,18 +260,19 @@ Each product card shows:
|
|
|
260
260
|
- Product name
|
|
261
261
|
- Brand
|
|
262
262
|
- Price (or price range for multiple sizes)
|
|
263
|
-
- Rating (if available)
|
|
264
263
|
- Clickable image/card linking to the product detail page (when `productUrl` is configured)
|
|
265
264
|
- "Add to Cart" button (optional)
|
|
266
265
|
- Availability indicator
|
|
267
266
|
|
|
267
|
+
Product card images automatically have their white/near-white backgrounds removed so the product blends into the surrounding card and page background. This treatment is applied at render time and is not host-configurable.
|
|
268
|
+
|
|
268
269
|
### Card Interaction
|
|
269
270
|
|
|
270
271
|
**Click on card:** Navigate to product detail page (if `productUrl` configured — see [Product URL Map](#product-url-map) for partner-owned PDP URLs that aren't derivable from a token).
|
|
271
272
|
|
|
272
273
|
**Quick Add:** Add product to cart directly from list view (if enabled)
|
|
273
274
|
|
|
274
|
-
**Click on image:**
|
|
275
|
+
**Click on image:** Navigate to the configured `productUrl` (only when `productUrl` is set — otherwise the image is not a link)
|
|
275
276
|
|
|
276
277
|
## Customization
|
|
277
278
|
|
|
@@ -514,10 +515,8 @@ The product list component includes:
|
|
|
514
515
|
### Optimization Features
|
|
515
516
|
|
|
516
517
|
- **Image lazy loading**: Images load as they enter viewport
|
|
517
|
-
- **
|
|
518
|
+
- **Progressive loading**: Products load in batches via an `IntersectionObserver` sentinel as you scroll — each page is appended to the grid and loaded cards remain in the DOM
|
|
518
519
|
- **Debounced search**: Reduces API calls during typing
|
|
519
|
-
- **Filter caching**: Caches filter results
|
|
520
|
-
- **Progressive loading**: Loads in batches
|
|
521
520
|
|
|
522
521
|
### Large Catalogs
|
|
523
522
|
|
|
@@ -53,6 +53,12 @@ customTheme: {
|
|
|
53
53
|
}
|
|
54
54
|
```
|
|
55
55
|
|
|
56
|
+
**Constraints:**
|
|
57
|
+
|
|
58
|
+
- Only Google Fonts are supported. Each font's `name` must be a valid Google Font name (for example, `'Poppins'` or `'Inter'`).
|
|
59
|
+
- `Poppins` is always loaded as the default font regardless of your configuration, so it remains available even if you do not specify it.
|
|
60
|
+
- Font loading requires network access to `fonts.googleapis.com` and `fonts.gstatic.com`. If your environment enforces a Content Security Policy or routes traffic through a proxy, allow these hosts so fonts can load.
|
|
61
|
+
|
|
56
62
|
### Border Radius
|
|
57
63
|
|
|
58
64
|
```javascript
|
|
@@ -77,12 +83,16 @@ customTheme: {
|
|
|
77
83
|
personalizationCardStyle: 'outlined', // or 'filled'
|
|
78
84
|
allowPromoCodes: true,
|
|
79
85
|
inputFieldStyle: 'outlined', // or 'filled'
|
|
86
|
+
enableOrderedProductSizes: true, // enable custom ordering of the size selectors
|
|
87
|
+
orderedProductSizes: ['750ml', '1L', '1.75L'], // order applied to product and product-list size selectors
|
|
80
88
|
poweredByMode: 'light' // or 'dark' (note: showPoweredBy is controlled server-side and cannot be overridden via customTheme)
|
|
81
89
|
}
|
|
82
90
|
}
|
|
83
91
|
}
|
|
84
92
|
```
|
|
85
93
|
|
|
94
|
+
`enableOrderedProductSizes` and `orderedProductSizes` control the ordering of the size selectors rendered by the product and product-list components. When `enableOrderedProductSizes` is `true`, size options are sorted to match the sequence in the `orderedProductSizes` string array. Updating either key triggers a targeted rerender of the affected size selectors.
|
|
95
|
+
|
|
86
96
|
## Component Themes
|
|
87
97
|
|
|
88
98
|
### Product Component
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
# Analytics & Google Tag Manager
|
|
2
|
+
|
|
3
|
+
The SDK ships with a built-in Google Tag Manager (GTM) / Google Analytics 4 (GA4) integration. It automatically pushes GA4 ecommerce events for the interactions your shoppers perform in Elements components — product views, cart changes, checkout steps, purchases, and more.
|
|
4
|
+
|
|
5
|
+
This runs entirely inside the SDK. In most cases you do not need to configure or code anything.
|
|
6
|
+
|
|
7
|
+
## What You Need To Do
|
|
8
|
+
|
|
9
|
+
**Typically nothing.** The integration is automatic in production and staging. The SDK receives its GTM container configuration from the LiquidCommerce platform (per partner) and initializes itself after the DOM is ready.
|
|
10
|
+
|
|
11
|
+
It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
|
|
12
|
+
|
|
13
|
+
## Supported Environments
|
|
14
|
+
|
|
15
|
+
GTM initialization and every event push are enabled in production and staging. When the SDK is running in development or Builder mode, no container is loaded and no events are sent.
|
|
16
|
+
|
|
17
|
+
Events are suppressed when any of the following is true:
|
|
18
|
+
|
|
19
|
+
- `window` is undefined (server-side rendering).
|
|
20
|
+
- The SDK is running in Builder mode.
|
|
21
|
+
- The environment is `development`.
|
|
22
|
+
|
|
23
|
+
The environment defaults to `production` when none is provided, so a standard production embed is analytics-enabled out of the box; a staging embed is also analytics-enabled when server GTM config is enabled for the partner.
|
|
24
|
+
|
|
25
|
+
## How It Works
|
|
26
|
+
|
|
27
|
+
### Container injection
|
|
28
|
+
|
|
29
|
+
When enabled, the SDK injects the GTM container script:
|
|
30
|
+
|
|
31
|
+
```
|
|
32
|
+
https://www.googletagmanager.com/gtm.js?id=<containerId>
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
The script is appended to `<head>` with `async` and `crossorigin="anonymous"`, and the SDK waits for GTM to initialize before flushing events.
|
|
36
|
+
|
|
37
|
+
### dataLayer and gtag
|
|
38
|
+
|
|
39
|
+
The SDK initializes the standard GTM globals **without clobbering an existing setup**:
|
|
40
|
+
|
|
41
|
+
- `window.dataLayer` is created only if it does not already exist.
|
|
42
|
+
- `window.gtag` is defined only if it is not already present.
|
|
43
|
+
|
|
44
|
+
Events are delivered using Google's recommended `window.dataLayer.push()` pattern.
|
|
45
|
+
|
|
46
|
+
### Event queueing
|
|
47
|
+
|
|
48
|
+
Events fired before GTM finishes initializing are queued (up to 100, oldest dropped first) and flushed once the container is ready. Queued events older than 30 seconds at flush time are discarded.
|
|
49
|
+
|
|
50
|
+
## Coexisting With Your Own GTM
|
|
51
|
+
|
|
52
|
+
The SDK detects an already-present partner/host GTM container rather than replacing it. When a host GTM install (an existing `gtag` function or an existing `googletagmanager.com/gtm.js` script tag) is detected, the SDK integrates with it.
|
|
53
|
+
|
|
54
|
+
When both the LiquidCommerce container and a partner container are initialized, events are sent to both using GA4's `send_to` targeting (a dual-container send). Only containers that are actually initialized are added to `send_to`, so events are never routed to a container that failed to load.
|
|
55
|
+
|
|
56
|
+
If the LiquidCommerce container can't be loaded, the SDK falls back — in order — to the partner container, any initialized GTM container on the page, or the basic `dataLayer` — so event tracking degrades gracefully instead of failing.
|
|
57
|
+
|
|
58
|
+
## Source Tracking (`tenant_*`)
|
|
59
|
+
|
|
60
|
+
Every event automatically carries source-tracking fields identifying the tenant and the SDK build:
|
|
61
|
+
|
|
62
|
+
| Field | Value |
|
|
63
|
+
| --- | --- |
|
|
64
|
+
| `tenant_name` | Partner name |
|
|
65
|
+
| `tenant_code` | Partner code |
|
|
66
|
+
| `tenant_env` | SDK environment |
|
|
67
|
+
| `tenant_source` | SDK package description and version |
|
|
68
|
+
|
|
69
|
+
## Events
|
|
70
|
+
|
|
71
|
+
All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.).
|
|
72
|
+
|
|
73
|
+
### Standard GA4 ecommerce events
|
|
74
|
+
|
|
75
|
+
| Event | Fired when |
|
|
76
|
+
| --- | --- |
|
|
77
|
+
| `view_item` | A shopper views a product |
|
|
78
|
+
| `view_item_list` | A shopper views a list of products |
|
|
79
|
+
| `select_item` | A shopper selects a product from a list |
|
|
80
|
+
| `add_to_cart` | A shopper adds an item to the cart |
|
|
81
|
+
| `view_cart` | A shopper views the cart |
|
|
82
|
+
| `remove_from_cart` | A shopper removes an item from the cart |
|
|
83
|
+
| `begin_checkout` | A shopper begins checkout |
|
|
84
|
+
| `add_shipping_info` | Shipping info is added during checkout |
|
|
85
|
+
| `add_payment_info` | Payment info is added during checkout |
|
|
86
|
+
| `purchase` | A purchase completes |
|
|
87
|
+
|
|
88
|
+
### Custom events
|
|
89
|
+
|
|
90
|
+
| Event | Fired when |
|
|
91
|
+
| --- | --- |
|
|
92
|
+
| `promo_code_attempt` | A promo code is submitted |
|
|
93
|
+
| `promo_code_applied` | A promo code is successfully applied |
|
|
94
|
+
| `promo_code_failed` | A promo code fails to apply |
|
|
95
|
+
| `gift_card_attempt` | A gift card is submitted |
|
|
96
|
+
| `gift_card_applied` | A gift card is successfully applied |
|
|
97
|
+
| `gift_card_failed` | A gift card fails to apply |
|
|
98
|
+
| `address_updated` | An address is successfully updated |
|
|
99
|
+
| `address_failed` | An address operation fails |
|
|
100
|
+
| `product_no_availability` | A product has no availability for any size/fulfillment |
|
|
101
|
+
| `product_size_no_availability` | A selected size has no availability |
|
|
102
|
+
| `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
|
|
103
|
+
|
|
104
|
+
## Related Docs
|
|
105
|
+
|
|
106
|
+
- [Events Guide](../guides/events.md)
|
|
107
|
+
- [Client API](../api/client.md)
|
|
108
|
+
- [Troubleshooting](./troubleshooting.md)
|
|
@@ -25,7 +25,9 @@ In non-browser environments, initialization is skipped. If you call the SDK on t
|
|
|
25
25
|
it returns `null` and logs a warning instead of throwing.
|
|
26
26
|
|
|
27
27
|
Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
|
|
28
|
-
to render components.
|
|
28
|
+
to render components. `Elements` and `ElementsBuilder` resolve to no-op stubs from the main SSR
|
|
29
|
+
entry; `ElementsCheckout` ships in its own tree-shaken entry with a separate stub, so it is safe to
|
|
30
|
+
import even if you never use the other two.
|
|
29
31
|
|
|
30
32
|
## Polyfills (Legacy Browsers)
|
|
31
33
|
|
|
@@ -68,6 +68,14 @@ window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
|
|
|
68
68
|
|
|
69
69
|
When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
|
|
70
70
|
|
|
71
|
+
## Global Error Interception
|
|
72
|
+
|
|
73
|
+
On load, the SDK installs its own global handlers by reassigning `window.onerror` and `window.onunhandledrejection`. Each incoming error or rejection is classified by an `isSDKError` heuristic that inspects the error's message, stack, and source — matching a script `src` ending in `/elements.js`, known SDK class and directory patterns, and an `isSdk` flag on `SDKError` instances.
|
|
74
|
+
|
|
75
|
+
When an error is classified as SDK-originated, the handler logs it to the console and returns `true` (for `onerror`) or calls `event.preventDefault()` (for `onunhandledrejection`), so the error is swallowed and never reaches your app. Errors that are not classified as SDK-originated are chained to any handler that was already installed before the SDK loaded.
|
|
76
|
+
|
|
77
|
+
> **Implications:** SDK-originated errors are intentionally suppressed and will **not** surface in your host error monitoring (e.g. Sentry). Conversely, the heuristic is pattern-based and can occasionally match a non-SDK error, causing it to be swallowed too. If you rely on catching failures, use the `*_failed` events and `try/catch` described above rather than global error monitoring.
|
|
78
|
+
|
|
71
79
|
## Related Docs
|
|
72
80
|
|
|
73
81
|
- [Events Guide](../guides/events.md)
|
|
@@ -0,0 +1,85 @@
|
|
|
1
|
+
# Telemetry & Privacy
|
|
2
|
+
|
|
3
|
+
The SDK includes lightweight, privacy-conscious telemetry that reports errors and warnings back to LiquidCommerce so the platform can detect and fix production issues. This page is a full disclosure of **what** is collected, **when**, **where** it is sent, and **how to turn it off**.
|
|
4
|
+
|
|
5
|
+
Telemetry never blocks or breaks your page — capture and sending are wrapped so internal failures are swallowed silently.
|
|
6
|
+
|
|
7
|
+
## When It Is Enabled
|
|
8
|
+
|
|
9
|
+
Telemetry is enabled **only** when both conditions are true:
|
|
10
|
+
|
|
11
|
+
- The SDK is running in the **production** environment (`env === 'production'`), and
|
|
12
|
+
- **No custom API URL is configured** (`hasCustomApiUrl` is `false`).
|
|
13
|
+
|
|
14
|
+
In every other case it is **disabled** and no events are queued or sent:
|
|
15
|
+
|
|
16
|
+
- Non-production environments (e.g. staging/development).
|
|
17
|
+
- A custom API URL / proxy is configured via `development.customApiUrl`.
|
|
18
|
+
- Internal telemetry errors are only logged to the console in non-production or when debugging is enabled — never sent.
|
|
19
|
+
|
|
20
|
+
## What Is Collected
|
|
21
|
+
|
|
22
|
+
Each event carries the message, severity level, and timestamp, plus three context blocks.
|
|
23
|
+
|
|
24
|
+
**Browser context**
|
|
25
|
+
|
|
26
|
+
- `userAgent` — the browser user-agent string
|
|
27
|
+
- `url` — the full current page URL (`window.location.href`)
|
|
28
|
+
- `referrer` — the referring URL, if any
|
|
29
|
+
- `timezone` — the resolved IANA timezone (e.g. `America/New_York`)
|
|
30
|
+
- `deviceType` — device classification (desktop/mobile/tablet)
|
|
31
|
+
|
|
32
|
+
**User context**
|
|
33
|
+
|
|
34
|
+
- `deviceId` — the SDK-generated device id (falls back to `not_defined`)
|
|
35
|
+
- `isLocalStorageAvailable` — whether localStorage is usable
|
|
36
|
+
- `selectedAddress` — the user's currently selected **formatted address string**, if one is set
|
|
37
|
+
|
|
38
|
+
**SDK context**
|
|
39
|
+
|
|
40
|
+
- `version`, `env`, `isBuilder`, and `partnerCode`
|
|
41
|
+
|
|
42
|
+
**Errors** (when the event represents one) include the error `name`, `message`, `code`, and a stack trace **truncated to the first 10 lines**.
|
|
43
|
+
|
|
44
|
+
Only **warnings** and **errors/fatal** events are captured. Debug/log/info events are excluded by default (`includeDebugLogs: false`).
|
|
45
|
+
|
|
46
|
+
## Where It Is Sent
|
|
47
|
+
|
|
48
|
+
Events are **batched** and sent to:
|
|
49
|
+
|
|
50
|
+
```
|
|
51
|
+
<baseUrl>/api/telemetry
|
|
52
|
+
```
|
|
53
|
+
|
|
54
|
+
`baseUrl` is the SDK's configured API host. Because telemetry is disabled whenever a custom API URL is set, events are only ever sent to LiquidCommerce's own endpoint — never to a partner proxy.
|
|
55
|
+
|
|
56
|
+
Batches are delivered with `navigator.sendBeacon`, falling back to a **synchronous `XMLHttpRequest`** if sendBeacon is unavailable or fails. Payloads are sent as `text/plain`.
|
|
57
|
+
|
|
58
|
+
Batches flush:
|
|
59
|
+
|
|
60
|
+
- When the queue reaches the batch size (5 events in production),
|
|
61
|
+
- On a periodic timer (every 5s in production), and
|
|
62
|
+
- On page teardown (`beforeunload` / `pagehide`), so pending events are not lost.
|
|
63
|
+
|
|
64
|
+
The queue is capped (max 50 events); oldest events are dropped first if it overflows.
|
|
65
|
+
|
|
66
|
+
## Disabling Telemetry
|
|
67
|
+
|
|
68
|
+
There is no separate opt-out flag — telemetry follows the two conditions above. To ensure it never runs, do either of the following:
|
|
69
|
+
|
|
70
|
+
- Run the SDK in a **non-production** environment, or
|
|
71
|
+
- Configure a **custom API URL** so events are routed through your own infrastructure and SDK telemetry is switched off:
|
|
72
|
+
|
|
73
|
+
```javascript
|
|
74
|
+
const client = await Elements('YOUR_API_KEY', {
|
|
75
|
+
development: {
|
|
76
|
+
customApiUrl: 'https://your-proxy.example.com'
|
|
77
|
+
}
|
|
78
|
+
});
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
## Related Docs
|
|
82
|
+
|
|
83
|
+
- [Error Handling](./error-handling.md)
|
|
84
|
+
- [Client API](../api/client.md)
|
|
85
|
+
- [Troubleshooting](./troubleshooting.md)
|
|
@@ -105,8 +105,7 @@ This is expected behavior. The SDK ships SSR stubs that are automatically resolv
|
|
|
105
105
|
|
|
106
106
|
**Fixes:**
|
|
107
107
|
- Verify all 5 required fields are set: `promoCode`, `text`, `separator`, `activeFrom`, `activeUntil`.
|
|
108
|
-
- Check that the current time falls between `activeFrom` and `activeUntil` (ISO 8601 UTC format).
|
|
109
|
-
- Ensure `global.layout.allowPromoCodes` is not set to `false`.
|
|
108
|
+
- Check that the current time falls between `activeFrom` and `activeUntil` (ISO 8601 UTC format). The ticker only renders when at least one configured ticker is currently active — the active window is evaluated against the shopper's timezone (derived from the current address state, falling back to the browser timezone), so a ticker with a valid but out-of-window range will not appear.
|
|
110
109
|
|
|
111
110
|
## Ad Blockers Blocking SDK Requests
|
|
112
111
|
|
package/package.json
CHANGED
|
@@ -3,7 +3,7 @@
|
|
|
3
3
|
"description": "LiquidCommerce Elements SDK",
|
|
4
4
|
"license": "UNLICENSED",
|
|
5
5
|
"author": "LiquidCommerce Team",
|
|
6
|
-
"version": "2.6.0-beta.
|
|
6
|
+
"version": "2.6.0-beta.95",
|
|
7
7
|
"homepage": "https://docs.liquidcommerce.co/elements-sdk",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
},
|
|
15
15
|
"module": "./dist/index.esm.js",
|
|
16
16
|
"types": "./dist/types/index.d.ts",
|
|
17
|
-
"packageManager": "pnpm@11.
|
|
17
|
+
"packageManager": "pnpm@11.18.0",
|
|
18
18
|
"exports": {
|
|
19
19
|
".": {
|
|
20
20
|
"types": "./dist/types/index.d.ts",
|
|
@@ -68,18 +68,47 @@
|
|
|
68
68
|
},
|
|
69
69
|
"keywords": [
|
|
70
70
|
"liquidcommerce",
|
|
71
|
+
"vesper",
|
|
72
|
+
"vesper-commerce",
|
|
73
|
+
"accelpay",
|
|
74
|
+
"reservebar",
|
|
75
|
+
"minibar",
|
|
71
76
|
"alcohol",
|
|
72
77
|
"beverage",
|
|
73
|
-
"alcohol tech",
|
|
74
78
|
"elements",
|
|
75
|
-
"
|
|
76
|
-
"
|
|
77
|
-
"
|
|
78
|
-
"
|
|
79
|
+
"alcohol-ecommerce",
|
|
80
|
+
"ecommerce",
|
|
81
|
+
"ecommerce-sdk",
|
|
82
|
+
"headless-commerce",
|
|
83
|
+
"embeddable-commerce",
|
|
84
|
+
"embeddable-components",
|
|
85
|
+
"web-components",
|
|
86
|
+
"custom-elements",
|
|
87
|
+
"shadow-dom",
|
|
88
|
+
"framework-agnostic",
|
|
89
|
+
"typescript",
|
|
90
|
+
"zero-dependencies",
|
|
91
|
+
"product-display",
|
|
92
|
+
"product-list",
|
|
93
|
+
"shopping-cart",
|
|
94
|
+
"cart-drawer",
|
|
95
|
+
"checkout",
|
|
96
|
+
"hosted-checkout",
|
|
97
|
+
"stripe",
|
|
98
|
+
"payments",
|
|
99
|
+
"promo-codes",
|
|
100
|
+
"gift-cards",
|
|
101
|
+
"address-autocomplete",
|
|
102
|
+
"delivery",
|
|
103
|
+
"shipping",
|
|
104
|
+
"pickup",
|
|
105
|
+
"presale",
|
|
106
|
+
"fulfillment",
|
|
107
|
+
"theming"
|
|
79
108
|
],
|
|
80
109
|
"devDependencies": {
|
|
81
|
-
"@biomejs/biome": "^2.5.
|
|
82
|
-
"@commitlint/cli": "^21.2.
|
|
110
|
+
"@biomejs/biome": "^2.5.6",
|
|
111
|
+
"@commitlint/cli": "^21.2.1",
|
|
83
112
|
"@commitlint/config-conventional": "^21.2.0",
|
|
84
113
|
"@rollup/plugin-alias": "^6.0.0",
|
|
85
114
|
"@rollup/plugin-commonjs": "^29.0.3",
|
|
@@ -87,21 +116,21 @@
|
|
|
87
116
|
"@rollup/plugin-node-resolve": "^16.0.3",
|
|
88
117
|
"@rollup/plugin-replace": "^6.0.3",
|
|
89
118
|
"@rollup/plugin-terser": "^1.0.0",
|
|
90
|
-
"@semantic-release/changelog": "^
|
|
119
|
+
"@semantic-release/changelog": "^7.0.0",
|
|
91
120
|
"@semantic-release/commit-analyzer": "^13.0.1",
|
|
92
|
-
"@semantic-release/git": "^
|
|
121
|
+
"@semantic-release/git": "^11.0.1",
|
|
93
122
|
"@semantic-release/github": "^12.0.9",
|
|
94
123
|
"@semantic-release/npm": "^13.1.5",
|
|
95
124
|
"@semantic-release/release-notes-generator": "^14.1.1",
|
|
96
125
|
"@types/core-js": "^2.5.8",
|
|
97
|
-
"@types/node": "^26.1.
|
|
98
|
-
"conventional-changelog": "8.0
|
|
126
|
+
"@types/node": "^26.1.2",
|
|
127
|
+
"conventional-changelog": "8.1.0",
|
|
99
128
|
"husky": "^9.1.7",
|
|
100
129
|
"process": "^0.11.10",
|
|
101
|
-
"rollup": "^4.62.
|
|
130
|
+
"rollup": "^4.62.3",
|
|
102
131
|
"rollup-obfuscator": "^4.1.1",
|
|
103
132
|
"rollup-plugin-typescript2": "^0.37.0",
|
|
104
|
-
"semantic-release": "^25.0.
|
|
133
|
+
"semantic-release": "^25.0.8",
|
|
105
134
|
"ts-node": "^10.9.2",
|
|
106
135
|
"typescript": "6.0.3"
|
|
107
136
|
},
|