@liquidcommerce/elements-sdk 2.7.41 → 2.7.43

package/docs/v1/reference/analytics.md

@@ -52,7 +52,17 @@ The SDK detects an already-present partner/host GTM container rather than replac
 
 ### Google tag gateway
 
-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:
+[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', {
@@ -62,7 +72,9 @@ const client = await Elements('YOUR_API_KEY', {
 
 Or declaratively, on the script tag: `data-gtm-gateway-url="/metrics/"`.
 
-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`.
+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.
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "LiquidCommerce Elements SDK",
   "license": "UNLICENSED",
   "author": "LiquidCommerce Team",
-  "version": "2.7.41",
+  "version": "2.7.43",
   "homepage": "https://docs.liquidcommerce.co/elements-sdk",
   "repository": {
     "type": "git",
@@ -14,7 +14,7 @@
   },
   "module": "./dist/index.esm.js",
   "types": "./dist/types/index.d.ts",
-  "packageManager": "pnpm@11.24.0",
+  "packageManager": "pnpm@12.9.1",
   "exports": {
     ".": {
       "types": "./dist/types/index.d.ts",
@@ -109,7 +109,7 @@
     "theming"
   ],
   "devDependencies": {
-    "@biomejs/biome": "^2.5.14",
+    "@biomejs/biome": "^2.5.15",
     "@commitlint/cli": "^21.2.3",
     "@commitlint/config-conventional": "^21.2.3",
     "@playwright/test": "1.63.0",
@@ -126,18 +126,18 @@
     "@semantic-release/npm": "^13.2.0",
     "@semantic-release/release-notes-generator": "^14.1.1",
     "@types/core-js": "^2.5.8",
-    "@types/node": "^26.6.3",
+    "@types/node": "^26.6.4",
     "conventional-changelog": "8.1.3",
     "husky": "^9.1.7",
-    "jsdom": "30.1.1",
+    "jsdom": "30.1.2",
     "process": "^0.11.10",
-    "rollup": "^4.63.5",
+    "rollup": "^4.64.0",
     "rollup-obfuscator": "^4.1.1",
     "rollup-plugin-typescript2": "^0.37.0",
     "semantic-release": "^25.0.9",
     "ts-node": "^10.9.2",
     "typescript": "6.0.3",
-    "vitest": "5.0.2"
+    "vitest": "5.0.3"
   },
   "engines": {
     "node": ">=22"