@cartbase/storefront 0.7.0 → 0.8.0

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

package/src/tracking/storefront-tags.tsx

@@ -1,67 +1,75 @@
-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} />
-    </>
-  )
-}
+import { GoogleTag } from "./ga4"
+import { LiveHeartbeat } from "./live-heartbeat"
+import { PageViews } from "./page-views"
+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 (
+    <>
+      {/* Cartbase's own analytics, always on and never a merchant setting:
+          it is what feeds the merchant's own dashboard, so it does not
+          depend on any vendor id being configured. The vendor tags below
+          only appear when the merchant has entered their ids. */}
+      <PageViews />
+      <LiveHeartbeat />
+      <MetaPixel pixelId={tracking.facebookPixel?.pixelId} />
+      <TikTokPixel pixelId={tracking.tiktok?.pixelId} />
+      <GoogleTag
+        measurementId={tracking.ga4?.measurementId}
+        adsConversionId={tracking.googleAds?.conversionId}
+      />
+      <Gtm containerId={tracking.gtm?.containerId} />
+    </>
+  )
+}