@liquidcommerce/elements-sdk 2.7.39 → 2.7.41

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (29) hide show
  1. package/dist/index.checkout.esm.js +8000 -7917
  2. package/dist/index.esm.js +13136 -12942
  3. package/dist/ssr-stub.esm.js +1 -0
  4. package/dist/types/auto-initialize/shared-utils.d.ts +1 -0
  5. package/dist/types/core/client/client-config.service.d.ts +3 -1
  6. package/dist/types/core/google-tag-manager.service.d.ts +7 -0
  7. package/dist/types/enums/core.enum.d.ts +1 -0
  8. package/dist/types/interfaces/config.interface.d.ts +4 -0
  9. package/dist/types/interfaces/configs/product.interface.d.ts +2 -0
  10. package/dist/types/modules/checkout/components/checkout-prop65-warning.component.d.ts +1 -1
  11. package/dist/types/modules/product/components/index.d.ts +1 -0
  12. package/dist/types/modules/product/components/product-add-to-cart-section.component.d.ts +1 -0
  13. package/dist/types/modules/product/components/product-delivery-estimate.component.d.ts +11 -0
  14. package/dist/types/modules/product/components/product-retailers.component.d.ts +1 -0
  15. package/dist/types/modules/product-list/components/card-components/index.d.ts +1 -0
  16. package/dist/types/modules/product-list/components/card-components/product-fulfillment-text.d.ts +2 -0
  17. package/dist/types/modules/product-list/components/product-list-card.component.d.ts +2 -0
  18. package/dist/types/modules/product-list/components/product-list-product-pre-cart.component.d.ts +1 -0
  19. package/dist/types/modules/ui-components/engraving/engraving-form.component.d.ts +1 -0
  20. package/dist/types/ssr/stub.d.ts +1 -1
  21. package/dist/types/utils/product.d.ts +4 -1
  22. package/docs/v1/api/client.md +19 -0
  23. package/docs/v1/api/configuration.md +22 -0
  24. package/docs/v1/api/typescript-types.md +11 -0
  25. package/docs/v1/getting-started/installation.md +2 -0
  26. package/docs/v1/guides/checkout-component.md +4 -4
  27. package/docs/v1/guides/product-component.md +9 -0
  28. package/docs/v1/reference/analytics.md +15 -1
  29. package/package.json +7 -7
