@cartbase/storefront 0.19.0 → 0.20.1

package/src/tracking/ga4.tsx

@@ -1,93 +1,93 @@
-"use client"
-
-import Script from "next/script"
-
-import { jsStringLiteral, urlParam } from "./inline-script"
-
-/**
- * GoogleTag — THE single Google tag for a storefront.
- *
- * Loads `https://www.googletagmanager.com/gtag/js` once and issues one
- * `config` per destination: GA4 for analytics, Google Ads for conversions
- * and remarketing audiences.
- *
- * ONE loader, TWO configs, and that is Google's own instruction: when a
- * page already carries a Google tag you add the Ads conversion ID with an
- * additional `config` command, never a second `<script src>`
- * (https://support.google.com/google-ads/answer/2476688). Every agency
- * onboarding email pastes a second loader anyway, contradicting the line
- * printed above it in the same email. Take the instruction, not the
- * snippet.
- *
- * The Ads `config` is also what powers Google Ads remarketing audiences.
- * It is not optional for an account that intends to retarget, and linking
- * GA4 to Ads does not substitute for it.
- *
- * Consent needs nothing here: <ConsentInit> sets the Consent Mode v2
- * defaults synchronously ahead of this loader, and because the Ads
- * destination rides the same gtag instance, `ad_storage` /
- * `ad_user_data` / `ad_personalization` gate it with no extra wiring.
- * That is the direct payoff of refusing the second script tag.
- *
- * Renders nothing when neither id is configured, so a layout can mount it
- * unconditionally.
- *
- * `send_page_view` stays at its default, so the initial page_view fires
- * on load. SPA route changes are NOT auto-tracked by gtag; a storefront
- * that wants per-route page_views calls `gtag('event', 'page_view', …)`
- * from a route-change effect. Take care doing that: a `router.replace`
- * that only rewrites a query parameter reads as a navigation to gtag, to
- * the Meta pixel and to TikTok alike, and every vendor then counts two
- * views of one page.
- */
-export function GoogleTag({
-  measurementId,
-  adsConversionId,
-}: {
-  /** GA4 destination, e.g. "G-8BLJ6CW7VX". */
-  measurementId?: string
-  /** Google Ads destination, e.g. "AW-18150814603". */
-  adsConversionId?: string
-}) {
-  const destinations = [measurementId, adsConversionId].filter(
-    (id): id is string => Boolean(id && id.trim())
-  )
-  if (destinations.length === 0) return null
-
-  // Which id lands in the loader URL is cosmetic — gtag treats every
-  // `config` equally once loaded. GA4 leads when present so the URL stays
-  // what it has always been for stores that only run analytics.
-  const loaderId = destinations[0]
-
-  const initSnippet = `
-window.dataLayer = window.dataLayer || [];
-function gtag(){dataLayer.push(arguments);}
-gtag('js', new Date());
-${destinations.map((id) => `gtag('config', ${jsStringLiteral(id)});`).join("\n")}
-`.trim()
-
-  return (
-    <>
-      <Script
-        id="google-tag-loader"
-        strategy="afterInteractive"
-        src={`https://www.googletagmanager.com/gtag/js?id=${urlParam(loaderId)}`}
-      />
-      <Script
-        id="google-tag-init"
-        strategy="afterInteractive"
-        dangerouslySetInnerHTML={{ __html: initSnippet }}
-      />
-    </>
-  )
-}
-
-/**
- * GA4 — the analytics-only door, kept because storefronts mount it by
- * this name. It is <GoogleTag> with one destination; a store that also
- * runs Google Ads should mount <GoogleTag> with both ids instead, since
- * two loaders on one page is the thing Google tells you not to do.
- */
-export function GA4({ measurementId }: { measurementId?: string }) {
-  return <GoogleTag measurementId={measurementId} />
-}
+"use client"
+
+import Script from "next/script"
+
+import { jsStringLiteral, urlParam } from "./inline-script"
+
+/**
+ * GoogleTag — THE single Google tag for a storefront.
+ *
+ * Loads `https://www.googletagmanager.com/gtag/js` once and issues one
+ * `config` per destination: GA4 for analytics, Google Ads for conversions
+ * and remarketing audiences.
+ *
+ * ONE loader, TWO configs, and that is Google's own instruction: when a
+ * page already carries a Google tag you add the Ads conversion ID with an
+ * additional `config` command, never a second `<script src>`
+ * (https://support.google.com/google-ads/answer/2476688). Every agency
+ * onboarding email pastes a second loader anyway, contradicting the line
+ * printed above it in the same email. Take the instruction, not the
+ * snippet.
+ *
+ * The Ads `config` is also what powers Google Ads remarketing audiences.
+ * It is not optional for an account that intends to retarget, and linking
+ * GA4 to Ads does not substitute for it.
+ *
+ * Consent needs nothing here: <ConsentInit> sets the Consent Mode v2
+ * defaults synchronously ahead of this loader, and because the Ads
+ * destination rides the same gtag instance, `ad_storage` /
+ * `ad_user_data` / `ad_personalization` gate it with no extra wiring.
+ * That is the direct payoff of refusing the second script tag.
+ *
+ * Renders nothing when neither id is configured, so a layout can mount it
+ * unconditionally.
+ *
+ * `send_page_view` stays at its default, so the initial page_view fires
+ * on load. SPA route changes are NOT auto-tracked by gtag; a storefront
+ * that wants per-route page_views calls `gtag('event', 'page_view', …)`
+ * from a route-change effect. Take care doing that: a `router.replace`
+ * that only rewrites a query parameter reads as a navigation to gtag, to
+ * the Meta pixel and to TikTok alike, and every vendor then counts two
+ * views of one page.
+ */
+export function GoogleTag({
+  measurementId,
+  adsConversionId,
+}: {
+  /** GA4 destination, e.g. "G-8BLJ6CW7VX". */
+  measurementId?: string
+  /** Google Ads destination, e.g. "AW-18150814603". */
+  adsConversionId?: string
+}) {
+  const destinations = [measurementId, adsConversionId].filter(
+    (id): id is string => Boolean(id && id.trim())
+  )
+  if (destinations.length === 0) return null
+
+  // Which id lands in the loader URL is cosmetic — gtag treats every
+  // `config` equally once loaded. GA4 leads when present so the URL stays
+  // what it has always been for stores that only run analytics.
+  const loaderId = destinations[0]
+
+  const initSnippet = `
+window.dataLayer = window.dataLayer || [];
+function gtag(){dataLayer.push(arguments);}
+gtag('js', new Date());
+${destinations.map((id) => `gtag('config', ${jsStringLiteral(id)});`).join("\n")}
+`.trim()
+
+  return (
+    <>
+      <Script
+        id="google-tag-loader"
+        strategy="afterInteractive"
+        src={`https://www.googletagmanager.com/gtag/js?id=${urlParam(loaderId)}`}
+      />
+      <Script
+        id="google-tag-init"
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{ __html: initSnippet }}
+      />
+    </>
+  )
+}
+
+/**
+ * GA4 — the analytics-only door, kept because storefronts mount it by
+ * this name. It is <GoogleTag> with one destination; a store that also
+ * runs Google Ads should mount <GoogleTag> with both ids instead, since
+ * two loaders on one page is the thing Google tells you not to do.
+ */
+export function GA4({ measurementId }: { measurementId?: string }) {
+  return <GoogleTag measurementId={measurementId} />
+}

