@cartbase/storefront 0.5.0 → 0.7.0

package/src/tracking/index.ts

@@ -1,133 +1,176 @@
-/**
- * @cartbase/storefront/tracking — Meta Pixel + GA4 + Rybbit + Consent Mode v2.
- *
- * Ported from `@1click/ui/src/tracking` (v2.3.1) with the Cartbase seams:
- *   - config comes from `GET /api/store/integrations` → `tracking` block
- *     via `getTrackingConfig(client)` (never env vars)
- *   - server-side CAPI / GA4-MP sending is Cartbase-backend-owned (the
- *     `order.placed` forwarder) — this package fires CLIENT events only
- *     and writes attribution for the server to inherit
- *   - Purchase dedupe: Pixel `eventID = "purchase_" + order.display_id`
- *     (trackPurchase builds it); GA4 `transaction_id =
- *     String(order.display_id)`
- *
- * Public surface:
- *   - <ConsentInit> / <ConsentBanner> / <ConsentSettingsLink> — Consent
- *     Mode v2 (config from GET /api/store/consent; `_1c_consent` seam)
- *   - <MetaPixel pixelId> / <GA4 measurementId> / <Rybbit siteId> — layout tags
- *   - Meta Pixel client helpers: trackViewContent / trackAddToCart /
- *     trackInitiateCheckout / trackPurchase / trackLead
- *   - GA4 client helpers: trackGAViewItem / trackGAAddToCart /
- *     trackGABeginCheckout / trackGAPurchase / setEnhancedConversions
- *   - Rybbit client helpers: trackRybbit* (queue-buffered)
- *   - getTrackingConfig(client) — the public tag config
- *   - getTrackingAttribution(clientHints?, opts?) — server-side signal
- *     gathering for the cart.metadata writeback (consent-gated)
- *   - getEngagementTimeMsec() / initEngagementTime() — time-on-session
- *
- * Server vs client split (per Next.js App Router rules):
- *   - get-tracking-attribution.ts imports `next/headers` (server-only by
- *     construction); get-tracking-config.ts is isomorphic
- *   - meta-pixel.tsx, ga4.tsx, rybbit.tsx, fbq.ts, gtag.ts,
- *     rybbit-events.ts, attribution.ts, use-engagement-time.ts,
- *     consent-banner.tsx are `"use client"`
- *   - types.ts, consent.ts, consent-init.tsx are universal
- *
- * Importers should usually pull from the subpath that matches their
- * environment. The barrel re-exports everything, but tree-shaking and
- * Next.js's RSC boundary detection both work better with subpaths.
- */
-
-export { MetaPixel, updatePixelAdvancedMatching } from "./meta-pixel"
-export { GA4 } from "./ga4"
-export { Rybbit } from "./rybbit"
-export { ConsentInit } from "./consent-init"
-export { ConsentBanner, ConsentBannerCard, ConsentSettingsLink } from "./consent-banner"
-export {
-  applyConsent,
-  setConsent,
-  openConsentSettings,
-  readConsentCookie,
-  writeConsentCookie,
-  shouldRenderBanner,
-  pickConsentCopy,
-  CONSENT_COOKIE,
-  CONSENT_MAX_AGE_SECONDS,
-  CONSENT_OPEN_EVENT,
-  CONSENT_INIT_SNIPPET,
-  type ConsentChoices,
-  type ConsentCopy,
-  type ConsentLayout,
-  type ConsentMode,
-  type ConsentSettings,
-} from "./consent"
-export {
-  trackViewContent,
-  trackAddToCart,
-  trackInitiateCheckout,
-  trackPurchase,
-  trackLead,
-  generateEventId,
-  type LeadContext,
-} from "./fbq"
-export {
-  setTrackingDefaults,
-  getOrCreateAnonId,
-  getOrCreateFbp,
-  getOrCreateFbc,
-  getKnownVisitor,
-  rememberKnownVisitor,
-  captureUtmsFromUrl,
-  getCapturedFirstTouchUtms,
-  getCapturedLastTouchUtms,
-  sha256Hex,
-  normaliseEmailForHash,
-  normalisePhoneForHash,
-  type KnownVisitor,
-  type CapturedUtms,
-} from "./attribution"
-export {
-  trackGAViewItem,
-  trackGAAddToCart,
-  trackGABeginCheckout,
-  trackGAPurchase,
-  setEnhancedConversions,
-  type EnhancedConversionsInput,
-} from "./gtag"
-export {
-  trackRybbitViewItem,
-  trackRybbitAddToCart,
-  trackRybbitBeginCheckout,
-  trackRybbitPurchase,
-  type RybbitViewItemData,
-  type RybbitAddToCartData,
-  type RybbitBeginCheckoutData,
-  type RybbitPurchaseData,
-} from "./rybbit-events"
-export { getTrackingConfig } from "./get-tracking-config"
-export { getTrackingAttribution } from "./get-tracking-attribution"
-export {
-  getEngagementTimeMsec,
-  initEngagementTime,
-} from "./use-engagement-time"
-
-export type {
-  TrackingConfig,
-  TrackingConfigResponse,
-  TrackingAttribution,
-  TrackingClientHints,
-  MetaContentItem,
-  ViewContentData,
-  AddToCartData,
-  InitiateCheckoutData,
-  PurchaseData,
-  LeadData,
-} from "./types"
-
-export type {
-  GA4Item,
-  GA4ViewItemData,
-  GA4AddToCartData,
-  GA4BeginCheckoutData,
-  GA4PurchaseData,
-} from "./gtag"
+/**
+ * @cartbase/storefront/tracking — Meta Pixel + GA4 + Rybbit + Consent Mode v2.
+ *
+ * Ported from `@1click/ui/src/tracking` (v2.3.1) with the Cartbase seams:
+ *   - config comes from `GET /api/store/integrations` → `tracking` block
+ *     via `getTrackingConfig(client)` (never env vars)
+ *   - server-side CAPI / GA4-MP sending is Cartbase-backend-owned (the
+ *     `order.placed` forwarder) — this package fires CLIENT events only
+ *     and writes attribution for the server to inherit
+ *   - Purchase dedupe: Pixel `eventID = "purchase_" + order.display_id`
+ *     (trackPurchase builds it); GA4 `transaction_id =
+ *     String(order.display_id)`
+ *
+ * Public surface:
+ *   - <ConsentInit> / <ConsentBanner> / <ConsentSettingsLink> — Consent
+ *     Mode v2 (config from GET /api/store/consent; `_1c_consent` seam)
+ *   - <StorefrontTags client> — EVERY tag the store configured, mounted
+ *     from its own config. This is the one a storefront should mount;
+ *     the individual tags below are for a layout that needs control.
+ *   - <TrackInit /> — captures UTMs and ad-click ids on the landing page
+ *     (they exist only there) and starts the engagement clock.
+ *   - <MetaPixel pixelId> / <GoogleTag measurementId adsConversionId> /
+ *     <TikTokPixel pixelId> / <Gtm containerId> / <Rybbit siteId> —
+ *     individual layout tags (<GA4> is <GoogleTag> with only the
+ *     analytics destination)
+ *   - ONE call per commerce moment, every vendor at once (prefer these):
+ *     trackProductView / trackCartAdd / trackCheckoutStart /
+ *     trackOrderPurchase
+ *   - Meta Pixel client helpers: trackViewContent / trackAddToCart /
+ *     trackInitiateCheckout / trackPurchase / trackLead
+ *   - GA4 client helpers: trackGAViewItem / trackGAAddToCart /
+ *     trackGABeginCheckout / trackGAPurchase / setEnhancedConversions
+ *   - Rybbit client helpers: trackRybbit* (queue-buffered)
+ *   - getTrackingConfig(client) — the public tag config
+ *   - getTrackingAttribution(clientHints?, opts?) — server-side signal
+ *     gathering for the cart.metadata writeback (consent-gated)
+ *   - getEngagementTimeMsec() / initEngagementTime() — time-on-session
+ *
+ * Server vs client split (per Next.js App Router rules):
+ *   - get-tracking-attribution.ts imports `next/headers` (server-only by
+ *     construction); get-tracking-config.ts is isomorphic
+ *   - meta-pixel.tsx, ga4.tsx, rybbit.tsx, fbq.ts, gtag.ts,
+ *     rybbit-events.ts, attribution.ts, use-engagement-time.ts,
+ *     consent-banner.tsx are `"use client"`
+ *   - types.ts, consent.ts, consent-init.tsx are universal
+ *
+ * Importers should usually pull from the subpath that matches their
+ * environment. The barrel re-exports everything, but tree-shaking and
+ * Next.js's RSC boundary detection both work better with subpaths.
+ */
+
+export { MetaPixel, updatePixelAdvancedMatching } from "./meta-pixel"
+export { GA4, GoogleTag } from "./ga4"
+export { Gtm } from "./gtm"
+export { TikTokPixel } from "./tiktok-pixel"
+export { StorefrontTags } from "./storefront-tags"
+export { TrackInit } from "./track-init"
+export { TrackOrderPurchase } from "./track-order-purchase"
+export { Rybbit } from "./rybbit"
+export { ConsentInit } from "./consent-init"
+export { ConsentBanner, ConsentBannerCard, ConsentSettingsLink } from "./consent-banner"
+export {
+  applyConsent,
+  setConsent,
+  openConsentSettings,
+  readConsentCookie,
+  writeConsentCookie,
+  shouldRenderBanner,
+  pickConsentCopy,
+  CONSENT_COOKIE,
+  CONSENT_MAX_AGE_SECONDS,
+  CONSENT_OPEN_EVENT,
+  CONSENT_INIT_SNIPPET,
+  type ConsentChoices,
+  type ConsentCopy,
+  type ConsentLayout,
+  type ConsentMode,
+  type ConsentSettings,
+} from "./consent"
+export {
+  trackViewContent,
+  trackAddToCart,
+  trackInitiateCheckout,
+  trackPurchase,
+  trackLead,
+  generateEventId,
+  type LeadContext,
+} from "./fbq"
+export {
+  setTrackingDefaults,
+  getOrCreateAnonId,
+  getOrCreateFbp,
+  getOrCreateFbc,
+  getKnownVisitor,
+  rememberKnownVisitor,
+  captureUtmsFromUrl,
+  captureClickIdsFromUrl,
+  getCapturedFirstTouchUtms,
+  getCapturedLastTouchUtms,
+  sha256Hex,
+  normaliseEmailForHash,
+  normalisePhoneForHash,
+  normalisePhoneForGoogleHash,
+  CLICK_ID_COOKIES,
+  CLICK_ID_METADATA_KEYS,
+  type KnownVisitor,
+  type CapturedUtms,
+} from "./attribution"
+export {
+  trackProductView,
+  trackCartAdd,
+  trackCheckoutStart,
+  trackOrderPurchase,
+  type TrackedLine,
+  type TrackedOrder,
+} from "./events"
+export {
+  trackTikTokViewContent,
+  trackTikTokAddToCart,
+  trackTikTokInitiateCheckout,
+  trackTikTokPurchase,
+  applyTikTokConsent,
+  tiktokPurchaseEventId,
+  type TikTokContentItem,
+} from "./ttq"
+export {
+  trackGoogleAdsPurchase,
+  googleAdsPurchaseSendTo,
+  type GoogleAdsPurchaseInput,
+} from "./google-ads"
+export {
+  trackGAViewItem,
+  trackGAAddToCart,
+  trackGABeginCheckout,
+  trackGAPurchase,
+  setEnhancedConversions,
+  type EnhancedConversionsInput,
+} from "./gtag"
+export {
+  trackRybbitViewItem,
+  trackRybbitAddToCart,
+  trackRybbitBeginCheckout,
+  trackRybbitPurchase,
+  type RybbitViewItemData,
+  type RybbitAddToCartData,
+  type RybbitBeginCheckoutData,
+  type RybbitPurchaseData,
+} from "./rybbit-events"
+export { getTrackingConfig } from "./get-tracking-config"
+export { useTrackingConfig } from "./use-tracking-config"
+export { getTrackingAttribution } from "./get-tracking-attribution"
+export {
+  getEngagementTimeMsec,
+  initEngagementTime,
+} from "./use-engagement-time"
+
+export type {
+  TrackingConfig,
+  TrackingConfigResponse,
+  TrackingAttribution,
+  TrackingClientHints,
+  MetaContentItem,
+  ViewContentData,
+  AddToCartData,
+  InitiateCheckoutData,
+  PurchaseData,
+  LeadData,
+} from "./types"
+
+export type {
+  GA4Item,
+  GA4ViewItemData,
+  GA4AddToCartData,
+  GA4BeginCheckoutData,
+  GA4PurchaseData,
+} from "./gtag"

