@cartbase/storefront 0.20.0 → 0.21.0

package/src/tracking/track-init.tsx

@@ -1,56 +1,56 @@
-"use client"
-
-import { useEffect } from "react"
-
-import {
-  captureClickIdsFromUrl,
-  captureUtmsFromUrl,
-  getOrCreateAnonId,
-  setTrackingDefaults,
-} from "./attribution"
-import { initEngagementTime } from "./use-engagement-time"
-
-/**
- * TrackInit — mounts once in the root layout and does the four things
- * that must happen on the FIRST page of a visit, not at checkout:
- *
- *   1. Capture UTM parameters into the first-touch and last-touch
- *      cookies. First-touch is written once and survives a year, so the
- *      campaign that acquired the visitor is still attributable when they
- *      convert months later.
- *   2. Capture the ad-click identifiers — TikTok's `ttclid`, Google's
- *      `gclid` and the two iOS variants `gbraid` / `wbraid`. These arrive
- *      ONLY on the landing URL of an ad click. Miss them there and they
- *      are gone: the visitor navigates, the parameter disappears, and
- *      neither platform can ever tie the eventual order back to the click
- *      that paid for it.
- *   3. Create the anonymous visitor id, so events before signup can be
- *      joined to the customer afterwards.
- *   4. Start the engagement clock, so time-on-session is measured from
- *      the landing page rather than lazily from the first checkout call.
- *
- * All four are idempotent and safe on every mount: a URL with no
- * parameters leaves every existing cookie untouched, so an organic visit
- * never clears the click that acquired the visitor.
- *
- * Cookies only — nothing is sent from here. The server reads them at
- * checkout through `getTrackingAttribution()` and writes them onto the
- * cart, which carries them to the order, which is where the platform's
- * server-side Purchase events read them.
- *
- * `country` is the storefront's default market, used when an event has no
- * address to derive one from (a product view by an anonymous visitor).
- * Passing it lifts country coverage from the fraction of events that
- * carry an address to effectively all of them.
- */
-export function TrackInit({ country }: { country?: string } = {}) {
-  useEffect(() => {
-    if (country) setTrackingDefaults({ country })
-    captureUtmsFromUrl()
-    captureClickIdsFromUrl()
-    getOrCreateAnonId()
-    initEngagementTime()
-  }, [country])
-
-  return null
-}
+"use client"
+
+import { useEffect } from "react"
+
+import {
+  captureClickIdsFromUrl,
+  captureUtmsFromUrl,
+  getOrCreateAnonId,
+  setTrackingDefaults,
+} from "./attribution"
+import { initEngagementTime } from "./use-engagement-time"
+
+/**
+ * TrackInit — mounts once in the root layout and does the four things
+ * that must happen on the FIRST page of a visit, not at checkout:
+ *
+ *   1. Capture UTM parameters into the first-touch and last-touch
+ *      cookies. First-touch is written once and survives a year, so the
+ *      campaign that acquired the visitor is still attributable when they
+ *      convert months later.
+ *   2. Capture the ad-click identifiers — TikTok's `ttclid`, Google's
+ *      `gclid` and the two iOS variants `gbraid` / `wbraid`. These arrive
+ *      ONLY on the landing URL of an ad click. Miss them there and they
+ *      are gone: the visitor navigates, the parameter disappears, and
+ *      neither platform can ever tie the eventual order back to the click
+ *      that paid for it.
+ *   3. Create the anonymous visitor id, so events before signup can be
+ *      joined to the customer afterwards.
+ *   4. Start the engagement clock, so time-on-session is measured from
+ *      the landing page rather than lazily from the first checkout call.
+ *
+ * All four are idempotent and safe on every mount: a URL with no
+ * parameters leaves every existing cookie untouched, so an organic visit
+ * never clears the click that acquired the visitor.
+ *
+ * Cookies only — nothing is sent from here. The server reads them at
+ * checkout through `getTrackingAttribution()` and writes them onto the
+ * cart, which carries them to the order, which is where the platform's
+ * server-side Purchase events read them.
+ *
+ * `country` is the storefront's default market, used when an event has no
+ * address to derive one from (a product view by an anonymous visitor).
+ * Passing it lifts country coverage from the fraction of events that
+ * carry an address to effectively all of them.
+ */
+export function TrackInit({ country }: { country?: string } = {}) {
+  useEffect(() => {
+    if (country) setTrackingDefaults({ country })
+    captureUtmsFromUrl()
+    captureClickIdsFromUrl()
+    getOrCreateAnonId()
+    initEngagementTime()
+  }, [country])
+
+  return null
+}

