@cartbase/storefront 0.7.0 → 0.9.0

package/src/tracking/consent.ts

@@ -131,6 +131,18 @@ export function applyConsent(choices: ConsentChoices): void {
     if (choices.ads) w.ttq.grantConsent()
     else w.ttq.revokeConsent()
   }
+
+  // ChatGPT Ads. One command on their own queue, `oaiq("consent", bool)`,
+  // which works before the SDK has arrived because the queue buffers it.
+  //
+  // A grant also fires the page view the loader withheld: their docs say
+  // an unconsented event sends no ping and do not promise that a held call
+  // is released later, so the visitor who accepts on their third page is
+  // counted from the grant onward rather than not at all.
+  if (typeof w.oaiq === "function") {
+    w.oaiq("consent", choices.ads)
+    if (choices.ads) w.oaiq("measure", "page_viewed", { type: "contents" })
+  }
 }
 
 /**

package/src/tracking/events.ts

@@ -24,6 +24,14 @@ import {
   trackTikTokPurchase,
   trackTikTokViewContent,
 } from "./ttq"
+import {
+  minorUnits,
+  trackOpenAiCheckoutStarted,
+  trackOpenAiContentsViewed,
+  trackOpenAiItemsAdded,
+  trackOpenAiOrderCreated,
+  type OpenAiContentItem,
+} from "./oaiq"
 import { googleAdsPurchaseSendTo, trackGoogleAdsPurchase } from "./google-ads"
 import type { TrackingConfig } from "./types"
 
@@ -118,6 +126,25 @@ const tiktokContents = (lines: TrackedLine[]) =>
 const unitCount = (lines: TrackedLine[]) =>
   lines.reduce((sum, line) => sum + (Number(line.quantity) || 0), 0)
 
+/**
+ * ChatGPT Ads contents. The shape is close to TikTok's, but every amount
+ * is an INTEGER IN MINOR UNITS on this vendor, which is why the mapping
+ * cannot be shared with `tiktokContents` above: the same numbers in the
+ * same field names would be a hundredfold under-report.
+ */
+const openAiContents = (
+  lines: TrackedLine[],
+  currency: string
+): OpenAiContentItem[] =>
+  lines.map((line) => ({
+    id: line.productId,
+    name: line.title,
+    content_type: "product",
+    quantity: line.quantity,
+    amount: minorUnits(line.price),
+    currency,
+  }))
+
 /** Product page view. */
 export function trackProductView(input: {
   line: TrackedLine
@@ -137,6 +164,12 @@ export function trackProductView(input: {
     currency,
     value,
   })
+  trackOpenAiContentsViewed({
+    contentId: line.productId,
+    contentName: line.title,
+    currency,
+    value,
+  })
   trackGAViewItem({ currency, value, items: gaItems([line], currency) })
   trackRybbitViewItem({
     item_id: line.variantId || line.productId,
@@ -168,6 +201,14 @@ export function trackCartAdd(input: {
     currency,
     value,
   })
+  trackOpenAiItemsAdded({
+    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,
@@ -199,6 +240,11 @@ export function trackCheckoutStart(input: {
     currency,
     value,
   })
+  trackOpenAiCheckoutStarted({
+    contents: openAiContents(lines, currency),
+    currency,
+    value,
+  })
   trackGABeginCheckout({
     currency,
     value,
@@ -222,8 +268,9 @@ export function trackCheckoutStart(input: {
  * 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.
+ * `purchase_<displayId>`, TikTok on `tt_purchase_<displayId>`, ChatGPT Ads
+ * on `oai_order_<displayId>`, GA4 and Google Ads on the transaction id,
+ * which is `displayId` itself.
  */
 export function trackOrderPurchase(
   order: TrackedOrder,
@@ -261,6 +308,13 @@ export function trackOrderPurchase(
     customerType,
   })
 
+  trackOpenAiOrderCreated({
+    contents: openAiContents(lines, currency),
+    currency,
+    value,
+    displayId,
+  })
+
   trackGAPurchase({
     transaction_id: transactionId,
     currency,

package/src/tracking/get-tracking-attribution.ts

@@ -4,6 +4,14 @@ 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"
+import {
+  LEGACY_UTM_FIRST_COOKIE,
+  LEGACY_UTM_LAST_COOKIE,
+  LEGACY_VISITOR_COOKIE,
+  UTM_FIRST_COOKIE,
+  UTM_LAST_COOKIE,
+  VISITOR_COOKIE,
+} from "../lib/cookie-names"
 
 /**
  * Reads Meta + GA4 attribution signals from the current Next.js server
@@ -73,14 +81,19 @@ export async function getTrackingAttribution(
     // attribution.ts on first tracking call. Surfaces server-side here
     // so the order.placed CAPI Purchase can include it as external_id
     // (alongside customer_id when both exist — Meta accepts an array).
-    anonId = cookieStore.get("_1c_anon")?.value
+    anonId =
+      cookieStore.get(VISITOR_COOKIE)?.value ?? cookieStore.get(LEGACY_VISITOR_COOKIE)?.value
     gaCookieRaw = cookieStore.get("_ga")?.value
     // _1c_utm_first / _1c_utm_last — JSON-encoded UTM tuples written
     // by browser-side captureUtmsFromUrl(). First-touch records the
     // acquisition campaign (365-day TTL); last-touch records the
     // closer (90-day TTL, refreshed on each UTM-bearing visit).
-    utmFirstRaw = cookieStore.get("_1c_utm_first")?.value
-    utmLastRaw = cookieStore.get("_1c_utm_last")?.value
+    utmFirstRaw =
+      cookieStore.get(UTM_FIRST_COOKIE)?.value ??
+      cookieStore.get(LEGACY_UTM_FIRST_COOKIE)?.value
+    utmLastRaw =
+      cookieStore.get(UTM_LAST_COOKIE)?.value ??
+      cookieStore.get(LEGACY_UTM_LAST_COOKIE)?.value
 
     // _ga_<MEASUREMENT_ID> uses the GA4 measurementId (e.g., G-ABCDEF1234)
     // with the "G-" prefix stripped: cookie name = `_ga_ABCDEF1234`.

package/src/tracking/index.ts

@@ -18,6 +18,10 @@
  *     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
+ *   - <PageViews /> — one pageview per navigation, client-side ones
+ *     included; the platform derives page type + entity id from the path
+ *   - <LiveHeartbeat /> — pings while a tab is open, so the merchant's live
+ *     visitor count means "right now" rather than "recently active"
  *     (they exist only there) and starts the engagement clock.
  *   - <MetaPixel pixelId> / <GoogleTag measurementId adsConversionId> /
  *     <TikTokPixel pixelId> / <Gtm containerId> / <Rybbit siteId> —
@@ -53,8 +57,16 @@ export { MetaPixel, updatePixelAdvancedMatching } from "./meta-pixel"
 export { GA4, GoogleTag } from "./ga4"
 export { Gtm } from "./gtm"
 export { TikTokPixel } from "./tiktok-pixel"
+export { ChatGptPixel } from "./chatgpt-pixel"
 export { StorefrontTags } from "./storefront-tags"
 export { TrackInit } from "./track-init"
+// The live-visitor heartbeat. Mounted by <StorefrontTags> so a storefront
+// gets it without knowing it exists.
+export { LiveHeartbeat } from "./live-heartbeat"
+// Every navigation, automatically. Mounted by <StorefrontTags>; the page
+// type and the record it was about are derived by the platform, never
+// declared here.
+export { PageViews } from "./page-views"
 export { TrackOrderPurchase } from "./track-order-purchase"
 export { Rybbit } from "./rybbit"
 export { ConsentInit } from "./consent-init"
@@ -123,6 +135,17 @@ export {
   tiktokPurchaseEventId,
   type TikTokContentItem,
 } from "./ttq"
+export {
+  trackOpenAiPageView,
+  trackOpenAiContentsViewed,
+  trackOpenAiItemsAdded,
+  trackOpenAiCheckoutStarted,
+  trackOpenAiOrderCreated,
+  applyOpenAiConsent,
+  openAiOrderEventId,
+  minorUnits,
+  type OpenAiContentItem,
+} from "./oaiq"
 export {
   trackGoogleAdsPurchase,
   googleAdsPurchaseSendTo,

package/src/tracking/live-heartbeat.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+import { useEffect } from "react"
+
+import { getTabSessionId, platformCollectorPresent, readVisitorId } from "../lib/visitor"
+
+/**
+ * The live-visitor heartbeat.
+ *
+ * While this tab is open it pings the store's own domain every 15 seconds.
+ * The platform counts a visitor as present while their last ping is inside
+ * a 30 second window, so a closed tab, a killed browser, a dropped network
+ * or a locked phone all disappear within half a minute with nothing to
+ * detect them — no unload handler, which browsers do not guarantee anyway,
+ * especially on mobile.
+ *
+ * Why a heartbeat instead of counting recent events: a shopper reading one
+ * product page for four minutes sends nothing in between, so an
+ * event-window count either forgets them or keeps counting people who left.
+ * A ping answers "who is on the store right now" literally.
+ *
+ * The path is first-party (`/_cb/heartbeat` on the merchant's own domain),
+ * which is what keeps it out of ad blockers and away from third-party
+ * cookie rules. The platform's injected proxy forwards it.
+ *
+ * Costs nothing when it fails: every call is fire-and-forget with keepalive,
+ * a dropped ping is one missing dot on a chart.
+ */
+const HEARTBEAT_MS = 15_000
+const ENDPOINT = "/_cb/heartbeat"
+
+export function LiveHeartbeat() {
+  useEffect(() => {
+    // The deploy-injected collector already does this on every page.
+    if (platformCollectorPresent()) return
+    const session = getTabSessionId()
+
+    const ping = () => {
+      const body = JSON.stringify({
+        session_id: session,
+        device_id: readVisitorId(),
+        // Path only. The platform drops query strings as well, because
+        // signed document links and login codes travel in them.
+        path: window.location.pathname,
+      })
+      void fetch(ENDPOINT, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body,
+        keepalive: true,
+      }).catch(() => undefined)
+    }
+
+    ping()
+    // No visibility handling on purpose (the live-polling law): browsers
+    // already throttle timers in a hidden tab, and anything that guesses at
+    // attention will eventually guess wrong.
+    const timer = setInterval(ping, HEARTBEAT_MS)
+    return () => clearInterval(timer)
+  }, [])
+
+  return null
+}

package/src/tracking/oaiq.ts

@@ -0,0 +1,206 @@
+"use client"
+
+/**
+ * Typed wrappers around the global `oaiq` command queue from the OpenAI
+ * measurement pixel — the ChatGPT Ads twin of ./ttq.ts and ./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.oaiq` is absent (pixel not configured,
+ * server render, script blocked), so callers need no guards.
+ *
+ * The call signature is theirs, from
+ * https://developers.openai.com/ads/measurement-pixel:
+ *
+ *     oaiq("measure", eventName, eventData, { event_id })
+ *
+ * Two things here are NOT like the other vendors, and both are silent when
+ * wrong:
+ *
+ *   1. MONEY IS AN INTEGER IN MINOR UNITS. Meta, TikTok and GA4 all read
+ *      `value: 25.99`; OpenAI reads `amount: 2599`. Passing a decimal
+ *      under-reports revenue by a factor of a hundred with nothing to show
+ *      for it, so every amount goes through `minorUnits` below and no
+ *      caller passes `amount` itself.
+ *   2. EVENT DATA CARRIES ITS OWN `type`. Each event name is bound to one
+ *      of four data shapes; the five commerce events we fire all take
+ *      `contents`, so the wrappers set it and callers cannot get it wrong.
+ *
+ * Event names are theirs and are not interchangeable with Meta's or
+ * TikTok's: `contents_viewed`, `items_added`, `checkout_started`,
+ * `order_created`, `page_viewed`.
+ */
+
+/** One product line inside `contents`. */
+export type OpenAiContentItem = {
+  id: string
+  name?: string
+  content_type?: string
+  quantity?: number
+  /** Integer, minor units. */
+  amount?: number
+  currency?: string
+}
+
+type OpenAiEventData = {
+  type: "contents"
+  /** Integer, minor units. */
+  amount?: number
+  currency?: string
+  contents?: OpenAiContentItem[]
+}
+
+type OaiqFn = (
+  command: "init" | "measure" | "consent",
+  ...args: unknown[]
+) => void
+
+function safeOaiq(): OaiqFn | null {
+  if (typeof window === "undefined") return null
+  const oaiq = (window as unknown as { oaiq?: OaiqFn }).oaiq
+  return typeof oaiq === "function" ? oaiq : null
+}
+
+/**
+ * Major units to their integer minor units: 25.99 becomes 2599.
+ *
+ * The twin of `openAiMinorUnits` in the platform's
+ * src/lib/tracking/constants.ts. Duplicated rather than imported because
+ * this package cannot reach into the platform, and rounded rather than
+ * truncated because 0.1 + 0.2 is 0.30000000000000004 in binary floating
+ * point and truncation would report 29 cents for 30.
+ */
+export function minorUnits(amountInMajorUnits: number): number {
+  return Math.round((Number(amountInMajorUnits) || 0) * 100)
+}
+
+/**
+ * THE order dedup key — must equal what the backend forwarder sends
+ * (`openAiOrderEventId` in the platform's 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 and
+ * `tiktokPurchaseEventId` for TikTok.
+ *
+ * OpenAI deduplicates on pixel id + event name + id, keeping the FIRST
+ * event it receives, so the browser and the server collapse into one
+ * conversion whichever arrives first.
+ */
+export function openAiOrderEventId(displayId: string | number): string {
+  return `oai_order_${displayId}`
+}
+
+/** A page view. Their pixel fires nothing on its own at init. */
+export function trackOpenAiPageView(): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "page_viewed", { type: "contents" } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiContentsViewed(data: {
+  contentId: string
+  contentName?: string
+  currency: string
+  /** Major units — converted here. */
+  value: number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "contents_viewed", {
+    type: "contents",
+    amount: minorUnits(data.value),
+    currency: data.currency,
+    contents: [
+      {
+        id: data.contentId,
+        name: data.contentName,
+        content_type: "product",
+        quantity: 1,
+      },
+    ],
+  } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiItemsAdded(data: {
+  contentId: string
+  contentName?: string
+  quantity: number
+  /** Unit price, major units. */
+  price: number
+  currency: string
+  /** Line value, major units. */
+  value: number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "items_added", {
+    type: "contents",
+    amount: minorUnits(data.value),
+    currency: data.currency,
+    contents: [
+      {
+        id: data.contentId,
+        name: data.contentName,
+        content_type: "product",
+        quantity: data.quantity,
+        amount: minorUnits(data.price),
+        currency: data.currency,
+      },
+    ],
+  } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiCheckoutStarted(data: {
+  contents: OpenAiContentItem[]
+  currency: string
+  /** Cart value, major units. */
+  value: number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("measure", "checkout_started", {
+    type: "contents",
+    amount: minorUnits(data.value),
+    currency: data.currency,
+    contents: data.contents,
+  } satisfies OpenAiEventData)
+}
+
+export function trackOpenAiOrderCreated(data: {
+  contents: OpenAiContentItem[]
+  currency: string
+  /** Order total, major units. */
+  value: number
+  /** The order's display id — the dedup key shared with the server. */
+  displayId: string | number
+}): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq(
+    "measure",
+    "order_created",
+    {
+      type: "contents",
+      amount: minorUnits(data.value),
+      currency: data.currency,
+      contents: data.contents,
+    } satisfies OpenAiEventData,
+    { event_id: openAiOrderEventId(data.displayId) }
+  )
+}
+
+/**
+ * Push a live consent decision to the pixel.
+ *
+ * Normally you do NOT call this: `applyConsent()` in ./consent.ts relays
+ * every decision to gtag, fbq, ttq and oaiq together. Exported for a host
+ * app driving the pixel from a consent layer of its own.
+ *
+ * Their own gate, from the measurement-pixel docs: with consent false the
+ * pixel sends no measurement pings, and the default is TRUE, which is why
+ * the loader closes it explicitly before init rather than trusting it.
+ */
+export function applyOpenAiConsent(adsGranted: boolean): void {
+  const oaiq = safeOaiq()
+  if (!oaiq) return
+  oaiq("consent", adsGranted)
+}

package/src/tracking/page-views.tsx

@@ -0,0 +1,96 @@
+"use client"
+
+import { Suspense, useEffect, useRef } from "react"
+import { usePathname, useSearchParams } from "next/navigation"
+
+import { getTabSessionId, platformCollectorPresent, readVisitorId } from "../lib/visitor"
+import { readConsentCookie } from "./consent"
+
+/**
+ * PAGEVIEWS — every route, automatically.
+ *
+ * Mounted once by <StorefrontTags>, this fires on every navigation the
+ * router performs, client-side ones included. That is the whole design:
+ * NOT a list of instrumented pages. Home, collections, blog posts, content
+ * pages, search, account and 404s are all captured without a single
+ * per-page call, which is the only shape that survives an agent inventing
+ * routes the platform has never seen.
+ *
+ * WHAT IT DELIBERATELY DOES NOT SEND: what the page IS. No `pageType` prop,
+ * no per-page declaration. The platform derives the page type and the id of
+ * the record the page was about from the path and its own catalog, because
+ * a declaration is a guarantee living in merchant code, and merchant code
+ * forgets. A route nobody anticipated still resolves, because the last path
+ * segment is looked up as a handle in the store's own catalog.
+ *
+ * The path is first-party (`/_cb/pageview` on the merchant's own domain),
+ * which keeps it out of ad blockers and away from third-party cookie rules.
+ *
+ * Query VALUES never leave the browser: only the keys travel, because a
+ * search term is shopper input and signed links live in query strings.
+ */
+const ENDPOINT = "/_cb/pageview"
+
+function PageViewsInner() {
+  const pathname = usePathname()
+  const searchParams = useSearchParams()
+  // The referrer for a client-side navigation is the page you came FROM,
+  // which the browser cannot tell us — document.referrer only ever holds
+  // the page that loaded the app.
+  const lastPath = useRef<string | null>(null)
+
+  const search = searchParams?.toString() ?? ""
+
+  useEffect(() => {
+    if (!pathname) return
+    // The deploy-injected collector already reports every navigation.
+    if (platformCollectorPresent()) return
+
+    const previous = lastPath.current
+    lastPath.current = pathname
+
+    const consent = readConsentCookie()
+    const referrer = previous
+      ? `${window.location.origin}${previous}`
+      : typeof document !== "undefined" && document.referrer
+        ? document.referrer
+        : undefined
+
+    const body = JSON.stringify({
+      path: pathname,
+      query_keys: search ? Array.from(new URLSearchParams(search).keys()).slice(0, 20) : undefined,
+      referrer,
+      title: typeof document !== "undefined" ? document.title : undefined,
+      session_id: getTabSessionId(),
+      device_id: readVisitorId(),
+      // undefined when the store runs no banner, which the platform reads
+      // as "nothing to honour" rather than as a refusal.
+      consent: consent ? consent.analytics : undefined,
+    })
+
+    void fetch(ENDPOINT, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body,
+      keepalive: true,
+    }).catch(() => undefined)
+    // `search` is in the deps on purpose: a filter or a search query change
+    // is a new pageview, and a merchant reading a search report needs it.
+  }, [pathname, search])
+
+  return null
+}
+
+/**
+ * The Suspense boundary is INSIDE the component, not left to the consumer.
+ * `useSearchParams` opts a page out of static rendering unless it sits
+ * under one, and a storefront must not be able to lose its own static
+ * pages by mounting analytics. Nobody can wire this wrong.
+ */
+export function PageViews() {
+  return (
+    <Suspense fallback={null}>
+      <PageViewsInner />
+    </Suspense>
+  )
+}