package/src/tracking/inline-script.ts

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

package/src/tracking/storefront-tags.tsx

@@ -0,0 +1,67 @@
+import { GoogleTag } from "./ga4"
+import { Gtm } from "./gtm"
+import { MetaPixel } from "./meta-pixel"
+import { TikTokPixel } from "./tiktok-pixel"
+import { getTrackingConfig } from "./get-tracking-config"
+import type { StorefrontClient } from "../api/http"
+import type { TrackingConfig } from "./types"
+
+/**
+ * StorefrontTags — every marketing tag the store has configured, mounted
+ * from the store's own config.
+ *
+ * THE POINT: a merchant who saves their pixel ids in the admin gets those
+ * tags on their storefront, with nothing else to do and no code to write.
+ * Before this existed the package EXPORTED tags and no storefront mounted
+ * them, so the admin could serve a Meta pixel id, a GA4 id and a Google
+ * Ads conversion id that reached the browser and did nothing. Adding a
+ * vendor is one line HERE now, and every store built on the package gains
+ * it at the next deploy.
+ *
+ * Consent: nothing extra to wire. <ConsentInit> sets the Consent Mode v2
+ * defaults synchronously ahead of these, the Meta and TikTok snippets read
+ * the shared consent cookie before they are allowed to write cookies, and
+ * `applyConsent()` relays a live decision to all three vendors. Mount this
+ * AFTER <ConsentInit> and the gate holds.
+ *
+ * Google is deliberately ONE tag with two destinations rather than two
+ * loaders — see the comment block in ./ga4.tsx. It is also why the Ads
+ * conversion inherits the consent gate for free.
+ *
+ * Server component: pass a `client` and it fetches the config (cached),
+ * or pass an already-fetched `config` when the layout has one in hand.
+ * Renders nothing for a vendor the store has not configured, so a store
+ * running only GA4 ships exactly one tag.
+ */
+export async function StorefrontTags({
+  client,
+  config,
+}: {
+  /** Used to fetch the tracking config when `config` is not supplied. */
+  client?: StorefrontClient
+  /** Pre-fetched tracking block, e.g. from a layout that already has it. */
+  config?: TrackingConfig
+}) {
+  let tracking: TrackingConfig | undefined = config
+  if (!tracking) {
+    if (!client) return null
+    try {
+      tracking = await getTrackingConfig(client)
+    } catch {
+      // A tracking-config failure must never take a storefront down.
+      return null
+    }
+  }
+
+  return (
+    <>
+      <MetaPixel pixelId={tracking.facebookPixel?.pixelId} />
+      <TikTokPixel pixelId={tracking.tiktok?.pixelId} />
+      <GoogleTag
+        measurementId={tracking.ga4?.measurementId}
+        adsConversionId={tracking.googleAds?.conversionId}
+      />
+      <Gtm containerId={tracking.gtm?.containerId} />
+    </>
+  )
+}