@@ -169,6 +169,7 @@ const COMPONENT_TYPE = {
169
169
  PRODUCT_RETAILERS_CAROUSEL: 'product-retailers-carousel',
170
170
  PRODUCT_RETAILERS_POPUP: 'product-retailers-popup',
171
171
  PRODUCT_RETAILERS_POPUP_LIST: 'product-retailers-popup-list',
172
+ PRODUCT_DELIVERY_ESTIMATE: 'product-delivery-estimate',
172
173
  PRODUCT_PRICE: 'product-price',
173
174
  PRODUCT_ADD_TO_CART_SECTION: 'product-add-to-cart-section',
174
175
  PRODUCT_DRAWER: 'product-drawer',
@@ -19,6 +19,7 @@ export declare const SHARED_ATTR: {
19
19
  readonly PROMO_CODE_PARAM: "data-promo-code-param";
20
20
  readonly CHECKOUT_PARAM: "data-checkout-param";
21
21
  readonly CHECKOUT_URL: "data-checkout-url";
22
+ readonly GTM_GATEWAY_URL: "data-gtm-gateway-url";
22
23
  };
23
24
  readonly ELEMENT: {
24
25
  readonly CHECKOUT: "data-lce-checkout";
@@ -1,5 +1,5 @@
1
1
  import { type DebugMode, type ElementsEnv } from '@/enums';
2
- import type { IClientCustomThemeConfig, IElementsProxyConfig, ILiquidCommerceElementsCheckoutConfig } from '@/interfaces/config.interface';
2
+ import type { IClientCustomThemeConfig, IElementsGTMConfig, IElementsProxyConfig, ILiquidCommerceElementsCheckoutConfig } from '@/interfaces/config.interface';
3
3
  import type { IPromoTicker } from '@/interfaces/configs';
4
4
  export type DeviceType = 'desktop' | 'tablet' | 'mobile';
5
5
  export interface IClientConfigs {
@@ -12,6 +12,7 @@ export interface IClientConfigs {
12
12
  partnerName?: string;
13
13
  customTheme: IClientCustomThemeConfig | null;
14
14
  proxy: IElementsProxyConfig | null;
15
+ gtm: IElementsGTMConfig | null;
15
16
  deviceType: DeviceType;
16
17
  userDeviceId?: string;
17
18
  localStorageKeyPrefix?: string;
@@ -31,6 +32,7 @@ export interface IClientConfigInput {
31
32
  debugMode?: DebugMode;
32
33
  customTheme?: IClientCustomThemeConfig;
33
34
  proxy?: IElementsProxyConfig;
35
+ gtm?: IElementsGTMConfig;
34
36
  promoTicker?: IPromoTicker[];
35
37
  development?: {
36
38
  customApiUrl?: string;
@@ -51,6 +51,7 @@ export declare class GoogleTagManagerService {
51
51
  private partnerName?;
52
52
  private partnerCode?;
53
53
  private partnerGTMId?;
54
+ private partnerGatewayUrl?;
54
55
  private liquidCommerceGTMId?;
55
56
  private enablePartnerGTM;
56
57
  private enableLiquidCommerceGTM;
@@ -67,6 +68,12 @@ export declare class GoogleTagManagerService {
67
68
  private waitForDOMReady;
68
69
  private isGTMAlreadyLoaded;
69
70
  private isContainerLoaded;
71
+ private isGatewayScriptForContainer;
72
+ private getPartnerGatewayScripts;
73
+ private parseScriptUrl;
74
+ private resolveGatewayUrl;
75
+ private getContainerRegistry;
76
+ private isContainerRegistered;
70
77
  private isContainerInitialized;
71
78
  private loadGTMScript;
72
79
  private waitForContainerInit;
@@ -88,6 +88,7 @@ export declare const COMPONENT_TYPE: {
88
88
  readonly PRODUCT_RETAILERS_CAROUSEL: "product-retailers-carousel";
89
89
  readonly PRODUCT_RETAILERS_POPUP: "product-retailers-popup";
90
90
  readonly PRODUCT_RETAILERS_POPUP_LIST: "product-retailers-popup-list";
91
+ readonly PRODUCT_DELIVERY_ESTIMATE: "product-delivery-estimate";
91
92
  readonly PRODUCT_PRICE: "product-price";
92
93
  readonly PRODUCT_ADD_TO_CART_SECTION: "product-add-to-cart-section";
93
94
  readonly PRODUCT_DRAWER: "product-drawer";
@@ -7,6 +7,9 @@ export interface IElementsProxyConfig {
7
7
  baseUrl: string;
8
8
  headers?: Record<string, string>;
9
9
  }
10
+ export interface IElementsGTMConfig {
11
+ gatewayUrl?: string;
12
+ }
10
13
  export interface ILiquidCommerceElementsDevelopmentConfig {
11
14
  customApiUrl?: string;
12
15
  openShadowDom?: boolean;
@@ -30,6 +33,7 @@ export interface ILiquidCommerceElementsBaseConfig {
30
33
  debugMode?: DebugMode;
31
34
  checkout?: ILiquidCommerceElementsCheckoutConfig;
32
35
  proxy?: IElementsProxyConfig;
36
+ gtm?: IElementsGTMConfig;
33
37
  development?: ILiquidCommerceElementsDevelopmentConfig;
34
38
  }
35
39
  export interface ILiquidCommerceElementsBuilderConfig extends ILiquidCommerceElementsBaseConfig {
@@ -15,6 +15,8 @@ export interface IProductLayout {
15
15
  enableShippingFulfillment: boolean;
16
16
  enableOnDemandFulfillment: boolean;
17
17
  primaryFulfillmentMethod: FulfillmentType;
18
+ showOnlyOneRetailer: boolean;
19
+ hideRetailerName: boolean;
18
20
  addToCartButtonText: string;
19
21
  addToCartButtonShowTotalPrice: boolean;
20
22
  buyNowButtonText: string;
@@ -4,5 +4,5 @@ export declare class CheckoutProp65WarningComponent extends BaseComponent<null,
4
4
  constructor();
5
5
  get hostClasses(): string[];
6
6
  private colorMode;
7
- protected template(): HTMLElement;
7
+ protected template(): HTMLElement | HTMLElement[];
8
8
  }
@@ -1,5 +1,6 @@
1
1
  export * from './components';
2
2
  export * from './product-add-to-cart-section.component';
3
+ export * from './product-delivery-estimate.component';
3
4
  export * from './product-description.component';
4
5
  export * from './product-drawer.component';
5
6
  export * from './product-image-carousel.component';
@@ -17,6 +17,7 @@ export declare class ProductAddToCartSectionComponent extends BaseComponent<IAdd
17
17
  afterRender(): void;
18
18
  private getAvailableQuantity;
19
19
  private isFulfillmentClosed;
20
+ private isRequiredEngravingUnavailable;
20
21
  private isButtonLoading;
21
22
  private calculateQuantityLimits;
22
23
  private handleAddToCart;
@@ -0,0 +1,11 @@
1
+ import { BaseComponent } from '@/core/base-component.service';
2
+ import type { IProductComponent } from '@/interfaces/configs';
3
+ export interface IProductDeliveryEstimateComponentParams {
4
+ productId: string;
5
+ }
6
+ export declare class ProductDeliveryEstimateComponent extends BaseComponent<IProductDeliveryEstimateComponentParams, IProductComponent> {
7
+ get hostClasses(): string[];
8
+ constructor();
9
+ private getProductId;
10
+ protected template(): HTMLElement[];
11
+ }
@@ -8,5 +8,6 @@ export declare class ProductRetailersComponent extends BaseComponent<IProductRet
8
8
  constructor();
9
9
  get hostAttributes(): Record<string, string>;
10
10
  private getProductId;
11
+ private retailersDisplayType;
11
12
  protected template(): HTMLElement | HTMLElement[];
12
13
  }
@@ -1,5 +1,6 @@
1
1
  export * from './product-badge';
2
2
  export * from './product-button';
3
+ export * from './product-fulfillment-text';
3
4
  export * from './product-price-and-personalization';
4
5
  export * from './product-quantity-selector';
5
6
  export * from './product-sizes-list';
@@ -0,0 +1,2 @@
1
+ import type { IPLProductStore } from '@/core/store/interfaces/product-list.interface';
2
+ export declare function productFulfillmentText(product: IPLProductStore, retailerNameHidden: boolean): string;
@@ -28,6 +28,8 @@ export declare class ProductListCardComponent extends BaseComponent<IProductList
28
28
  protected afterRender(): void;
29
29
  private updatePriceDisplay;
30
30
  private updateFulfillmentText;
31
+ private isRetailerNameHidden;
32
+ private showsDeliveryOptions;
31
33
  private updateImage;
32
34
  private updatePersonalizeVisibility;
33
35
  private updateAddToCartButton;
@@ -29,6 +29,7 @@ export declare class ProductListProductPreCartComponent extends BaseComponent<IP
29
29
  onStoreWatch(changes: IOnStoreChanged[]): void;
30
30
  private updatePriceDisplay;
31
31
  private updateFulfillmentText;
32
+ private isRetailerNameHidden;
32
33
  private updateImage;
33
34
  private updatePersonalizeVisibility;
34
35
  private updateAddToCartButton;
@@ -21,6 +21,7 @@ export declare class EngravingFormComponent extends BaseComponent<IEngravingForm
21
21
  private partNumber;
22
22
  private isPresale;
23
23
  beforeConnected(): void;
24
+ private canSubmit;
24
25
  private calculateTotalPrice;
25
26
  private productInformationSection;
26
27
  private addToCartButtonText;
@@ -3,7 +3,7 @@ export type { CartEventLevel, CartEventType, CheckoutEventLevel, CheckoutEventTy
3
3
  export { CART_EVENT_LEVEL, CART_EVENT_TYPE, CHECKOUT_EVENT_LEVEL, CHECKOUT_EVENT_TYPE, COMPONENT_TYPE, DEBUG_MODE, DISPLAY_MODE, ELEMENTS_ACTIONS_EVENT, ELEMENTS_ENV, ELEMENTS_FORM, FULFILLMENT_TYPE, NAVIGATION_SOURCE, } from '../enums/core.enum';
4
4
  export type { ILiquidCommerceElementsActions, ILiquidCommerceElementsBuilderClient, ILiquidCommerceElementsClient, } from '../interfaces/client.interface';
5
5
  export type { IInjectedComponent } from '../interfaces/component.interface';
6
- export type { IElementsProxyConfig, ILiquidCommerceElementsBuilderConfig, ILiquidCommerceElementsCheckoutConfig, ILiquidCommerceElementsConfig, ILiquidCommerceElementsDevelopmentConfig, } from '../interfaces/config.interface';
6
+ export type { IElementsGTMConfig, IElementsProxyConfig, ILiquidCommerceElementsBuilderConfig, ILiquidCommerceElementsCheckoutConfig, ILiquidCommerceElementsConfig, ILiquidCommerceElementsDevelopmentConfig, } from '../interfaces/config.interface';
7
7
  export type * from '../interfaces/configs';
8
8
  export type { IBuilderInjectElementParams, IInjectCheckoutBuilderParams, IInjectCheckoutParams, IInjectProductElement, IInjectProductListFiltersParams, IInjectProductListParams, IInjectProductListSearchParams, ProductListFilterType, } from '../interfaces/injection.interface';
9
9
  export declare function Elements(..._args: any[]): Promise<null>;
@@ -1,7 +1,10 @@
1
- import type { IProductStore } from '@/core/store/interfaces/product.interface';
1
+ import type { IProductFulfillmentStore, IProductSizeStore, IProductStore } from '@/core/store/interfaces/product.interface';
2
2
  import type { IPLProductStore } from '@/core/store/interfaces/product-list.interface';
3
3
  import { type FulfillmentType } from '@/enums';
4
4
  import type { IProduct, IProductAvailabilityResponse } from '@/interfaces/api/product.interface';
5
+ import type { IProductLayout } from '@/interfaces/configs';
6
+ export declare function engravingFulfillmentFor(size: Pick<IProductSizeStore, 'shippingFulfillments'> | undefined, selectedFulfillmentId: string | null | undefined): IProductFulfillmentStore | null;
7
+ export declare function isRetailerNameHidden(layout: Pick<IProductLayout, 'showOnlyOneRetailer' | 'hideRetailerName'> | undefined): boolean;
5
8
  export interface IPrepareApiProductForStoreParams {
6
9
  context: 'product-list' | 'product-page';
7
10
  product: IProduct;
@@ -108,6 +108,7 @@ interface ILiquidCommerceElementsConfig {
108
108
  customTheme?: IClientCustomThemeConfig;
109
109
  promoTicker?: IPromoTicker[];
110
110
  proxy?: IElementsProxyConfig;
111
+ gtm?: IElementsGTMConfig;
111
112
  checkout?: ILiquidCommerceElementsCheckoutConfig;
112
113
  development?: ILiquidCommerceElementsDevelopmentConfig;
113
114
  }
@@ -192,6 +193,24 @@ proxy: {
192
193
 
193
194
  See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation.
194
195
 
196
+ #### GTM Configuration
197
+
198
+ ```typescript
199
+ interface IElementsGTMConfig {
200
+ gatewayUrl?: string;
201
+ }
202
+ ```
203
+
204
+ **Example:**
205
+
206
+ ```javascript
207
+ gtm: {
208
+ gatewayUrl: 'https://www.yoursite.com/metrics/'
209
+ }
210
+ ```
211
+
212
+ Set this when your site serves its own GTM container through Google tag gateway. See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway).
213
+
195
214
  #### Checkout Configuration
196
215
 
197
216
  ```typescript
@@ -16,6 +16,7 @@ interface ILiquidCommerceElementsConfig {
16
16
  debugMode?: DebugMode;
17
17
  checkout?: ILiquidCommerceElementsCheckoutConfig;
18
18
  proxy?: IElementsProxyConfig;
19
+ gtm?: IElementsGTMConfig;
19
20
  development?: ILiquidCommerceElementsDevelopmentConfig;
20
21
  }
21
22
  ```
@@ -28,6 +29,7 @@ interface ILiquidCommerceElementsConfig {
28
29
  | `debugMode` | `'none' \| 'console' \| 'panel'` | No | Debug output mode |
29
30
  | `checkout` | `ILiquidCommerceElementsCheckoutConfig` | No | Checkout behavior settings |
30
31
  | `proxy` | `IElementsProxyConfig` | No | Proxy configuration for API requests |
32
+ | `gtm` | `IElementsGTMConfig` | No | Google tag gateway URL of your own GTM container |
31
33
  | `development` | `ILiquidCommerceElementsDevelopmentConfig` | No | Development/testing options |
32
34
 
33
35
  > **Note:** `debugMode` (`'console'` or `'panel'`) is **ignored in production** -- it is forced off when `env` is `'production'`. It only takes effect outside production (`'staging'`).
@@ -202,6 +204,8 @@ interface IProductLayout {
202
204
  enableShippingFulfillment: boolean;
203
205
  enableOnDemandFulfillment: boolean;
204
206
  primaryFulfillmentMethod: 'shipping' | 'onDemand';
207
+ showOnlyOneRetailer: boolean;
208
+ hideRetailerName: boolean;
205
209
  addToCartButtonText: string;
206
210
  addToCartButtonShowTotalPrice: boolean;
207
211
  buyNowButtonText: string;
@@ -225,6 +229,8 @@ interface IProductLayout {
225
229
  | `enableShippingFulfillment` | `boolean` | Enable shipping fulfillment option |
226
230
  | `enableOnDemandFulfillment` | `boolean` | Enable on-demand delivery option |
227
231
  | `primaryFulfillmentMethod` | `'shipping' \| 'onDemand'` | Fulfillment method shown first and selected by default; falls back to the other enabled method when it has no availability |
232
+ | `showOnlyOneRetailer` | `boolean` | Admin setting. Availability is narrowed server-side to one shipping and one on-demand retailer per product |
233
+ | `hideRetailerName` | `boolean` | Admin setting, honoured only with `showOnlyOneRetailer`. Availability is narrowed to one retailer and one delivery method per size, and the product component and product list show only its delivery estimate (e.g. "Ships in 2-3 days") instead of the retailer choice. Cart and checkout still show the retailer |
228
234
  | `addToCartButtonText` | `string` | Custom text for add-to-cart button |
229
235
  | `addToCartButtonShowTotalPrice` | `boolean` | Show total price on add-to-cart button |
230
236
  | `buyNowButtonText` | `string` | Custom text for buy-now button |
@@ -530,6 +536,22 @@ See [Proxy Setup Guide](../integration/proxy-setup.md) for implementation detail
530
536
 
531
537
  ---
532
538
 
539
+ ## GTM Configuration
540
+
541
+ ### IElementsGTMConfig
542
+
543
+ ```typescript
544
+ interface IElementsGTMConfig {
545
+ gatewayUrl?: string;
546
+ }
547
+ ```
548
+
549
+ If your site loads its own GTM container through Google tag gateway for advertisers, set `gatewayUrl` to that first-party path (e.g. `'https://www.yoursite.com/metrics/'` or `'/metrics/'`) so the SDK recognizes the container instead of treating the page as having none. Declarative equivalent: `data-gtm-gateway-url`. An empty or non-string value drops the whole `gtm` config with a console warning.
550
+
551
+ See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway).
552
+
553
+ ---
554
+
533
555
  ## Development Configuration
534
556
 
535
557
  ### ILiquidCommerceElementsDevelopmentConfig
@@ -99,6 +99,7 @@ interface ILiquidCommerceElementsConfig {
99
99
  debugMode?: DebugMode;
100
100
  checkout?: ILiquidCommerceElementsCheckoutConfig;
101
101
  proxy?: IElementsProxyConfig;
102
+ gtm?: IElementsGTMConfig;
102
103
  development?: ILiquidCommerceElementsDevelopmentConfig;
103
104
  }
104
105
  ```
@@ -133,6 +134,16 @@ interface IElementsProxyConfig {
133
134
  }
134
135
  ```
135
136
 
137
+ ### IElementsGTMConfig
138
+
139
+ ```typescript
140
+ interface IElementsGTMConfig {
141
+ gatewayUrl?: string;
142
+ }
143
+ ```
144
+
145
+ `gatewayUrl` is the Google tag gateway path your own GTM container is served from (see [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway)).
146
+
136
147
  ### ILiquidCommerceElementsDevelopmentConfig
137
148
 
138
149
  ```typescript
@@ -47,6 +47,7 @@ The path segment selects which bundle is served:
47
47
  | `data-liquid-commerce-elements` | Yes | Identifies this as the Elements SDK script |
48
48
  | `data-token` | Yes | Your LiquidCommerce API key |
49
49
  | `data-env` | No | Environment: `staging` or `production`. Defaults to `production` if omitted. |
50
+ | `data-gtm-gateway-url` | No | Google tag gateway path your own GTM container is served from (e.g. `/metrics/`). See [Analytics → Google tag gateway](../reference/analytics.md#google-tag-gateway). |
50
51
  | `defer` | Recommended | Allows non-blocking script loading |
51
52
 
52
53
  ### Where to Place the Script
@@ -269,6 +270,7 @@ const client = await Elements('YOUR_API_KEY', {
269
270
  customTheme: { /* ... */ }, // Optional: Theme customization
270
271
  promoTicker: [ /* ... */ ], // Optional: Promo ticker configuration
271
272
  proxy: { /* ... */ }, // Optional: Proxy configuration
273
+ gtm: { /* ... */ }, // Optional: Google tag gateway URL of your own GTM container
272
274
  checkout: { /* ... */ }, // Optional: Checkout configuration
273
275
  development: { /* ... */ } // Optional: Development/testing options
274
276
  });
@@ -454,16 +454,16 @@ window.addEventListener('lce:actions.checkout_product_add_failed', (event) => {
454
454
 
455
455
  ## California Proposition 65 Warning
456
456
 
457
- The order summary shows a panel directly above the place-order button reading **Adult signature
458
- (21+) required at delivery.** When the shipping address is in California, the panel adds
457
+ When the shipping address is in California, the order summary shows a panel directly above the
458
+ place-order button reading **Adult signature (21+) required at delivery.** followed by
459
459
  **CA WARNING · California Proposition 65 information for these products**, so the warning is
460
460
  presented before the purchase completes. The text links to the OEHHA alcohol page,
461
461
  [www.P65Warnings.ca.gov/alcohol](https://www.p65warnings.ca.gov/alcohol), in a new tab. The full
462
462
  27 CCR § 25607.4 text is on the product element.
463
463
 
464
464
  The panel appears in the drawer checkout, the hosted checkout and the checkout-only build. The
465
- adult-signature notice is always shown; the Prop 65 line follows the shipping address's state and
466
- updates when the address changes. Neither can be turned off or reworded by configuration. Its colours follow `global.layout.poweredByMode` — the same
465
+ whole panel, adult-signature notice included, is shown only for a California shipping address; it
466
+ appears or disappears when the address changes, and nothing renders in its place otherwise. Neither can be turned off or reworded by configuration. Its colours follow `global.layout.poweredByMode` — the same
467
467
  light/dark switch the Stripe payment form uses — as a fixed pair so the copy is always legible:
468
468
  `light` is `#18181B` on `#F5F3EE`, `dark` is `#F5F3EE` on `#2A2824`. The font and corner radius come
469
469
  from your theme. If your checkout is dark, set `poweredByMode: 'dark'`.
@@ -211,6 +211,15 @@ For products with multiple retailers:
211
211
  - Opens a plain, scrollable list of the available delivery/retailer options
212
212
  - No filtering or search — select a retailer from the list to choose it
213
213
 
214
+ **Delivery Estimate Only**
215
+ - Used when the `showOnlyOneRetailer` and `hideRetailerName` admin settings are both on
216
+ - Each size arrives with a single retailer and a single delivery method, so there is nothing to choose
217
+ - Shows only the delivery estimate, e.g. "Ships in 2-3 days" or "Arrives in 60 minutes", and never the retailer name; the engraving form does the same
218
+ - Product list cards and their pre-cart follow the same settings: the "Ships from" line shows the estimate instead, and the "Delivery Options" button is not shown
219
+ - The retailer is still shown in the cart and checkout
220
+
221
+ Both settings are made in the LiquidCommerce admin, because the narrowing happens in the availability response. Setting them through `customTheme` changes the display only: the shopper would see one estimate while the store still holds every retailer.
222
+
214
223
  ### Personalization/Engraving
215
224
 
216
225
  For products that support personalization:
@@ -48,7 +48,21 @@ Events fired before GTM finishes initializing are queued (up to 100, oldest drop
48
48
 
49
49
  ## Coexisting With Your Own GTM
50
50
 
51
- 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.
51
+ 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.
52
+
53
+ ### Google tag gateway
54
+
55
+ If your site loads its own GTM container first-party through [Google tag gateway for advertisers](https://developers.google.com/tag-platform/tag-manager/gateway/get-started) (e.g. `https://www.yoursite.com/metrics/` instead of `https://www.googletagmanager.com/gtm.js?id=GTM-XXXX`), tell the SDK where that path is so it recognizes your container:
56
+
57
+ ```javascript
58
+ const client = await Elements('YOUR_API_KEY', {
59
+ gtm: { gatewayUrl: 'https://www.yoursite.com/metrics/' }, // or '/metrics/'
60
+ });
61
+ ```
62
+
63
+ Or declaratively, on the script tag: `data-gtm-gateway-url="/metrics/"`.
64
+
65
+ A gateway script URL usually carries no container ID, so without this setting the SDK cannot match the script tag to your partner container. 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. The setting affects detection only — the SDK never loads your container, and the LiquidCommerce container still loads from `googletagmanager.com`.
52
66
 
53
67
  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.
54
68
 
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.7.39",
6
+ "version": "2.7.41",
7
7
  "homepage": "https://docs.liquidcommerce.co/elements-sdk",
8
8
  "repository": {
9
9
  "type": "git",
@@ -122,22 +122,22 @@
122
122
  "@semantic-release/changelog": "^7.0.0",
123
123
  "@semantic-release/commit-analyzer": "^13.0.1",
124
124
  "@semantic-release/git": "^11.0.1",
125
- "@semantic-release/github": "^12.0.9",
126
- "@semantic-release/npm": "^13.1.5",
125
+ "@semantic-release/github": "^12.0.10",
126
+ "@semantic-release/npm": "^13.2.0",
127
127
  "@semantic-release/release-notes-generator": "^14.1.1",
128
128
  "@types/core-js": "^2.5.8",
129
- "@types/node": "^26.6.2",
129
+ "@types/node": "^26.6.3",
130
130
  "conventional-changelog": "8.1.3",
131
131
  "husky": "^9.1.7",
132
- "jsdom": "30.1.0",
132
+ "jsdom": "30.1.1",
133
133
  "process": "^0.11.10",
134
- "rollup": "^4.63.4",
134
+ "rollup": "^4.63.5",
135
135
  "rollup-obfuscator": "^4.1.1",
136
136
  "rollup-plugin-typescript2": "^0.37.0",
137
137
  "semantic-release": "^25.0.9",
138
138
  "ts-node": "^10.9.2",
139
139
  "typescript": "6.0.3",
140
- "vitest": "5.0.1"
140
+ "vitest": "5.0.2"
141
141
  },
142
142
  "engines": {
143
143
  "node": ">=22"