package/src/tracking/google-ads.ts

@@ -1,84 +1,84 @@
-"use client"
-
-import type { TrackingConfig } from "./types"
-
-/**
- * Google Ads conversion tracking — browser side.
- *
- * Rides the SAME gtag instance <GoogleTag> loads for GA4; there is
- * deliberately no loader in this file (see the comment block in ./ga4.tsx
- * and https://support.google.com/google-ads/answer/2476688).
- *
- * DEDUP, and it is the whole reason this file is careful. Google Ads
- * collapses two conversions that share a conversion action AND a
- * `transaction_id` (https://support.google.com/google-ads/answer/6386790).
- * Every vendor snippet ships `'transaction_id': ''`, and an empty value
- * dedupes nothing — so every re-open of the confirmation page counts
- * another purchase. That is not a hypothetical: order emails link back to
- * the confirmation page, so the page is re-opened days after the sale, by
- * the same buyer, routinely. We always send `String(order.display_id)`,
- * the same key GA4's Measurement Protocol already uses.
- *
- * No-ops when gtag is absent (Ads not configured, server render, blocked
- * script), so callers need no guards.
- */
-
-type GtagFn = (...args: unknown[]) => void
-
-function safeGtag(): GtagFn | null {
-  if (typeof window === "undefined") return null
-  const fn = (window as unknown as { gtag?: GtagFn }).gtag
-  return typeof fn === "function" ? fn : null
-}
-
-/**
- * Build the `send_to` Google Ads expects for the purchase conversion:
- * "AW-XXXXXXXXXX/Label".
- *
- * Returns null when either half is missing, so callers skip the
- * conversion entirely instead of firing a malformed `send_to` that Google
- * accepts and silently drops. The label is genuinely optional in the
- * admin: a merchant can save the account id before creating the
- * conversion action.
- */
-export function googleAdsPurchaseSendTo(config: TrackingConfig): string | null {
-  const conversionId = config.googleAds?.conversionId?.trim()
-  const label = config.googleAds?.conversionLabel?.trim()
-  if (!conversionId || !label) return null
-  return `${conversionId}/${label}`
-}
-
-export type GoogleAdsPurchaseInput = {
-  /** Full send_to value from `googleAdsPurchaseSendTo`. */
-  sendTo: string
-  /** Order total actually collected, in `currency`. */
-  value: number
-  /** ISO 4217, e.g. "EUR". */
-  currency: string
-  /** THE dedup key. Always `String(order.display_id)`. */
-  transactionId: string
-  /**
-   * Whether this order is the buyer's first. Computed once server-side by
-   * the order.placed forwarder and persisted on the order, so the browser
-   * and the server cannot disagree. Omitted entirely when unknown: a
-   * wrong value is worse than an absent one for new-customer bidding.
-   */
-  newCustomer?: boolean
-}
-
-export function trackGoogleAdsPurchase(input: GoogleAdsPurchaseInput): void {
-  const gtag = safeGtag()
-  if (!gtag || !input.sendTo) return
-
-  const payload: Record<string, unknown> = {
-    send_to: input.sendTo,
-    value: input.value,
-    currency: input.currency,
-    transaction_id: input.transactionId,
-  }
-  if (typeof input.newCustomer === "boolean") {
-    payload.new_customer = input.newCustomer
-  }
-
-  gtag("event", "conversion", payload)
-}
+"use client"
+
+import type { TrackingConfig } from "./types"
+
+/**
+ * Google Ads conversion tracking — browser side.
+ *
+ * Rides the SAME gtag instance <GoogleTag> loads for GA4; there is
+ * deliberately no loader in this file (see the comment block in ./ga4.tsx
+ * and https://support.google.com/google-ads/answer/2476688).
+ *
+ * DEDUP, and it is the whole reason this file is careful. Google Ads
+ * collapses two conversions that share a conversion action AND a
+ * `transaction_id` (https://support.google.com/google-ads/answer/6386790).
+ * Every vendor snippet ships `'transaction_id': ''`, and an empty value
+ * dedupes nothing — so every re-open of the confirmation page counts
+ * another purchase. That is not a hypothetical: order emails link back to
+ * the confirmation page, so the page is re-opened days after the sale, by
+ * the same buyer, routinely. We always send `String(order.display_id)`,
+ * the same key GA4's Measurement Protocol already uses.
+ *
+ * No-ops when gtag is absent (Ads not configured, server render, blocked
+ * script), so callers need no guards.
+ */
+
+type GtagFn = (...args: unknown[]) => void
+
+function safeGtag(): GtagFn | null {
+  if (typeof window === "undefined") return null
+  const fn = (window as unknown as { gtag?: GtagFn }).gtag
+  return typeof fn === "function" ? fn : null
+}
+
+/**
+ * Build the `send_to` Google Ads expects for the purchase conversion:
+ * "AW-XXXXXXXXXX/Label".
+ *
+ * Returns null when either half is missing, so callers skip the
+ * conversion entirely instead of firing a malformed `send_to` that Google
+ * accepts and silently drops. The label is genuinely optional in the
+ * admin: a merchant can save the account id before creating the
+ * conversion action.
+ */
+export function googleAdsPurchaseSendTo(config: TrackingConfig): string | null {
+  const conversionId = config.googleAds?.conversionId?.trim()
+  const label = config.googleAds?.conversionLabel?.trim()
+  if (!conversionId || !label) return null
+  return `${conversionId}/${label}`
+}
+
+export type GoogleAdsPurchaseInput = {
+  /** Full send_to value from `googleAdsPurchaseSendTo`. */
+  sendTo: string
+  /** Order total actually collected, in `currency`. */
+  value: number
+  /** ISO 4217, e.g. "EUR". */
+  currency: string
+  /** THE dedup key. Always `String(order.display_id)`. */
+  transactionId: string
+  /**
+   * Whether this order is the buyer's first. Computed once server-side by
+   * the order.placed forwarder and persisted on the order, so the browser
+   * and the server cannot disagree. Omitted entirely when unknown: a
+   * wrong value is worse than an absent one for new-customer bidding.
+   */
+  newCustomer?: boolean
+}
+
+export function trackGoogleAdsPurchase(input: GoogleAdsPurchaseInput): void {
+  const gtag = safeGtag()
+  if (!gtag || !input.sendTo) return
+
+  const payload: Record<string, unknown> = {
+    send_to: input.sendTo,
+    value: input.value,
+    currency: input.currency,
+    transaction_id: input.transactionId,
+  }
+  if (typeof input.newCustomer === "boolean") {
+    payload.new_customer = input.newCustomer
+  }
+
+  gtag("event", "conversion", payload)
+}