package/src/tracking/tiktok-pixel.tsx

@@ -0,0 +1,83 @@
+"use client"
+
+import Script from "next/script"
+
+import { CONSENT_COOKIE } from "./consent"
+import { jsStringLiteral } from "./inline-script"
+
+/**
+ * TikTokPixel — client-side base pixel injector, the TikTok twin of
+ * <MetaPixel>.
+ *
+ * Injects TikTok's own base snippet with `<Script
+ * strategy="afterInteractive">`, resolves consent from the `_1c_consent`
+ * cookie BEFORE the pixel is allowed to write cookies, then loads and
+ * fires the initial page view.
+ *
+ * Consent model. TikTok's base code registers `holdConsent`,
+ * `grantConsent` and `revokeConsent` on `ttq` alongside `page` and
+ * `track`, and `setAndDefer` queues every call onto the `ttq` array
+ * before the SDK is fetched. So the Meta pattern transfers exactly:
+ *
+ *     ttq.holdConsent()   // queued before load — cookies withheld
+ *     ttq.load(pixelId)
+ *     ttq.page()
+ *     ttq.grantConsent()  // visitor accepted marketing
+ *     ttq.revokeConsent() // visitor declined, or withdrew later
+ *
+ * HOLDING rather than withholding the script is the point, and it is the
+ * same reasoning as the Meta gate above it: under load-on-consent, a
+ * visitor who browses three products and only then accepts gives TikTok
+ * nothing for those three pages. Holding queues them and the grant
+ * releases them.
+ *
+ * Live decisions arrive through `applyConsent()` in ./consent.ts, which
+ * relays to gtag, fbq and ttq together — there is no cookie watcher.
+ *
+ * One dependency outside the code: Cookie Consent Mode must be switched
+ * on for this pixel in TikTok Events Manager. With it off, `holdConsent`
+ * is an inert queued call and the pixel behaves like any unconsented
+ * pixel — no error, no crash, and no gate. That switch belongs to whoever
+ * owns the ad account.
+ *
+ * Renders nothing when `pixelId` is falsy, so a layout can mount it
+ * unconditionally.
+ */
+export function TikTokPixel({ pixelId }: { pixelId?: string }) {
+  if (!pixelId) return null
+
+  const id = jsStringLiteral(pixelId)
+
+  const initSnippet = `
+!function (w, d, t) {
+  w.TiktokAnalyticsObject=t;
+  var ttq=w[t]=w[t]||[];
+  ttq.methods=["page","track","identify","instances","debug","on","off","once","ready","alias","group","enableCookie","disableCookie","holdConsent","revokeConsent","grantConsent"];
+  ttq.setAndDefer=function(t,e){t[e]=function(){t.push([e].concat(Array.prototype.slice.call(arguments,0)))}};
+  for(var i=0;i<ttq.methods.length;i++)ttq.setAndDefer(ttq,ttq.methods[i]);
+  ttq.instance=function(t){var e=ttq._i[t]||[];for(var n=0;n<ttq.methods.length;n++)ttq.setAndDefer(e,ttq.methods[n]);return e};
+  ttq.load=function(e,n){var r="https://analytics.tiktok.com/i18n/pixel/events.js";ttq._i=ttq._i||{},ttq._i[e]=[],ttq._i[e]._u=r,ttq._t=ttq._t||{},ttq._t[e]=+new Date,ttq._o=ttq._o||{},ttq._o[e]=n||{};var o=d.createElement("script");o.type="text/javascript",o.async=!0,o.src=r+"?sdkid="+e+"&lib="+t;var a=d.getElementsByTagName("script")[0];a.parentNode.insertBefore(o,a)};
+
+  ttq.holdConsent();
+  ttq.load(${id});
+  ttq.page();
+
+  (function(){
+    var ads=false;
+    try{
+      var m=d.cookie.match(/(?:^|; )${CONSENT_COOKIE}=([^;]*)/);
+      if(m){ads=!!JSON.parse(decodeURIComponent(m[1])).ads;}
+    }catch(e){}
+    if(ads){ttq.grantConsent();}else{ttq.revokeConsent();}
+  })();
+}(window, document, 'ttq');
+`.trim()
+
+  return (
+    <Script
+      id="tiktok-pixel-init"
+      strategy="afterInteractive"
+      dangerouslySetInnerHTML={{ __html: initSnippet }}
+    />
+  )
+}

package/src/tracking/track-init.tsx

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