@cartbase/storefront 0.5.0 → 0.7.0

package/src/tracking/events.ts

@@ -0,0 +1,294 @@
+"use client"
+
+import {
+  trackAddToCart,
+  trackInitiateCheckout,
+  trackPurchase,
+  trackViewContent,
+} from "./fbq"
+import {
+  trackGAAddToCart,
+  trackGABeginCheckout,
+  trackGAPurchase,
+  trackGAViewItem,
+} from "./gtag"
+import {
+  trackRybbitAddToCart,
+  trackRybbitBeginCheckout,
+  trackRybbitPurchase,
+  trackRybbitViewItem,
+} from "./rybbit-events"
+import {
+  trackTikTokAddToCart,
+  trackTikTokInitiateCheckout,
+  trackTikTokPurchase,
+  trackTikTokViewContent,
+} from "./ttq"
+import { googleAdsPurchaseSendTo, trackGoogleAdsPurchase } from "./google-ads"
+import type { TrackingConfig } from "./types"
+
+/**
+ * ONE call per commerce moment, every vendor at once.
+ *
+ * The per-vendor helpers beside this file stay exported and stay usable.
+ * This is the door a storefront should reach for anyway, because the
+ * failure these functions prevent is the most common one in tracking and
+ * it is invisible: a store adds a fifth vendor, updates four call sites,
+ * misses the fifth, and nobody notices until an ad account has been
+ * optimising on partial data for a month. We have watched it happen to a
+ * product page whose buy box predated a shared helper: ViewContent and
+ * InitiateCheckout were present, AddToCart was missing from the single
+ * most-used add path in the store.
+ *
+ * With one function per moment, a vendor is added HERE, once, and every
+ * surface that already calls it gains the vendor for free.
+ *
+ * Every helper underneath no-ops when its tag is absent, so passing a
+ * config with only two vendors configured fires exactly those two.
+ *
+ * Identifier discipline, and it is not cosmetic:
+ *   - `productId` is the catalogue key. Meta's content_ids, TikTok's
+ *     content_id and the feed's <g:id> must be the SAME value or the
+ *     event matches no catalogue entry, which costs dynamic ads and
+ *     product-level reporting on both platforms.
+ *   - GA4 is the exception on purpose: its items are keyed by VARIANT,
+ *     because GA4 reports on what was actually bought rather than
+ *     matching an ads catalogue.
+ *   - Purchase dedup keys are derived from `displayId` inside the
+ *     helpers, never passed in, so the browser and the server cannot
+ *     drift apart.
+ */
+
+/** One line, in the shape every vendor is derived from. */
+export type TrackedLine = {
+  /** Catalogue key. Meta + TikTok content ids, and the feed's <g:id>. */
+  productId: string
+  /** What was actually bought. GA4 item_id. */
+  variantId?: string
+  title: string
+  quantity: number
+  /** Unit price, in `currency`. */
+  price: number
+}
+
+export type TrackedOrder = {
+  /** THE dedup key across every vendor and both sides of the wire. */
+  displayId: string | number
+  currency: string
+  /** Order total actually collected. */
+  value: number
+  tax?: number
+  shipping?: number
+  coupon?: string
+  lines: TrackedLine[]
+  /**
+   * First order for this buyer. Computed server-side by the order.placed
+   * forwarder and persisted on the order as `metadata.customer_type`;
+   * read it from there rather than deriving it in the browser, so the two
+   * sides tell the ad platforms the same thing. Omit when unknown.
+   */
+  customerType?: "new" | "returning"
+}
+
+const gaItems = (lines: TrackedLine[], currency: string) =>
+  lines.map((line, index) => ({
+    item_id: line.variantId || line.productId,
+    item_name: line.title,
+    quantity: line.quantity,
+    price: line.price,
+    currency,
+    index,
+  }))
+
+const metaContents = (lines: TrackedLine[]) =>
+  lines.map((line) => ({
+    id: line.productId,
+    quantity: line.quantity,
+    item_price: line.price,
+  }))
+
+const tiktokContents = (lines: TrackedLine[]) =>
+  lines.map((line) => ({
+    content_id: line.productId,
+    content_name: line.title,
+    quantity: line.quantity,
+    price: line.price,
+  }))
+
+const unitCount = (lines: TrackedLine[]) =>
+  lines.reduce((sum, line) => sum + (Number(line.quantity) || 0), 0)
+
+/** Product page view. */
+export function trackProductView(input: {
+  line: TrackedLine
+  currency: string
+  value: number
+}): void {
+  const { line, currency, value } = input
+  trackViewContent({
+    content_ids: [line.productId],
+    content_type: "product",
+    currency,
+    value,
+  })
+  trackTikTokViewContent({
+    contentId: line.productId,
+    contentName: line.title,
+    currency,
+    value,
+  })
+  trackGAViewItem({ currency, value, items: gaItems([line], currency) })
+  trackRybbitViewItem({
+    item_id: line.variantId || line.productId,
+    item_name: line.title,
+    currency,
+    value,
+  })
+}
+
+/** Add to cart, from ANY surface — listing card, buy box, upsell rail. */
+export function trackCartAdd(input: {
+  line: TrackedLine
+  currency: string
+  value: number
+}): void {
+  const { line, currency, value } = input
+  trackAddToCart({
+    content_ids: [line.productId],
+    content_type: "product",
+    currency,
+    value,
+    contents: metaContents([line]),
+  })
+  trackTikTokAddToCart({
+    contentId: line.productId,
+    contentName: line.title,
+    quantity: line.quantity,
+    price: line.price,
+    currency,
+    value,
+  })
+  trackGAAddToCart({ currency, value, items: gaItems([line], currency) })
+  trackRybbitAddToCart({
+    item_id: line.variantId || line.productId,
+    item_name: line.title,
+    quantity: line.quantity,
+    currency,
+    value,
+  })
+}
+
+/** Checkout started. */
+export function trackCheckoutStart(input: {
+  lines: TrackedLine[]
+  currency: string
+  value: number
+  coupon?: string
+}): void {
+  const { lines, currency, value, coupon } = input
+  trackInitiateCheckout({
+    content_ids: lines.map((line) => line.productId),
+    content_type: "product",
+    currency,
+    value,
+    num_items: unitCount(lines),
+    contents: metaContents(lines),
+  })
+  trackTikTokInitiateCheckout({
+    contents: tiktokContents(lines),
+    currency,
+    value,
+  })
+  trackGABeginCheckout({
+    currency,
+    value,
+    items: gaItems(lines, currency),
+    ...(coupon ? { coupon } : {}),
+  })
+  trackRybbitBeginCheckout({
+    item_ids: lines.map((line) => line.variantId || line.productId),
+    num_items: unitCount(lines),
+    currency,
+    value,
+  })
+}
+
+/**
+ * Order confirmed — the money event.
+ *
+ * Google Ads only fires when the store configured BOTH the account id
+ * and the purchase conversion label, which is why the config is a
+ * parameter here: `googleAdsPurchaseSendTo` returns null otherwise, and a
+ * malformed `send_to` is accepted by Google and silently dropped.
+ *
+ * Everything here is deduped against the server: Meta on
+ * `purchase_<displayId>`, TikTok on `tt_purchase_<displayId>`, GA4 and
+ * Google Ads on the transaction id, which is `displayId` itself.
+ */
+export function trackOrderPurchase(
+  order: TrackedOrder,
+  config?: TrackingConfig
+): void {
+  const {
+    displayId,
+    currency,
+    value,
+    lines,
+    tax,
+    shipping,
+    coupon,
+    customerType,
+  } = order
+  const transactionId = String(displayId)
+
+  trackPurchase(
+    {
+      content_ids: lines.map((line) => line.productId),
+      content_type: "product",
+      currency,
+      value,
+      num_items: unitCount(lines),
+      contents: metaContents(lines),
+    },
+    displayId
+  )
+
+  trackTikTokPurchase({
+    contents: tiktokContents(lines),
+    currency,
+    value,
+    displayId,
+    customerType,
+  })
+
+  trackGAPurchase({
+    transaction_id: transactionId,
+    currency,
+    value,
+    items: gaItems(lines, currency),
+    ...(typeof tax === "number" ? { tax } : {}),
+    ...(typeof shipping === "number" ? { shipping } : {}),
+    ...(coupon ? { coupon } : {}),
+  })
+
+  trackRybbitPurchase({
+    transaction_id: transactionId,
+    item_ids: lines.map((line) => line.variantId || line.productId),
+    num_items: unitCount(lines),
+    currency,
+    value,
+  })
+
+  const sendTo = config ? googleAdsPurchaseSendTo(config) : null
+  if (sendTo) {
+    trackGoogleAdsPurchase({
+      sendTo,
+      value,
+      currency,
+      transactionId,
+      ...(customerType
+        ? { newCustomer: customerType === "new" }
+        : {}),
+    })
+  }
+}