package/src/tracking/gtm.tsx

@@ -1,60 +1,60 @@
-"use client"
-
-import Script from "next/script"
-
-import { jsStringLiteral, urlParam } from "./inline-script"
-
-/**
- * Gtm — Google Tag Manager container.
- *
- * The hub has served `tracking.gtm.containerId` to storefronts since the
- * tracking card shipped, and until now nothing in this package mounted
- * it, so a merchant who configured GTM got a container id in their page
- * data and no container. Same shape of defect as Google Ads was.
- *
- * GTM is the merchant's own escape hatch: whatever tag we have not built
- * a first-class integration for, they can deploy through their container
- * without waiting for us. That makes it worth mounting properly rather
- * than treating it as a lesser vendor.
- *
- * Consent: <ConsentInit> sets the Consent Mode v2 defaults synchronously
- * before this loads, so tags inside the container inherit the gate, and
- * `applyConsent()` pushes the visitor's decision to the same dataLayer.
- * Nothing extra to wire here.
- *
- * The <noscript> iframe is part of Google's documented snippet and is
- * what makes the container work for a scriptless visitor. Next renders
- * it in <body>, which is where Google puts it.
- *
- * Renders nothing when `containerId` is falsy.
- */
-export function Gtm({ containerId }: { containerId?: string }) {
-  if (!containerId) return null
-
-  const initSnippet = `
-(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
-new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
-j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
-'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
-})(window,document,'script','dataLayer',${jsStringLiteral(containerId)});
-`.trim()
-
-  return (
-    <>
-      <Script
-        id="gtm-init"
-        strategy="afterInteractive"
-        dangerouslySetInnerHTML={{ __html: initSnippet }}
-      />
-      <noscript>
-        <iframe
-          src={`https://www.googletagmanager.com/ns.html?id=${urlParam(containerId)}`}
-          height="0"
-          width="0"
-          style={{ display: "none", visibility: "hidden" }}
-          title="Google Tag Manager"
-        />
-      </noscript>
-    </>
-  )
-}
+"use client"
+
+import Script from "next/script"
+
+import { jsStringLiteral, urlParam } from "./inline-script"
+
+/**
+ * Gtm — Google Tag Manager container.
+ *
+ * The hub has served `tracking.gtm.containerId` to storefronts since the
+ * tracking card shipped, and until now nothing in this package mounted
+ * it, so a merchant who configured GTM got a container id in their page
+ * data and no container. Same shape of defect as Google Ads was.
+ *
+ * GTM is the merchant's own escape hatch: whatever tag we have not built
+ * a first-class integration for, they can deploy through their container
+ * without waiting for us. That makes it worth mounting properly rather
+ * than treating it as a lesser vendor.
+ *
+ * Consent: <ConsentInit> sets the Consent Mode v2 defaults synchronously
+ * before this loads, so tags inside the container inherit the gate, and
+ * `applyConsent()` pushes the visitor's decision to the same dataLayer.
+ * Nothing extra to wire here.
+ *
+ * The <noscript> iframe is part of Google's documented snippet and is
+ * what makes the container work for a scriptless visitor. Next renders
+ * it in <body>, which is where Google puts it.
+ *
+ * Renders nothing when `containerId` is falsy.
+ */
+export function Gtm({ containerId }: { containerId?: string }) {
+  if (!containerId) return null
+
+  const initSnippet = `
+(function(w,d,s,l,i){w[l]=w[l]||[];w[l].push({'gtm.start':
+new Date().getTime(),event:'gtm.js'});var f=d.getElementsByTagName(s)[0],
+j=d.createElement(s),dl=l!='dataLayer'?'&l='+l:'';j.async=true;j.src=
+'https://www.googletagmanager.com/gtm.js?id='+i+dl;f.parentNode.insertBefore(j,f);
+})(window,document,'script','dataLayer',${jsStringLiteral(containerId)});
+`.trim()
+
+  return (
+    <>
+      <Script
+        id="gtm-init"
+        strategy="afterInteractive"
+        dangerouslySetInnerHTML={{ __html: initSnippet }}
+      />
+      <noscript>
+        <iframe
+          src={`https://www.googletagmanager.com/ns.html?id=${urlParam(containerId)}`}
+          height="0"
+          width="0"
+          style={{ display: "none", visibility: "hidden" }}
+          title="Google Tag Manager"
+        />
+      </noscript>
+    </>
+  )
+}