package/src/tracking/track-order-purchase.tsx

@@ -1,122 +1,122 @@
-"use client"
-
-import { useEffect, useRef } from "react"
-
-import type { CartLineItem, CompletedOrder } from "../api/carts"
-import { trackOrderPurchase, type TrackedLine } from "./events"
-import type { TrackingConfig } from "./types"
-
-/**
- * TrackOrderPurchase — fires the purchase event to every configured
- * vendor from the order confirmation page.
- *
- * A component rather than four calls in the app, because purchase is the
- * one event nobody may get wrong and it is the one with the most ways to
- * go wrong: the dedup keys must match the server's exactly, the ids must
- * be the CATALOGUE's, and every vendor must fire from the same place.
- * A storefront mounts this and is done.
- *
- * FIRES ONCE PER ORDER, per browser. The guard is real, not defensive
- * tidiness: this page is linked from every order email, so a buyer opens
- * it again days later, and React strict mode double-mounts effects in
- * development. The vendors dedupe too (Meta and TikTok on the shared
- * event id, GA4 and Google Ads on the transaction id) and the platform's
- * server side carries its own idempotency flag, so this is the third of
- * three layers — but it is the only one that stops the request being made
- * at all.
- *
- * `customerType` comes from `order.metadata.customer_type`, which the
- * platform's order.placed forwarder computes ONCE and persists. Reading
- * it from the order rather than deriving it in the browser is what keeps
- * the browser and the server from telling Google and TikTok different
- * things about the same buyer.
- */
-
-const FIRED_KEY_PREFIX = "_cb_purchase_tracked_"
-
-function alreadyFired(key: string): boolean {
-  try {
-    return sessionStorage.getItem(key) === "1"
-  } catch {
-    // Private mode / blocked storage: fall back to the in-memory ref
-    // only. Worst case is a second event the vendors then dedupe.
-    return false
-  }
-}
-
-function markFired(key: string): void {
-  try {
-    sessionStorage.setItem(key, "1")
-  } catch {
-    // Non-fatal — see above.
-  }
-}
-
-export function TrackOrderPurchase({
-  order,
-  items,
-  config,
-}: {
-  order: CompletedOrder
-  /** The cart lines as completed. Carry product_id — it is the catalogue
-   *  key Meta and TikTok match on, and the flattened order items may not
-   *  have it. */
-  items: CartLineItem[]
-  /** The store's tracking config. Google Ads fires only when it carries
-   *  both the account id and the purchase label. */
-  config?: TrackingConfig
-}) {
-  const firedRef = useRef(false)
-
-  useEffect(() => {
-    const displayId = order.display_id
-    // No display id means no dedup key, and an event that cannot dedupe
-    // against the server's is worse than no event: it double-counts.
-    if (displayId === undefined || displayId === null) return
-
-    const key = `${FIRED_KEY_PREFIX}${displayId}`
-    if (firedRef.current || alreadyFired(key)) return
-    firedRef.current = true
-    markFired(key)
-
-    const lines: TrackedLine[] = items.map((item) => ({
-      productId: item.product_id || item.variant_id || item.id,
-      variantId: item.variant_id ?? undefined,
-      title: item.product_title || item.title || "",
-      quantity: Number(item.quantity) || 1,
-      price: Number(item.unit_price) || 0,
-    }))
-
-    const summary = (Array.isArray(order.summary)
-      ? order.summary[0]
-      : order.summary) as Record<string, unknown> | null
-    const totals = (summary?.totals ?? summary ?? {}) as Record<string, unknown>
-    const num = (v: unknown): number | undefined =>
-      typeof v === "number" ? v : undefined
-
-    const value =
-      num(totals.total) ??
-      lines.reduce((sum, line) => sum + line.price * line.quantity, 0)
-
-    const metadata = (order.metadata ?? {}) as Record<string, unknown>
-    const customerType =
-      metadata.customer_type === "new" || metadata.customer_type === "returning"
-        ? metadata.customer_type
-        : undefined
-
-    trackOrderPurchase(
-      {
-        displayId,
-        currency: (order.currency_code || "eur").toUpperCase(),
-        value,
-        tax: num(totals.tax_total),
-        shipping: num(totals.shipping_total),
-        lines,
-        customerType,
-      },
-      config
-    )
-  }, [order, items, config])
-
-  return null
-}
+"use client"
+
+import { useEffect, useRef } from "react"
+
+import type { CartLineItem, CompletedOrder } from "../api/carts"
+import { trackOrderPurchase, type TrackedLine } from "./events"
+import type { TrackingConfig } from "./types"
+
+/**
+ * TrackOrderPurchase — fires the purchase event to every configured
+ * vendor from the order confirmation page.
+ *
+ * A component rather than four calls in the app, because purchase is the
+ * one event nobody may get wrong and it is the one with the most ways to
+ * go wrong: the dedup keys must match the server's exactly, the ids must
+ * be the CATALOGUE's, and every vendor must fire from the same place.
+ * A storefront mounts this and is done.
+ *
+ * FIRES ONCE PER ORDER, per browser. The guard is real, not defensive
+ * tidiness: this page is linked from every order email, so a buyer opens
+ * it again days later, and React strict mode double-mounts effects in
+ * development. The vendors dedupe too (Meta and TikTok on the shared
+ * event id, GA4 and Google Ads on the transaction id) and the platform's
+ * server side carries its own idempotency flag, so this is the third of
+ * three layers — but it is the only one that stops the request being made
+ * at all.
+ *
+ * `customerType` comes from `order.metadata.customer_type`, which the
+ * platform's order.placed forwarder computes ONCE and persists. Reading
+ * it from the order rather than deriving it in the browser is what keeps
+ * the browser and the server from telling Google and TikTok different
+ * things about the same buyer.
+ */
+
+const FIRED_KEY_PREFIX = "_cb_purchase_tracked_"
+
+function alreadyFired(key: string): boolean {
+  try {
+    return sessionStorage.getItem(key) === "1"
+  } catch {
+    // Private mode / blocked storage: fall back to the in-memory ref
+    // only. Worst case is a second event the vendors then dedupe.
+    return false
+  }
+}
+
+function markFired(key: string): void {
+  try {
+    sessionStorage.setItem(key, "1")
+  } catch {
+    // Non-fatal — see above.
+  }
+}
+
+export function TrackOrderPurchase({
+  order,
+  items,
+  config,
+}: {
+  order: CompletedOrder
+  /** The cart lines as completed. Carry product_id — it is the catalogue
+   *  key Meta and TikTok match on, and the flattened order items may not
+   *  have it. */
+  items: CartLineItem[]
+  /** The store's tracking config. Google Ads fires only when it carries
+   *  both the account id and the purchase label. */
+  config?: TrackingConfig
+}) {
+  const firedRef = useRef(false)
+
+  useEffect(() => {
+    const displayId = order.display_id
+    // No display id means no dedup key, and an event that cannot dedupe
+    // against the server's is worse than no event: it double-counts.
+    if (displayId === undefined || displayId === null) return
+
+    const key = `${FIRED_KEY_PREFIX}${displayId}`
+    if (firedRef.current || alreadyFired(key)) return
+    firedRef.current = true
+    markFired(key)
+
+    const lines: TrackedLine[] = items.map((item) => ({
+      productId: item.product_id || item.variant_id || item.id,
+      variantId: item.variant_id ?? undefined,
+      title: item.product_title || item.title || "",
+      quantity: Number(item.quantity) || 1,
+      price: Number(item.unit_price) || 0,
+    }))
+
+    const summary = (Array.isArray(order.summary)
+      ? order.summary[0]
+      : order.summary) as Record<string, unknown> | null
+    const totals = (summary?.totals ?? summary ?? {}) as Record<string, unknown>
+    const num = (v: unknown): number | undefined =>
+      typeof v === "number" ? v : undefined
+
+    const value =
+      num(totals.total) ??
+      lines.reduce((sum, line) => sum + line.price * line.quantity, 0)
+
+    const metadata = (order.metadata ?? {}) as Record<string, unknown>
+    const customerType =
+      metadata.customer_type === "new" || metadata.customer_type === "returning"
+        ? metadata.customer_type
+        : undefined
+
+    trackOrderPurchase(
+      {
+        displayId,
+        currency: (order.currency_code || "eur").toUpperCase(),
+        value,
+        tax: num(totals.tax_total),
+        shipping: num(totals.shipping_total),
+        lines,
+        customerType,
+      },
+      config
+    )
+  }, [order, items, config])
+
+  return null
+}