package/src/tracking/ga4.tsx

@@ -1,49 +1,93 @@
-"use client"
-
-import Script from "next/script"
-
-/**
- * GA4 — Google Analytics 4 base script loader.
- *
- * Loads `https://www.googletagmanager.com/gtag/js?id=<measurementId>` via
- * Next.js `<Script strategy="afterInteractive">` and initialises gtag with
- * the given measurement ID. Once loaded, gtag automatically sets the
- * `_ga` and `_ga_<MEASUREMENT_ID>` first-party cookies, which the server
- * action `getTrackingAttribution` then reads on cart completion to
- * forward `ga_client_id` / `ga_session_id` into the order metadata for
- * GA4 Measurement Protocol Purchase events.
- *
- * Renders nothing when `measurementId` is falsy — every consuming layout
- * can call this unconditionally; the script is only injected when the
- * admin has configured GA4.
- *
- * `send_page_view: true` (default) — initial page_view fires automatically
- * on script load. Subsequent SPA route changes are NOT auto-tracked by
- * gtag; storefronts that need per-route page_views should call
- * `gtag('event', 'page_view', { page_path })` from a route-change effect.
- */
-export function GA4({ measurementId }: { measurementId?: string }) {
-  if (!measurementId) return null
-
-  const initSnippet = `
-window.dataLayer = window.dataLayer || [];
-function gtag(){dataLayer.push(arguments);}
-gtag('js', new Date());
-gtag('config', '${measurementId}');
-`.trim()
-
-  return (
-    <>
-      <Script
-        id="ga4-loader"
-        strategy="afterInteractive"
-        src={`https://www.googletagmanager.com/gtag/js?id=${measurementId}`}
-      />
-      <Script
-        id="ga4-init"
-        strategy="afterInteractive"
-        dangerouslySetInnerHTML={{ __html: initSnippet }}
-      />
-    </>
-  )
-}
+"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/get-tracking-attribution.ts