package/src/tracking/inline-script.ts

@@ -1,49 +1,49 @@
-/**
- * Safe interpolation of a configured id into a vendor's inline snippet.
- *
- * Every tag component here injects the vendor's own bootstrap through
- * `dangerouslySetInnerHTML`, with the merchant's pixel / measurement /
- * conversion id written into it. Those ids arrive from the store's
- * integration settings, which means they are typed by a person in the
- * admin, and a value carrying a quote would close the string literal and
- * run whatever follows it on every page of that storefront.
- *
- * On a single-merchant site that is only self-inflicted. On a platform it
- * is one tenant's admin user writing script into that tenant's public
- * storefront, so the escape is not optional.
- *
- * Returns the value as a COMPLETE single-quoted JavaScript literal,
- * quotes included, so callers cannot forget to quote it themselves:
- *
- *     `fbq('init', ${jsStringLiteral(pixelId)});`
- */
-const LINE_SEPARATORS = new RegExp("[\u2028\u2029]", "g")
-
-export function jsStringLiteral(value: string): string {
-  const escaped = String(value)
-    .replace(/\\/g, "\\\\")
-    .replace(/'/g, "\\'")
-    .replace(/\r/g, "\\r")
-    .replace(/\n/g, "\\n")
-    // `</script` inside an inline script closes the element wherever it
-    // appears, quoted or not.
-    .replace(/<\//g, "<\\/")
-    // U+2028 and U+2029 are line terminators to a JavaScript parser, so
-    // they break a string literal exactly like a newline does. The class
-    // is built from escapes rather than written literally, because a
-    // source file carrying those characters raw is its own version of
-    // this problem (it breaks the file that fixes it).
-    .replace(LINE_SEPARATORS, (ch) =>
-      ch.charCodeAt(0) === 0x2028 ? "\\u2028" : "\\u2029"
-    )
-  return `'${escaped}'`
-}
-
-/**
- * The same value for a URL query parameter (the loader `src`), where the
- * hazard is a crafted id breaking out of the parameter rather than out of
- * a string literal.
- */
-export function urlParam(value: string): string {
-  return encodeURIComponent(String(value))
-}
+/**
+ * Safe interpolation of a configured id into a vendor's inline snippet.
+ *
+ * Every tag component here injects the vendor's own bootstrap through
+ * `dangerouslySetInnerHTML`, with the merchant's pixel / measurement /
+ * conversion id written into it. Those ids arrive from the store's
+ * integration settings, which means they are typed by a person in the
+ * admin, and a value carrying a quote would close the string literal and
+ * run whatever follows it on every page of that storefront.
+ *
+ * On a single-merchant site that is only self-inflicted. On a platform it
+ * is one tenant's admin user writing script into that tenant's public
+ * storefront, so the escape is not optional.
+ *
+ * Returns the value as a COMPLETE single-quoted JavaScript literal,
+ * quotes included, so callers cannot forget to quote it themselves:
+ *
+ *     `fbq('init', ${jsStringLiteral(pixelId)});`
+ */
+const LINE_SEPARATORS = new RegExp("[\u2028\u2029]", "g")
+
+export function jsStringLiteral(value: string): string {
+  const escaped = String(value)
+    .replace(/\\/g, "\\\\")
+    .replace(/'/g, "\\'")
+    .replace(/\r/g, "\\r")
+    .replace(/\n/g, "\\n")
+    // `</script` inside an inline script closes the element wherever it
+    // appears, quoted or not.
+    .replace(/<\//g, "<\\/")
+    // U+2028 and U+2029 are line terminators to a JavaScript parser, so
+    // they break a string literal exactly like a newline does. The class
+    // is built from escapes rather than written literally, because a
+    // source file carrying those characters raw is its own version of
+    // this problem (it breaks the file that fixes it).
+    .replace(LINE_SEPARATORS, (ch) =>
+      ch.charCodeAt(0) === 0x2028 ? "\\u2028" : "\\u2029"
+    )
+  return `'${escaped}'`
+}
+
+/**
+ * The same value for a URL query parameter (the loader `src`), where the
+ * hazard is a crafted id breaking out of the parameter rather than out of
+ * a string literal.
+ */
+export function urlParam(value: string): string {
+  return encodeURIComponent(String(value))
+}