@cartbase/storefront 0.6.0 → 0.8.0

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
+}