@@ -3,6 +3,7 @@ import { cookies, headers } from "next/headers"
 import { getTrackingConfig } from "./get-tracking-config"
 import type { StorefrontClient } from "../api/http"
 import type { TrackingAttribution, TrackingClientHints } from "./types"
+import { CLICK_ID_METADATA_KEYS } from "./attribution"
 
 /**
  * Reads Meta + GA4 attribution signals from the current Next.js server
@@ -110,6 +111,35 @@ export async function getTrackingAttribution(
   applyUtmCookie(utmFirstRaw, "utm_first", result)
   applyUtmCookie(utmLastRaw, "utm_last", result)
 
+  // Ad-click identifiers — TikTok's ttclid / _ttp and Google's gclid /
+  // gbraid / wbraid, captured into cookies by captureClickIdsFromUrl().
+  // They travel the same road as the UTMs: cart.metadata at checkout,
+  // order.metadata at completion, and from there into the TikTok Events
+  // API `user` block. Without ttclid TikTok cannot tie a conversion back
+  // to the click that produced it, which is the number the advertiser
+  // looks at first.
+  try {
+    const cookieStore = await cookies()
+    // The key map is a plain tuple list (attribution.ts owns the cookie
+    // names), so the write goes through one narrow cast rather than a
+    // per-key branch that would have to be edited for every new platform.
+    const sink = result as Record<string, unknown>
+    for (const [cookieName, metadataKey] of CLICK_ID_METADATA_KEYS) {
+      const value = cookieStore.get(cookieName)?.value
+      if (value) {
+        // Written encoded by the capture; decoded once here so the wire
+        // carries the id the platform actually issued.
+        try {
+          sink[metadataKey] = decodeURIComponent(value)
+        } catch {
+          sink[metadataKey] = value
+        }
+      }
+    }
+  } catch {
+    // best-effort — attribution never blocks a checkout
+  }
+
   // _ga cookie format: "GA1.1.<client_id>.<timestamp>" — backend wants
   // the full <client_id>.<timestamp> portion (the canonical GA client_id).
   if (gaCookieRaw) {

package/src/tracking/google-ads.ts

@@ -0,0 +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)
+}

package/src/tracking/gtag.ts

@@ -1,6 +1,10 @@
 "use client"
 
-import { sha256Hex, normaliseEmailForHash, normalisePhoneForHash } from "./attribution"
+import {
+  sha256Hex,
+  normaliseEmailForHash,
+  normalisePhoneForGoogleHash,
+} from "./attribution"
 
 /**
  * Typed wrappers around the global `gtag()` from GA4 (gtag.js).
@@ -114,16 +118,23 @@ export function trackGAPurchase(data: GA4PurchaseData): void {
  * these signals to recover conversions that browser cookies miss
  * (Safari ITP, iOS, ad-blockers).
  *
- * Hashing strategy mirrors the Meta side (attribution.ts):
- *   - email / phone / first_name / last_name → SHA-256 hex, lowercase
- *     normalised, phone E.164-style digits-only with country code
- *   - city / region / postal_code / country / street → raw plain text
- *     (Google's spec only documents sha256 variants for name fields
- *     within the address block; geo fields are accepted as plain)
+ * Hashing:
+ *   - email / first_name / last_name: SHA-256 hex of the trimmed,
+ *     lowercased value, which is what both vendors want
+ *   - phone: SHA-256 hex of E.164 WITH the leading plus, which is what
+ *     GOOGLE wants and is NOT what Meta wants
+ *   - city / region / postal_code / country / street: plain text
+ *     (Google documents sha256 variants only for the name fields inside
+ *     the address block; geo fields are accepted as plain)
  *
- * Same input on both sides produces same digest → both vendors' match
- * engines see identical hashes for the same user. Storefront callers
- * pass RAW values; this function does the normalize+hash inline.
+ * The phone line is the one to read twice. This function used to reuse
+ * Meta's digits-only normaliser on the reasoning that both vendors should
+ * see identical digests for the same person. That was the bug: Google
+ * requires the plus, so the digest matched nobody, and nothing failed
+ * loudly enough to notice. Two vendors, two normalisers, on purpose.
+ *
+ * Storefront callers pass RAW values; this function normalises and hashes
+ * inline.
  *
  * Idempotent — safe to call repeatedly as new fields become known
  * (gtag.set merges user_data per Google's spec).
@@ -160,9 +171,11 @@ export async function setEnhancedConversions(
     )
   }
   if (input.phone) {
-    userData.sha256_phone_number = await sha256Hex(
-      normalisePhoneForHash(input.phone)
-    )
+    // Undefined for anything that could not be a real E.164 number: a
+    // hash of a malformed phone cannot match, and it costs the field
+    // Google would otherwise fall back from.
+    const e164 = normalisePhoneForGoogleHash(input.phone)
+    if (e164) userData.sha256_phone_number = await sha256Hex(e164)
   }
 
   const address: Record<string, unknown> = {}

package/src/tracking/gtm.tsx

@@ -0,0 +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>
+    </>
+  )
+}