@cartbase/storefront 0.5.0 → 0.7.0

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

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

package/src/tracking/ttq.ts

@@ -0,0 +1,180 @@
+"use client"
+
+/**
+ * Typed wrappers around the global `ttq` from the TikTok Pixel — the
+ * TikTok twin of ./fbq.ts, and deliberately the same shape so a surface
+ * that fires one can fire the other on the line below.
+ *
+ * Every helper no-ops when `window.ttq` is absent (pixel not configured,
+ * server render, script blocked), so callers need no guards.
+ *
+ * Event names are case-sensitive and taken from TikTok's supported pixel
+ * events table:
+ * https://business-api.tiktok.com/portal/docs/supported-pixel-events/v1.3
+ * `Purchase` is the current name; `CompletePayment` and `PlaceAnOrder` do
+ * not appear in the current tables at all.
+ *
+ * `event_id` is the THIRD argument, a separate object after the
+ * properties, per TikTok's own implementation guide:
+ *
+ *     ttq.track('Purchase', { ...properties }, { event_id: 'tt_purchase_1044' })
+ *
+ * TikTok deduplicates on event_source_id + event + event_id and discards
+ * duplicates for 48 hours from the first event, which is how the browser
+ * Purchase and the server-side Events API Purchase collapse into one.
+ *
+ * `content_id` must be the SAME identifier the product catalogue uses,
+ * which on Cartbase is the PRODUCT id — the value the feed emits as
+ * <g:id> and the value Meta already receives. A variant id here matches
+ * no catalogue entry at all.
+ */
+
+/** One product line inside `contents`. */
+export type TikTokContentItem = {
+  content_id: string
+  content_name?: string
+  content_category?: string
+  brand?: string
+  quantity?: number
+  price?: number
+}
+
+type TikTokProperties = {
+  contents?: TikTokContentItem[]
+  content_id?: string
+  content_name?: string
+  content_type?: "product" | "product_group"
+  currency?: string
+  value?: number
+  quantity?: number
+  description?: string
+  order_id?: string
+  /** TikTok's new-versus-returning signal. Same computed fact the backend
+   *  persists on the order and sends to Google Ads as `new_customer`. */
+  customer_type?: "new" | "returning"
+}
+
+type TtqFn = {
+  track: (
+    event: string,
+    properties?: TikTokProperties,
+    options?: { event_id?: string }
+  ) => void
+  page: () => void
+  identify: (data: Record<string, unknown>) => void
+  grantConsent: () => void
+  revokeConsent: () => void
+  holdConsent: () => void
+}
+
+function safeTtq(): TtqFn | null {
+  if (typeof window === "undefined") return null
+  const ttq = (window as unknown as { ttq?: Partial<TtqFn> }).ttq
+  if (!ttq || typeof ttq.track !== "function") return null
+  return ttq as TtqFn
+}
+
+/**
+ * THE purchase dedup key — must equal what the backend forwarder sends
+ * (`tiktokPurchaseEventId` in src/lib/tracking/constants.ts). Built from
+ * display_id here so the format cannot drift between the two sides, the
+ * same guarantee `trackPurchase` gives for Meta.
+ */
+export function tiktokPurchaseEventId(displayId: string | number): string {
+  return `tt_purchase_${displayId}`
+}
+
+export function trackTikTokViewContent(data: {
+  contentId: string
+  contentName?: string
+  currency: string
+  value: number
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("ViewContent", {
+    content_id: data.contentId,
+    content_type: "product",
+    content_name: data.contentName,
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackTikTokAddToCart(data: {
+  contentId: string
+  contentName?: string
+  quantity: number
+  price: number
+  currency: string
+  value: number
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("AddToCart", {
+    contents: [
+      {
+        content_id: data.contentId,
+        content_name: data.contentName,
+        quantity: data.quantity,
+        price: data.price,
+      },
+    ],
+    content_type: "product",
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackTikTokInitiateCheckout(data: {
+  contents: TikTokContentItem[]
+  currency: string
+  value: number
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track("InitiateCheckout", {
+    contents: data.contents,
+    content_type: "product",
+    currency: data.currency,
+    value: data.value,
+  })
+}
+
+export function trackTikTokPurchase(data: {
+  contents: TikTokContentItem[]
+  currency: string
+  value: number
+  /** The order's display id — the dedup key and the order_id TikTok shows. */
+  displayId: string | number
+  customerType?: "new" | "returning"
+}): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  ttq.track(
+    "Purchase",
+    {
+      contents: data.contents,
+      content_type: "product",
+      currency: data.currency,
+      value: data.value,
+      order_id: String(data.displayId),
+      ...(data.customerType ? { customer_type: data.customerType } : {}),
+    },
+    { event_id: tiktokPurchaseEventId(data.displayId) }
+  )
+}
+
+/**
+ * Push a live consent decision to the pixel.
+ *
+ * Normally you do NOT call this: `applyConsent()` in ./consent.ts already
+ * relays every decision to gtag, fbq and ttq together. It is exported for
+ * a host app driving the pixel from a consent layer of its own.
+ */
+export function applyTikTokConsent(adsGranted: boolean): void {
+  const ttq = safeTtq()
+  if (!ttq) return
+  if (adsGranted) ttq.grantConsent()
+  else ttq.revokeConsent()
+}

package/src/tracking/types.ts

@@ -40,6 +40,10 @@ export type TrackingConfig = {
   /** Cartbase extension over the @1click TrackingConfig — explicit Google
    *  Ads tag config (the @1click engine wired Ads through GTM). */
   googleAds?: { conversionId: string; conversionLabel?: string }
+  /** Pixel id ONLY. The Events API token stays on the platform and is
+   *  read by the order.placed forwarder, exactly like Meta's CAPI token,
+   *  which has never traversed this surface. */
+  tiktok?: { pixelId: string }
   /** True when the store's consent CMP is enabled — client tags must
    *  mount through the consent gate (`_1c_consent` / Consent Mode v2). */
   consent_required?: boolean
@@ -171,6 +175,25 @@ export type TrackingAttribution = {
   utm_last_term?: string
   utm_last_content?: string
   utm_last_captured_at?: number
+
+  // ── Ad-click identifiers ───────────────────────────────────────────
+  // Captured by browser-side `captureClickIdsFromUrl()` into `_1c_`
+  // cookies and read here at checkout. Meta's fbclid needs no entry: it
+  // is folded into `fb_fbc` by Meta's own cookie format.
+
+  /** TikTok's click id. Without it TikTok cannot attribute a conversion
+   *  back to the click that caused it. Sent as `user.ttclid`. */
+  tt_ttclid?: string
+  /** The `_ttp` cookie TikTok's own pixel writes when first-party
+   *  cookies are enabled. Read only; sent as `user.ttp`. */
+  tt_ttp?: string
+  /** Google's standard click id. */
+  google_gclid?: string
+  /** iOS app-to-web click id. A campaign can deliver this instead of
+   *  gclid, so capturing gclid alone loses that traffic silently. */
+  google_gbraid?: string
+  /** iOS web-to-web click id, same reasoning as gbraid. */
+  google_wbraid?: string
 }
 
 /**

package/src/tracking/use-tracking-config.ts

@@ -0,0 +1,54 @@
+"use client"
+
+import { useEffect, useState } from "react"
+
+import type { StorefrontClient } from "../api/http"
+import { getTrackingConfig } from "./get-tracking-config"
+import type { TrackingConfig } from "./types"
+
+/**
+ * The store's public tag config, from a client component.
+ *
+ * `<StorefrontTags>` reads the same config on the SERVER, which is right
+ * for mounting tags in a layout. This hook exists for the one place that
+ * genuinely cannot: a client page that needs the config to decide what to
+ * send, the order confirmation being the case that matters, because
+ * Google Ads needs the account id and the purchase label to build a valid
+ * `send_to`.
+ *
+ * Cached per browser session in module scope: the config changes only
+ * when a merchant edits Settings → Integrations, and re-fetching it on
+ * every mount would put a request in front of the purchase event.
+ *
+ * Returns undefined until the fetch resolves, and `{}` if it fails, so a
+ * caller renders and fires the vendors that need no config either way.
+ */
+
+let cached: TrackingConfig | undefined
+let inFlight: Promise<TrackingConfig> | undefined
+
+export function useTrackingConfig(
+  client: StorefrontClient
+): TrackingConfig | undefined {
+  const [config, setConfig] = useState<TrackingConfig | undefined>(cached)
+
+  useEffect(() => {
+    if (cached) return
+    let active = true
+    inFlight =
+      inFlight ??
+      getTrackingConfig(client).then((value) => {
+        cached = value
+        inFlight = undefined
+        return value
+      })
+    inFlight.then((value) => {
+      if (active) setConfig(value)
+    })
+    return () => {
+      active = false
+    }
+  }, [client])
+
+  return config
+}