@cartbase/storefront 0.6.0 → 0.8.0

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/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

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

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

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