@liquidcommerce/elements-sdk 2.6.0-beta.13 → 2.6.0-beta.130

package/docs/v1/reference/analytics.md

@@ -0,0 +1,176 @@
+# Analytics & Google Tag Manager
+
+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.
+
+This runs entirely inside the SDK. In most cases you do not need to configure or code anything.
+
+## What You Need To Do
+
+**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.
+
+It coexists with a host site's own GTM — see [Coexisting With Your Own GTM](#coexisting-with-your-own-gtm) below.
+
+The one case that needs code: if **your own UI** renders a step Elements would otherwise render — a
+product page, an address picker, a cart, or a "Proceed to checkout" in front of the checkout-only
+client — Elements never sees it. Report it with `actions.analytics` — see
+[Reporting Steps Your Own UI Renders](#reporting-steps-your-own-ui-renders).
+
+## Supported Environments
+
+GTM initialization and every event push are enabled in production and staging. When the SDK is running in Builder mode, no container is loaded and no events are sent.
+
+Events are suppressed when any of the following is true:
+
+- `window` is undefined (server-side rendering).
+- The SDK is running in Builder mode.
+
+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.
+
+## How It Works
+
+### Container injection
+
+When enabled, the SDK injects the GTM container script:
+
+```
+https://www.googletagmanager.com/gtm.js?id=<containerId>
+```
+
+The script is appended to `<head>` with `async` and `crossorigin="anonymous"`, and the SDK waits for GTM to initialize before flushing events.
+
+### dataLayer and gtag
+
+The SDK initializes the standard GTM globals **without clobbering an existing setup**:
+
+- `window.dataLayer` is created only if it does not already exist.
+- `window.gtag` is defined only if it is not already present.
+
+Events are delivered using Google's recommended `window.dataLayer.push()` pattern.
+
+### Event queueing
+
+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.
+
+## Coexisting With Your Own GTM
+
+The SDK detects an already-present partner/host GTM container rather than replacing it. When a host GTM install (an existing `gtag` function, an existing `googletagmanager.com/gtm.js` script tag, or a script served from your configured Google tag gateway) is detected, the SDK integrates with it. A container that has booted is also recognized through GTM's own `window.google_tag_manager[containerId]` registry, whichever host served it.
+
+### Google tag gateway
+
+[Google tag gateway for advertisers](https://developers.google.com/tag-platform/tag-manager/gateway/get-started) serves your Google tags from your own domain instead of Google's. Your GTM container loads from a first-party path such as `https://www.yoursite.com/metrics/` instead of `https://www.googletagmanager.com/gtm.js?id=GTM-XXXX`, and its measurement requests (e.g. GA4 `/g/collect` hits) go out through that same path. Your CDN or load balancer forwards them to Google, so they are less likely to be blocked than requests to Google's domains.
+
+#### How the SDK works with it
+
+- The SDK pushes every event to the page's `window.dataLayer`. Your container reads that same `dataLayer`, so it receives SDK events whether it loads from Google or from your gateway. Keep the default `dataLayer` name: a container renamed with `&l=` never sees them.
+- The SDK never loads your container and proxies nothing. The LiquidCommerce container still loads from `googletagmanager.com`.
+- To send SDK events to your own GA4 property, add a Custom Event trigger in your container on the [event names](#events) below and a GA4 Event tag that fires on it. The SDK puts `items`, `value` and `currency` at the top level of each event, not inside an `ecommerce` object, so map them with Data Layer Variables rather than the GA4 tag's "Send Ecommerce data" option.
+
+#### `gatewayUrl`
+
+Tell the SDK your gateway path so it can recognize your container:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  gtm: { gatewayUrl: 'https://www.yoursite.com/metrics/' }, // or '/metrics/'
+});
+```
+
+Or declaratively, on the script tag: `data-gtm-gateway-url="/metrics/"`.
+
+A gateway script URL usually carries no container ID, so until GTM has booted your container this setting is the only way the SDK can match the script tag to it. Once matched, your container ID is added to each event's `send_to` targets. The setting is optional: events reach your container through `dataLayer` without it.
+
+A script with the same origin whose path starts with that value is matched to your partner container by container ID: an `id=` query parameter must equal your partner container ID, and a script without one counts only once GTM's `window.google_tag_manager` registry lists your container ID (or while no container has booted yet). A gateway serving a different container or a GA4/Ads tag is therefore never taken for yours. Relative values resolve against the current page.
+
+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.
+
+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.
+
+## Source Tracking (`tenant_*`)
+
+Every event automatically carries source-tracking fields identifying the tenant and the SDK build:
+
+| Field | Value |
+| --- | --- |
+| `tenant_name` | Partner name |
+| `tenant_code` | Partner code |
+| `tenant_env` | SDK environment |
+| `tenant_source` | SDK package description and version |
+
+## Events
+
+All events are GA4-shaped and follow the standard ecommerce schema (`items[]`, `value`, `currency` — the SDK uses `USD`, `coupon`, etc.). `search` is the exception: it carries only `search_term`.
+
+### Standard GA4 ecommerce events
+
+| Event | Fired when |
+| --- | --- |
+| `view_item` | A shopper views a product, and again on each size they switch to |
+| `view_item_list` | A product list loads products: its first load, a filtered or searched list, each "load more" |
+| `select_item` | A shopper opens a product from a product list card |
+| `add_to_cart` | A shopper adds an item: from the product component or a list card, `actions.cart.addProduct()` / `actions.checkout.addProduct()`, a cart or checkout quantity increase, or a presale added straight to checkout |
+| `view_cart` | The cart drawer opens with items in it — the cart button, `openCart()` / `toggleCart()`, the checkout's back button — or an add that opens it lands |
+| `remove_from_cart` | A shopper lowers an item's quantity or removes it, in the cart or in the checkout |
+| `begin_checkout` | A shopper begins checkout: the cart's Checkout button (also before its redirect to `checkout.pageUrl`), `actions.checkout.addProduct()`, `openCheckout()` / `toggleCheckout()` opening the drawer, a presale added straight to checkout, or the first wallet tap on express buttons placed on their own |
+| `add_shipping_info` | Shipping info is added during checkout: the customer or gift recipient form is saved, or a wallet (Apple Pay / Google Pay) order hands over the wallet's contact details |
+| `add_payment_info` | Payment info is added during checkout |
+| `purchase` | A purchase completes |
+| `search` | A search typed into the product list's search box runs |
+
+### Custom events
+
+| Event | Fired when |
+| --- | --- |
+| `promo_code_attempt` | A promo code is submitted |
+| `promo_code_applied` | A promo code is successfully applied |
+| `promo_code_failed` | A promo code fails to apply |
+| `gift_card_attempt` | A gift card is submitted |
+| `gift_card_applied` | A gift card is successfully applied |
+| `gift_card_failed` | A gift card fails to apply |
+| `address_updated` | An address is successfully updated |
+| `address_failed` | An address operation fails |
+| `product_no_availability` | A product has no availability for any size/fulfillment |
+| `product_size_no_availability` | A selected size has no availability |
+| `product_fulfillment_no_availability` | A selected fulfillment type has no availability |
+
+## Reporting Steps Your Own UI Renders
+
+Elements reports the steps its components render. A host that renders some steps itself reports
+them through `actions.analytics`, on the full client and on the checkout-only client:
+
+| Action | Event |
+| --- | --- |
+| `search(searchTerm)` | `search` |
+| `viewItem(item)` | `view_item` |
+| `viewItemList(items, list?)` | `view_item_list` |
+| `selectItem(item, list?)` | `select_item` |
+| `addToCart(item)` | `add_to_cart` |
+| `removeFromCart(item)` | `remove_from_cart` |
+| `viewCart(items)` | `view_cart` |
+| `beginCheckout(items, { coupon? })` | `begin_checkout` |
+| `addressUpdated(address)` | `address_updated` |
+| `addressFailed(failure)` | `address_failed` |
+| `productNoAvailability(details)` | `product_no_availability` |
+| `productSizeNoAvailability(details)` | `product_size_no_availability` |
+| `productFulfillmentNoAvailability(details)` | `product_fulfillment_no_availability` |
+
+They go through the same pipeline as the SDK's own events — same shape, `tenant_*` fields,
+`send_to` targets, environment gating and queueing — so a report built on Elements events covers
+both. There are no actions for `add_shipping_info`, `add_payment_info`, `purchase` or the promo code
+and gift card events: the Elements checkout reports those itself, and a host reporting them too
+would count every order twice. For the same reason, don't report a step an Elements component
+renders — including `begin_checkout`, which Elements reports from the cart's Checkout button,
+`actions.checkout.addProduct()`, `openCheckout()` / `toggleCheckout()`, a presale, and the first
+wallet tap on express buttons placed on their own.
+
+Malformed input never throws: the event is skipped and a warning logged, so reporting can't break
+the host's page.
+
+Items take prices in cents, as product responses carry them, and send them in dollars. Full
+signatures and examples: [Analytics Actions](../api/actions/analytics-actions.md).
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Analytics Actions](../api/actions/analytics-actions.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/browser-support.md

@@ -0,0 +1,47 @@
+# Browser Support
+
+The Elements SDK requires modern browser features (Web Components + Shadow DOM). If you need to support older browsers, include polyfills.
+
+## Minimum Versions
+
+- Chrome 66+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+
+## Required Features
+
+- Custom Elements (Web Components)
+- Shadow DOM
+- ES2018 JavaScript
+- Fetch API
+
+**LocalStorage (optional, recommended):** used as a fast path for session persistence (cart/address). When unavailable (incognito, Safari/Firefox private mode, in-app webviews, cross-origin iframes), the SDK falls back to a generated device fingerprint plus server-side session persistence, so functionality is preserved.
+
+## Server-Side Rendering (SSR)
+
+The SDK is browser-only, but it is safe to import in SSR frameworks (Next.js, Remix, Nuxt).
+In non-browser environments, initialization is skipped. If you call the SDK on the server,
+it returns `null` and logs a warning instead of throwing.
+
+Call `Elements`, `ElementsCheckout`, or `ElementsBuilder` from client-only code (e.g., after mount)
+to render components. `Elements` and `ElementsBuilder` resolve to no-op stubs from the main SSR
+entry; `ElementsCheckout` ships in its own tree-shaken entry with a separate stub, so it is safe to
+import even if you never use the other two.
+
+## Polyfills (Legacy Browsers)
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## Notes
+
+- Always load the SDK script with `defer` to avoid blocking page render.
+- If you see Web Components errors in the console, add the polyfill before the SDK.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/error-handling.md

@@ -0,0 +1,83 @@
+# Error Handling
+
+The SDK emits errors as events and (when applicable) throws a custom `SDKError`. Your app should handle both.
+
+## SDKError
+
+All SDK errors use a custom error class:
+
+```typescript
+class SDKError extends Error {
+  constructor(message: string, reThrow?: boolean);
+  name: 'SDKError';
+  isSdk: boolean;
+  reThrow: boolean;
+}
+```
+
+## Catching Errors
+
+```javascript
+try {
+  // Structural input errors throw a catchable SDKError — e.g. a non-array
+  // argument or an empty array:
+  await window.LiquidCommerce.elements.injectProductElement([]);
+} catch (error) {
+  if (error.name === 'SDKError') {
+    console.error('SDK Error:', error);
+  }
+}
+```
+
+> A well-formed entry with an invalid product identifier does **not** throw — it renders an error view inside the component and sets an error in the store. `try/catch` here only catches malformed input: a missing or non-string `identifier`, a `fulfillmentType` other than `shipping`/`onDemand`, or a `quantity` below 1. An **empty array logs a warning and resolves** — it does not throw and emits no event.
+
+## Error Isolation
+
+Component failures are contained — a component that fails to load renders an error view and logs to the console without crashing your page. Action methods (like `cart.addProduct`) emit a `*_FAILED` event on failure, and re-throw only on an unexpected error; several soft-failure paths (e.g. no product found, no items added) emit the failure event but still resolve. Wrap calls in try/catch **and** listen for the corresponding `*_failed` event to reliably detect failures:
+
+```javascript
+try {
+  await window.LiquidCommerce.elements.actions.cart.addProduct([/* invalid */]);
+} catch (error) {
+  console.log('Handled add-to-cart failure');
+}
+```
+
+## Error Events
+
+Listen for failure events to show user-friendly messages or trigger retries:
+
+```javascript
+// Cart add failed
+window.addEventListener('lce:actions.cart_product_add_failed', (event) => {
+  console.error('Failed to add:', event.detail.data.error);
+});
+
+// Address failed
+window.addEventListener('lce:actions.address_failed', (event) => {
+  console.error('Address error:', event.detail.data.error);
+});
+
+// Checkout submit failed
+window.addEventListener('lce:actions.checkout_submit_failed', (event) => {
+  console.error('Checkout failed:', event.detail.data.message);
+});
+```
+
+## UI Errors
+
+When a component fails to load, the SDK renders an error view inside the container and logs details to the console.
+
+## Global Error Interception
+
+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.
+
+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.
+
+> **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.
+
+## Related Docs
+
+- [Events Guide](../guides/events.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/performance.md

@@ -0,0 +1,52 @@
+# Performance Guide
+
+The SDK is optimized out of the box. These tweaks help reduce load time and layout shift.
+
+## 1) Load Non-Blocking
+
+```html
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## 2) Use the Checkout-Only Build When Appropriate
+
+If you only need checkout, use the tree-shaken build:
+
+```javascript
+import { ElementsCheckout } from '@liquidcommerce/elements-sdk/checkout';
+```
+
+## 3) Inject Components When Needed
+
+Inject above-the-fold products first, then load the rest:
+
+```javascript
+await client.injectProductElement([
+  { containerId: 'hero-product', identifier: '001' }
+]);
+
+setTimeout(async () => {
+  await client.injectProductElement([
+    { containerId: 'related-1', identifier: '002' },
+    { containerId: 'related-2', identifier: '003' }
+  ]);
+}, 1000);
+```
+
+## 4) Reserve Space to Prevent Layout Shift
+
+```css
+#product {
+  min-height: 600px;
+}
+```
+
+## 5) Let the SDK Handle Media Optimization
+
+The SDK automatically:
+- Lazy loads carousel/thumbnail images (native `loading="lazy"`)
+
+## Related Docs
+
+- [Best Practices](../guides/best-practices.md)
+- [Product Component](../guides/product-component.md)

package/docs/v1/reference/telemetry.md

@@ -0,0 +1,85 @@
+# Telemetry & Privacy
+
+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**.
+
+Telemetry never blocks or breaks your page — capture and sending are wrapped so internal failures are swallowed silently.
+
+## When It Is Enabled
+
+Telemetry is enabled **only** when both conditions are true:
+
+- The SDK is running in the **production** environment (`env === 'production'`), and
+- **No custom API URL is configured** (`hasCustomApiUrl` is `false`).
+
+In every other case it is **disabled** and no events are queued or sent:
+
+- Non-production environments (i.e. staging).
+- A custom API URL / proxy is configured via `development.customApiUrl`.
+- Internal telemetry errors are only logged to the console in non-production or when debugging is enabled — never sent.
+
+## What Is Collected
+
+Each event carries the message, severity level, and timestamp, plus three context blocks.
+
+**Browser context**
+
+- `userAgent` — the browser user-agent string
+- `url` — the full current page URL (`window.location.href`)
+- `referrer` — the referring URL, if any
+- `timezone` — the resolved IANA timezone (e.g. `America/New_York`)
+- `deviceType` — device classification (desktop/mobile/tablet)
+
+**User context**
+
+- `deviceId` — the SDK-generated device id (falls back to `not_defined`)
+- `isLocalStorageAvailable` — whether localStorage is usable
+- `selectedAddress` — the user's currently selected **formatted address string**, if one is set
+
+**SDK context**
+
+- `version`, `env`, `isBuilder`, and `partnerCode`
+
+**Errors** (when the event represents one) include the error `name`, `message`, `code`, and a stack trace **truncated to the first 10 lines**.
+
+Only **warnings** and **errors/fatal** events are captured. Debug/log/info events are excluded by default (`includeDebugLogs: false`).
+
+## Where It Is Sent
+
+Events are **batched** and sent to:
+
+```
+<baseUrl>/api/telemetry
+```
+
+`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.
+
+Batches are delivered with `navigator.sendBeacon`, falling back to a **synchronous `XMLHttpRequest`** if sendBeacon is unavailable or fails. Payloads are sent as `text/plain`.
+
+Batches flush:
+
+- When the queue reaches the batch size (5 events in production),
+- On a periodic timer (every 5s in production), and
+- On page teardown (`beforeunload` / `pagehide`), so pending events are not lost.
+
+The queue is capped (max 50 events); oldest events are dropped first if it overflows.
+
+## Disabling Telemetry
+
+There is no separate opt-out flag — telemetry follows the two conditions above. To ensure it never runs, do either of the following:
+
+- Run the SDK in a **non-production** environment, or
+- Configure a **custom API URL** so events are routed through your own infrastructure and SDK telemetry is switched off:
+
+```javascript
+const client = await Elements('YOUR_API_KEY', {
+  development: {
+    customApiUrl: 'https://your-proxy.example.com'
+  }
+});
+```
+
+## Related Docs
+
+- [Error Handling](./error-handling.md)
+- [Client API](../api/client.md)
+- [Troubleshooting](./troubleshooting.md)

package/docs/v1/reference/troubleshooting.md

@@ -0,0 +1,135 @@
+# Troubleshooting
+
+Common setup issues and how to resolve them.
+
+## SDK Script Not Loading
+
+**Symptoms:** 404/CORS in Network tab, `window.LiquidCommerce.elements` is undefined.
+
+**Fixes:**
+- Verify the script URL and that the tag includes `data-liquid-commerce-elements`.
+- Check ad blockers; proxy the API if needed.
+- Confirm `data-env` is set correctly.
+
+## Web Components Error
+
+**Symptoms:** Console logs about Custom Elements or Shadow DOM.
+
+**Fix:** Add the Web Components polyfill before the SDK:
+
+```html
+<script src="https://cdn.jsdelivr.net/npm/@webcomponents/webcomponentsjs@2/webcomponents-bundle.js"></script>
+<script defer data-liquid-commerce-elements ...></script>
+```
+
+## Product Not Showing
+
+**Symptoms:** Empty container or error view.
+
+**Fixes:**
+- Confirm the container ID matches your HTML.
+- Verify the product identifier exists.
+- Check for errors in the console or network tab.
+
+## Cart Drawer Not Opening
+
+**Symptoms:** Add to cart works but cart stays closed.
+
+**Fixes:**
+- Ensure a cart button is configured or call `window.LiquidCommerce.elements.actions.cart.openCart()`.
+- Check for JavaScript errors in the console.
+
+## Checkout Issues
+
+**Symptoms:** Checkout fails to load or submit.
+
+**Fixes:**
+- Verify you are on a supported browser.
+- Look for `checkout_*_failed` events in the console.
+- Check for Stripe-related errors in the browser console.
+
+## Address/Availability Problems
+
+**Symptoms:** Products show unavailable or address prompts fail.
+
+**Fixes:**
+- Make sure the address is set and valid.
+- Listen for `lce:actions.address_failed` to surface errors.
+
+## SSR / Server-Side Rendering
+
+**Symptoms:** Console warning "This SDK is designed for the browser. Calls made during SSR return null."
+
+This is expected behavior. The SDK ships SSR stubs that are automatically resolved when bundled for Node.js (via the `node` export condition in `package.json`). There are two: the main build's stub (the `.` export) provides `Elements` and `ElementsBuilder` and warns with the `[LiquidCommerce Elements]` prefix; the checkout build's stub (the `./checkout` export) provides `ElementsCheckout` and warns with the `[LiquidCommerce Checkout]` prefix. Both re-export their types and enums for TypeScript compatibility and return `null` from the factory functions.
+
+**No action required** — initialize the SDK in a client-only lifecycle hook (`useEffect`, `onMounted`, etc.) and the real client will activate in the browser.
+
+## Styling Not Applied / CSS Not Working
+
+**Symptoms:** Components render but custom styles are ignored, or host page styles leak into components.
+
+**Cause:** Components use Shadow DOM for style isolation.
+
+**Fixes:**
+- Use `customTheme` in the client configuration to style components -- external CSS cannot penetrate Shadow DOM.
+- For debugging, enable `development.openShadowDom: true` to make the shadow root open (`mode: 'open'`) so you can inspect component internals in DevTools (via `element.shadowRoot`). This does **not** disable style isolation — external CSS still cannot reach the components; use `customTheme` to style them. (Forced off in production.)
+- Use the debug panel (`debugMode: 'panel'`) to inspect SDK logs, events, and GTM activity in real time — it surfaces a live stream of logger output and pubsub/GTM events (not component internal state), and auto-enables only in non-production environments.
+
+## Component Not Updating After Data Changes
+
+**Symptoms:** Component shows stale data after an action completes.
+
+**Fixes:**
+- Call `.rerender()` on the injected component to force a refresh:
+  ```javascript
+  const components = client.getInjectedComponents();
+  components.get('product-1')?.rerender();
+  ```
+- Ensure you're not holding a stale reference -- call `getInjectedComponents()` again after injection.
+
+## Cleanup / Memory Leaks
+
+**Symptoms:** Components persist after navigating away in SPA, or duplicate components appear.
+
+**Fixes:**
+- Call `destroy()` on individual injected components when removing them:
+  ```javascript
+  const component = client.getInjectedComponents().get('product-1');
+  component?.destroy();
+  ```
+- Call `client.destroy()` when tearing down the entire SDK (e.g., on SPA route change).
+
+## Promo Ticker Not Showing
+
+**Symptoms:** Promo ticker is configured but not visible.
+
+**Fixes:**
+- Verify all 5 required fields are set: `promoCode`, `text`, `separator`, `activeFrom`, `activeUntil`.
+- 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.
+
+## Ad Blockers Blocking SDK Requests
+
+**Symptoms:** Network requests fail, products don't load, but no code errors.
+
+**Fixes:**
+- Set up a proxy to route API requests through your own domain:
+  ```javascript
+  proxy: { baseUrl: 'https://yoursite.com/api/elements-proxy' }
+  ```
+- See [Proxy Setup Guide](../integration/proxy-setup.md) for server-side implementation.
+
+## Performance Issues on Large Product Lists
+
+**Symptoms:** Slow rendering or high memory usage with many products.
+
+**Fixes:**
+- Reduce `rows` and `columns` to load fewer products per page.
+- Limit the number of active filters.
+- Use the checkout-only build on checkout pages to reduce bundle size.
+
+## Related Docs
+
+- [Installation](../getting-started/installation.md)
+- [Browser Support](./browser-support.md)
+- [Error Handling](./error-handling.md)
+- [Proxy Setup](../integration/proxy-setup.md)