@tokenoftrust/storefront-runner 4.9.3 → 4.10.0

package/packages/public-runtime/src/integration/lifecycle-boot.ts

@@ -59,8 +59,8 @@ import {
 import { schedulePostPaint, type PostPaintWindow } from "./post-paint.js";
 import { scheduleGa4Sandbox, type Ga4SandboxScheduleWindow } from "./ga4-sandbox-schedule.js";
 import { ManagedAnalyticsEventBrokerBridge } from "./managed-analytics-bridge.js";
-import { minimizePageAttribution, type ManagedPageViewInput } from "./managed-analytics.js";
-import { managedAnalyticsOpaqueRevision } from "./managed-analytics-value-safety.js";
+import { minimizePageAttribution, readGoogleAdsClickIds, type ManagedPageViewInput } from "./managed-analytics.js";
+import { managedAnalyticsOpaqueRevision, type GoogleAdsClickIds } from "./managed-analytics-value-safety.js";
 import {
   CONTACT_SALES_ACTION_REGISTRY,
   createContactSalesActionSource,
@@ -349,13 +349,13 @@ function defaultConsentGate(
 }
 
 /**
- * Whether the tenant's EU/UK visitor policy governs this document: the edge classed the
- * visitor as EU/EEA/UK/CH or could not class them, and the tenant has not taken `full`
- * responsibility. A missing state global applies it (fail closed).
+ * Whether the tenant's EU/UK visitor policy governs this document, as the early consent
+ * boot decided it (`regionRestricted`). Only an explicit `false` lifts it: a missing
+ * state global or a missing or non-boolean flag applies it (fail closed).
  */
 function euUkPolicyApplies(win: LifecycleWindow): boolean {
-  const state = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined;
-  return !state || (state.region !== "other" && state.euUkVisitors !== "full");
+  const state = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as Partial<ViewerAnalyticsConsentState> | undefined;
+  return state?.regionRestricted !== false;
 }
 
 /**
@@ -367,6 +367,39 @@ function persistentVisitorStorage(win: LifecycleWindow): boolean {
   return state?.visitorStorage === "persistent";
 }
 
+/**
+ * Whether landing click identifiers may reach GA4: the visitor is known to be outside
+ * the EU/UK and analytics may keep them on this device. GPC, a saved denial, `count-only`,
+ * an unknown region, and an EU/UK visitor under any tenant policy all forward nothing.
+ * A missing state global allows nothing (fail closed).
+ */
+function landingClickIdsAllowed(win: LifecycleWindow): boolean {
+  const state = win[VIEWER_ANALYTICS_CONSENT_STATE_GLOBAL] as ViewerAnalyticsConsentState | undefined;
+  return state?.visitorStorage === "persistent" && state.region === "other";
+}
+
+/** Windows whose landing click identifiers already went out; a back-forward restore never resends them. */
+const landingClickIdsTaken = new WeakSet<object>();
+
+/**
+ * The GA4 host capability over this document's landing URL: identifiers are read once,
+ * when the lifecycle is built, and released once, to the page view of the landing path,
+ * only while {@link landingClickIdsAllowed} holds at that moment.
+ */
+function landingClickIdSource(
+  win: LifecycleWindow,
+  tenantPublicId: string,
+): ((path: string) => GoogleAdsClickIds | undefined) | undefined {
+  const clickIds = readGoogleAdsClickIds(win.location.href);
+  if (!clickIds) return undefined;
+  const landingPath = canonicalDocumentPath(win.location.pathname, tenantPublicId);
+  return (path) => {
+    if (path !== landingPath || landingClickIdsTaken.has(win) || !landingClickIdsAllowed(win)) return undefined;
+    landingClickIdsTaken.add(win);
+    return clickIds;
+  };
+}
+
 /**
  * Under the EU/UK policy only a reviewed platform adapter may run: its
  * visitor storage goes through this host's continuity seam, which then keeps nothing on
@@ -500,6 +533,7 @@ function createDocumentLifecycle(
           ? win["localStorage"] as VisitorContinuityStorage | undefined
           : undefined),
     }),
+    takeLandingClickIds: landingClickIdSource(win, descriptor.tenantPublicId),
     nativeGa4Transport: () => {
       if (options.nativeGa4Transport) return options.nativeGa4Transport;
       if (typeof document === "undefined" || typeof MessageChannel === "undefined") {

package/packages/public-runtime/src/integration/managed-analytics-value-safety.ts

@@ -1,12 +1,95 @@
 /** Shared PII-value canary for managed browser events and their diagnostics. */
-import { MANAGED_ANALYTICS_PII_VALUE_PATTERN } from "./managed-analytics-api-v1-safety.mjs";
+import {
+  MANAGED_ANALYTICS_PII_VALUE_PATTERN,
+  MANAGED_ANALYTICS_SECRET_VALUE_PATTERN,
+} from "./managed-analytics-api-v1-safety.mjs";
 import { fnv1a128Hex } from "./digest.js";
 
 const MANAGED_ANALYTICS_PII_VALUE = new RegExp(MANAGED_ANALYTICS_PII_VALUE_PATTERN);
+const MANAGED_ANALYTICS_SECRET_VALUE = new RegExp(MANAGED_ANALYTICS_SECRET_VALUE_PATTERN);
 const MANAGED_ANALYTICS_PROTECTED_VALUE =
   /(?:@|\d{7,}|(?:^|[./_~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[./_~-]))/i;
 const OPAQUE_HEX_ALPHABET = "abcdefghijklmnop";
 
+/** The five standard UTM fields, without their `utm_` prefix. */
+export const MANAGED_ANALYTICS_CAMPAIGN_FIELDS = ["source", "medium", "campaign", "term", "content"] as const;
+export type ManagedAnalyticsCampaignField = (typeof MANAGED_ANALYTICS_CAMPAIGN_FIELDS)[number];
+export type ManagedAnalyticsCampaign = Partial<Record<ManagedAnalyticsCampaignField, string>>;
+
+/** A dropped campaign field. It names the field and the reason, never the value. */
+export interface ManagedAnalyticsCampaignRejection {
+  field: ManagedAnalyticsCampaignField;
+  reason: "format" | "protected_value";
+}
+
+export interface ManagedAnalyticsCampaignScreen {
+  kept: ManagedAnalyticsCampaign;
+  rejected: ManagedAnalyticsCampaignRejection[];
+}
+
+const CAMPAIGN_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
+/** Credential words as a whole token segment. `token` and `preview` are ordinary campaign words. */
+const CAMPAIGN_CREDENTIAL_WORD = /(?:^|[._~-])(?:bearer|password|secret|authorization|credential)(?:$|[._~-])/i;
+/** A labelled token may carry a 7-8 digit stamp (`_20261027`); a longer run could be a dialable number. */
+const CAMPAIGN_LONG_DIGIT_RUN = /\d{9,}/;
+/**
+ * A bare number is never a campaign token. A Google Ads ValueTrack `{campaignid}` has the
+ * same shape as an international phone number written without `+`, and neither `utm_source`
+ * nor length separates them, so it is rejected; GA4 still attributes Ads traffic by click id.
+ */
+const CAMPAIGN_BARE_DIGITS = /^\d{7,}$/;
+
+function campaignTokenRejection(value: unknown): ManagedAnalyticsCampaignRejection["reason"] | undefined {
+  if (typeof value !== "string" || !CAMPAIGN_TOKEN.test(value)) return "format";
+  if (
+    resemblesManagedAnalyticsPii(value) || MANAGED_ANALYTICS_SECRET_VALUE.test(value) ||
+    CAMPAIGN_CREDENTIAL_WORD.test(value)
+  ) return "protected_value";
+  return CAMPAIGN_BARE_DIGITS.test(value) || CAMPAIGN_LONG_DIGIT_RUN.test(value) ? "protected_value" : undefined;
+}
+
+/**
+ * The one campaign-token policy for every layer that carries UTM values: minimization,
+ * event validation, the GA4 parent and sandbox, and Amplitude. Each present field is kept
+ * or rejected on its own, so one unsafe value never costs the page view its other fields.
+ */
+export function screenManagedAnalyticsCampaign(utm: Readonly<Record<string, unknown>>): ManagedAnalyticsCampaignScreen {
+  const kept: ManagedAnalyticsCampaign = {};
+  const rejected: ManagedAnalyticsCampaignRejection[] = [];
+  for (const field of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
+    if (!Object.hasOwn(utm, field)) continue;
+    const value = utm[field];
+    const reason = campaignTokenRejection(value);
+    if (reason) rejected.push({ field, reason });
+    else kept[field] = value as string;
+  }
+  return { kept, rejected };
+}
+
+/** The Google Ads click identifiers a landing URL may carry to GA4. */
+export const GOOGLE_ADS_CLICK_ID_KEYS = ["gclid", "gbraid", "wbraid"] as const;
+export type GoogleAdsClickIdKey = (typeof GOOGLE_ADS_CLICK_ID_KEYS)[number];
+export type GoogleAdsClickIds = Partial<Record<GoogleAdsClickIdKey, string>>;
+
+/** Auto-tagging writes URL-safe base64; the length bound only caps hostile input. */
+const GOOGLE_ADS_CLICK_ID = /^[A-Za-z0-9_-]{1,512}$/;
+
+/** A click identifier safe to place on a GA4 `page_location`: URL-safe, bounded, and not PII- or secret-shaped. */
+export function isGoogleAdsClickIdValue(value: unknown): value is string {
+  return typeof value === "string" && GOOGLE_ADS_CLICK_ID.test(value) &&
+    !resemblesManagedAnalyticsPii(value) && !MANAGED_ANALYTICS_SECRET_VALUE.test(value);
+}
+
+/** A non-empty record of known click-identifier keys, every value valid. */
+export function isGoogleAdsClickIds(value: unknown): value is GoogleAdsClickIds {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== Object.prototype && proto !== null) return false;
+  const entries = Object.entries(value);
+  return entries.length > 0 && entries.every(([key, id]) =>
+    (GOOGLE_ADS_CLICK_ID_KEYS as readonly string[]).includes(key) && isGoogleAdsClickIdValue(id));
+}
+
 /** True when a public string resembles an email, SSN, payment card, or phone number. */
 export function resemblesManagedAnalyticsPii(value: unknown): boolean {
   return typeof value === "string" && MANAGED_ANALYTICS_PII_VALUE.test(value);

package/packages/public-runtime/src/integration/managed-analytics.ts

@@ -16,6 +16,13 @@ import {
   type ContractResult,
 } from "./result.js";
 import { findForbiddenFields } from "./secrets.js";
+import {
+  GOOGLE_ADS_CLICK_ID_KEYS,
+  isGoogleAdsClickIdValue,
+  MANAGED_ANALYTICS_CAMPAIGN_FIELDS,
+  screenManagedAnalyticsCampaign,
+  type GoogleAdsClickIds,
+} from "./managed-analytics-value-safety.js";
 import type { CommerceEmitResult, CommerceEventBroker } from "./commerce-broker.js";
 import {
   APPROVED_MARKETING_ACTION_NAMES,
@@ -125,27 +132,11 @@ export interface AttributionSourceInput {
   routeUrl?: string | null;
 }
 
-const UTM_QUERY_FIELDS = [
-  ["utm_source", "source"],
-  ["utm_medium", "medium"],
-  ["utm_campaign", "campaign"],
-  ["utm_term", "term"],
-  ["utm_content", "content"],
-] as const;
-const SAFE_CAMPAIGN_TOKEN = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
-const PROTECTED_CAMPAIGN_TOKEN =
-  /(?:@|\d{7,}|(?:^|[._~-])(?:bearer|password|secret|token|authorization|preview)(?:$|[._~-]))/i;
-
-function safeCampaignToken(value: string): string | undefined {
-  return SAFE_CAMPAIGN_TOKEN.test(value) && !PROTECTED_CAMPAIGN_TOKEN.test(value)
-    ? value
-    : undefined;
-}
-
 /**
  * Reduce explicit URL inputs to an origin-only referrer and the five standard UTM
- * tokens. Query keys outside the UTM allowlist, duplicate keys, unsafe free-form
- * values, credentials, paths, and fragments are discarded. No browser global is read.
+ * tokens. Query keys outside the UTM allowlist, duplicate keys, values the shared
+ * campaign policy rejects (`screenManagedAnalyticsCampaign`), credentials, paths, and
+ * fragments are discarded. No browser global is read.
  */
 export function minimizePageAttribution(input: AttributionSourceInput): ManagedPageAttribution | undefined {
   const result: ManagedPageAttribution = {};
@@ -168,14 +159,13 @@ export function minimizePageAttribution(input: AttributionSourceInput): ManagedP
   if (input.routeUrl) {
     try {
       const route = new URL(input.routeUrl, "https://route.invalid");
-      const utm: NonNullable<ManagedPageAttribution["utm"]> = {};
-      for (const [queryName, field] of UTM_QUERY_FIELDS) {
-        const values = route.searchParams.getAll(queryName);
-        if (values.length !== 1) continue;
-        const value = safeCampaignToken(values[0] ?? "");
-        if (value !== undefined) utm[field] = value;
+      const query: Record<string, string> = {};
+      for (const field of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
+        const values = route.searchParams.getAll(`utm_${field}`);
+        if (values.length === 1) query[field] = values[0]!;
       }
-      if (Object.keys(utm).length > 0) result.utm = utm;
+      const { kept } = screenManagedAnalyticsCampaign(query);
+      if (Object.keys(kept).length > 0) result.utm = kept;
     } catch {
       // Invalid route input contributes no attribution.
     }
@@ -184,6 +174,29 @@ export function minimizePageAttribution(input: AttributionSourceInput): ManagedP
   return result.referrer || result.utm ? result : undefined;
 }
 
+/**
+ * Read Google Ads click identifiers (`gclid`, `gbraid`, `wbraid`) from a landing URL.
+ * Each key counts only when it appears exactly once with a valid value; anything else
+ * is dropped silently, so no rejected value reaches a diagnostic. These never enter
+ * the analytics event contract: only the GA4 host capability carries them.
+ */
+export function readGoogleAdsClickIds(routeUrl: string | null | undefined): GoogleAdsClickIds | undefined {
+  if (!routeUrl) return undefined;
+  let route: URL;
+  try {
+    route = new URL(routeUrl, "https://route.invalid");
+  } catch (error) {
+    if (error instanceof TypeError) return undefined;
+    throw error;
+  }
+  const ids: GoogleAdsClickIds = {};
+  for (const key of GOOGLE_ADS_CLICK_ID_KEYS) {
+    const values = route.searchParams.getAll(key);
+    if (values.length === 1 && isGoogleAdsClickIdValue(values[0])) ids[key] = values[0];
+  }
+  return Object.keys(ids).length > 0 ? ids : undefined;
+}
+
 export type ManagedAnalyticsEmitResult =
   | CommerceEmitResult
   | {

package/packages/public-runtime/src/integration/native-amplitude.ts

@@ -41,7 +41,11 @@ import {
   type BrowserEnvironment,
   type IntegrationEnvironment,
 } from "./environment.js";
-import { resemblesManagedAnalyticsPii } from "./managed-analytics-value-safety.js";
+import {
+  resemblesManagedAnalyticsPii,
+  screenManagedAnalyticsCampaign,
+  type ManagedAnalyticsCampaignField,
+} from "./managed-analytics-value-safety.js";
 import {
   buildGovernedEventProperties,
   type GovernedEventProperties,
@@ -342,10 +346,10 @@ function isPlainObject(value: unknown): value is Record<string, unknown> {
 /**
  * Flatten the already-validated `data.attribution` object (`events.ts`
  * `validatePageAttribution` — a minimized referrer origin plus up to five UTM
- * tokens) into Amplitude's flat `event_properties`. Re-screened for PII here
- * rather than trusted from upstream validation alone, matching `isSafePagePath`'s
- * own double-check: a field that resembles PII is dropped individually rather
- * than failing the whole page-view event.
+ * tokens) into Amplitude's flat `event_properties`. UTM values are re-screened with
+ * the same campaign policy GA4 applies (`screenManagedAnalyticsCampaign`) rather than
+ * trusted from upstream validation alone, so both destinations carry the same fields;
+ * a rejected field is dropped individually rather than failing the whole page view.
  */
 function extractAttributionProperties(data: Record<string, unknown>): AmplitudeAttributionProperties {
   const attribution = data["attribution"];
@@ -354,11 +358,8 @@ function extractAttributionProperties(data: Record<string, unknown>): AmplitudeA
 
   const utm = attribution["utm"];
   if (isPlainObject(utm)) {
-    for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
-      const value = utm[key];
-      if (typeof value === "string" && value.length > 0 && !resemblesManagedAnalyticsPii(value)) {
-        out[`utm_${key}`] = value;
-      }
+    for (const [key, value] of Object.entries(screenManagedAnalyticsCampaign(utm).kept)) {
+      out[`utm_${key as ManagedAnalyticsCampaignField}`] = value;
     }
   }
 

package/packages/public-runtime/src/integration/native-ga4-sandbox-asset.d.mts

@@ -1,4 +1,5 @@
 export const NATIVE_GA4_SANDBOX_ASSET_PATH: "platform/google-measurement/v2/sandbox.html";
 export const NATIVE_GA4_SANDBOX_ASSET_URL: "/platform/google-measurement/v2/sandbox.html";
 export const NATIVE_GA4_SANDBOX_ORIGIN: "https://analytics-frame.tokenoftrust.store";
+export const NATIVE_GA4_SANDBOX_FRAME_STYLE: Readonly<Record<string, string>>;
 export function resolveNativeGa4SandboxUrl(parentHref: string): string;

package/packages/public-runtime/src/integration/native-ga4-sandbox-asset.mjs

@@ -3,6 +3,26 @@ export const NATIVE_GA4_SANDBOX_ASSET_PATH = "platform/google-measurement/v2/san
 export const NATIVE_GA4_SANDBOX_ASSET_URL = `/${NATIVE_GA4_SANDBOX_ASSET_PATH}`;
 export const NATIVE_GA4_SANDBOX_ORIGIN = "https://analytics-frame.tokenoftrust.store";
 
+/**
+ * The frame's box: laid out, but invisible and inert. gtag's enhanced measurement
+ * reports a 90% `scroll` as soon as it loads in a frame with no layout (`display:none`
+ * or a 0x0 box), because the frame document's height guard then has no viewport to
+ * measure against. A 1px box gives it one (measured 2026-10-28 with the live gtag.js,
+ * collection null-routed: hidden and 0x0 frames each sent `scroll` at 90%, the 1px box
+ * sent only the page views). The parent sets it through the CSSOM, which its CSP does
+ * not govern.
+ */
+export const NATIVE_GA4_SANDBOX_FRAME_STYLE = Object.freeze({
+  position: "fixed",
+  top: "0",
+  left: "0",
+  width: "1px",
+  height: "1px",
+  border: "0",
+  opacity: "0",
+  "pointer-events": "none",
+});
+
 /**
  * Keep Google tag execution on a real, isolated origin. An opaque sandbox origin makes
  * gtag.js load successfully but silently suppresses every collection request. Production

package/packages/public-runtime/src/integration/native-ga4-sandbox-entry.ts

@@ -5,10 +5,15 @@ import {
   NATIVE_GA4_SANDBOX_PROTOCOL,
   type NativeGa4SandboxPortMessage,
 } from "./native-ga4-sandbox.js";
-import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-value-safety.js";
+import {
+  isGoogleAdsClickIds,
+  MANAGED_ANALYTICS_CAMPAIGN_FIELDS,
+  resemblesManagedAnalyticsProtectedValue,
+  screenManagedAnalyticsCampaign,
+  type GoogleAdsClickIds,
+} from "./managed-analytics-value-safety.js";
 
 const MEASUREMENT_ID = /^G-[A-Z0-9]{4,20}$/;
-const CAMPAIGN_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~-]{0,127}$/;
 const GOVERNED_VALUE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const CLIENT_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
 const SESSION_STATES: ReadonlySet<unknown> = new Set(["first_visit", "new_session", "continuing"]);
@@ -155,11 +160,12 @@ function seedSessionCookies(jar: Map<string, string>, ids: readonly string[], vi
 }
 
 /**
- * gtag's enhanced measurement runs inside this frame and reports the frame's own
- * document: its URL, its title, and a `scroll` at 90% depth that a short hidden
- * document reaches on load (measured 2026-10-06 on a live stream). A frame taller than
- * any viewport never reaches that depth, so the fabricated scroll is never sent.
- * Setting height through the CSSOM is outside the frame's style CSP, which governs markup.
+ * gtag's enhanced measurement runs inside this frame and reports a `scroll` at 90% depth
+ * once the frame document fits its viewport. A document taller than any viewport never
+ * reaches that depth, so the fabricated scroll is never sent. The guard needs the frame
+ * to be laid out (`NATIVE_GA4_SANDBOX_FRAME_STYLE`); a frame with no layout reports the
+ * scroll regardless. Setting height through the CSSOM is outside the frame's style CSP,
+ * which governs markup.
  */
 function suppressFrameScroll(doc: Document): void {
   const root = doc.documentElement as HTMLElement | null | undefined;
@@ -168,9 +174,8 @@ function suppressFrameScroll(doc: Document): void {
 
 function validCampaign(value: unknown): value is Record<string, string> {
   const record = plainRecord(value);
-  if (!record || !exactKeys(record, ["source", "medium", "campaign", "term", "content"], [])) return false;
-  return Object.values(record).every((item) =>
-    typeof item === "string" && CAMPAIGN_VALUE.test(item) && !resemblesManagedAnalyticsProtectedValue(item));
+  return record !== null && exactKeys(record, MANAGED_ANALYTICS_CAMPAIGN_FIELDS, []) &&
+    screenManagedAnalyticsCampaign(record).rejected.length === 0;
 }
 
 export interface NativeGa4SandboxRuntimeWindow extends Pick<Window, "parent" | "location"> {
@@ -281,25 +286,31 @@ function runPort(port: MessagePort, win: NativeGa4SandboxRuntimeWindow, doc: Doc
   const deliver = (message: Record<string, unknown>): void => {
     if (!active || disposed || message["schemaVersion"] !== 1) return;
     if (message["type"] === "page_view") {
-      if (!exactKeys(message, ["schemaVersion", "type", "path", "referrerOrigin", "campaign"], ["schemaVersion", "type", "path"])) return;
+      if (!exactKeys(message, ["schemaVersion", "type", "path", "referrerOrigin", "campaign", "clickIds"], ["schemaVersion", "type", "path"])) return;
       if (!validPath(message["path"])) return;
       if (message["referrerOrigin"] !== undefined && !validOrigin(message["referrerOrigin"])) return;
       if (message["campaign"] !== undefined && !validCampaign(message["campaign"])) return;
+      if (message["clickIds"] !== undefined && !isGoogleAdsClickIds(message["clickIds"])) return;
       const pageLocation = `${canonicalOrigin}${message["path"]}`;
       lastPageLocation = pageLocation;
       // Events gtag collects on its own (engagement, enhanced measurement) take the page
       // from these defaults, not from the frame. The title crosses the boundary as the path:
       // the frame's own title would label every page "Analytics transport".
       gtag("set", { page_location: pageLocation, page_title: message["path"] });
+      // Click identifiers ride only this event's page_location, where GA4 reads ad-click
+      // information; the page default and the action anchor stay query-free.
+      const clickIds = message["clickIds"] as GoogleAdsClickIds | undefined;
       const params: Record<string, unknown> = {
         ...governedProperties,
-        page_location: pageLocation,
+        page_location: clickIds
+          ? `${pageLocation}?${new URLSearchParams(clickIds as Record<string, string>).toString()}`
+          : pageLocation,
         page_path: message["path"],
       };
       if (message["referrerOrigin"] !== undefined) params["page_referrer"] = message["referrerOrigin"];
       if (message["campaign"] !== undefined) {
         const campaign = message["campaign"] as Record<string, string>;
-        for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
+        for (const key of MANAGED_ANALYTICS_CAMPAIGN_FIELDS) {
           const ga4Key = key === "campaign" ? "name" : key;
           if (campaign[key] !== undefined) params[`campaign_${ga4Key}`] = campaign[key];
         }

package/packages/public-runtime/src/integration/native-ga4-sandbox.ts

@@ -1,6 +1,7 @@
 /** Closed parent/iframe protocol for the reviewed GA4 isolated-origin sandbox. */
 import type { GovernedEventProperties } from "./governed-event-properties.js";
-import { resolveNativeGa4SandboxUrl } from "./native-ga4-sandbox-asset.mjs";
+import type { GoogleAdsClickIds, ManagedAnalyticsCampaign } from "./managed-analytics-value-safety.js";
+import { NATIVE_GA4_SANDBOX_FRAME_STYLE, resolveNativeGa4SandboxUrl } from "./native-ga4-sandbox-asset.mjs";
 
 export const NATIVE_GA4_SANDBOX_PROTOCOL = "tot.ga4-sandbox/1" as const;
 export const NATIVE_GA4_SANDBOX_MAX_DESTINATIONS = 4 as const;
@@ -40,13 +41,9 @@ export interface NativeGa4PageViewCommand {
   type: "page_view";
   path: string;
   referrerOrigin?: string;
-  campaign?: {
-    source?: string;
-    medium?: string;
-    campaign?: string;
-    term?: string;
-    content?: string;
-  };
+  campaign?: ManagedAnalyticsCampaign;
+  /** Landing-page Google Ads click identifiers; the frame adds them to this event's `page_location` only. */
+  clickIds?: GoogleAdsClickIds;
 }
 
 export interface NativeGa4ActionCommand {
@@ -75,7 +72,7 @@ export interface NativeGa4SandboxFrame {
   addEventListener(type: "load" | "error", listener: () => void, options?: { once?: boolean }): void;
   remove(): void;
   src: string;
-  hidden: boolean;
+  style: { setProperty(name: string, value: string): void };
 }
 
 export interface NativeGa4SandboxHost {
@@ -122,7 +119,7 @@ const IMMEDIATE_SCHEDULER: NativeGa4SandboxScheduler = (start) => {
 };
 
 /**
- * Mount one hidden same-site, cross-origin iframe and transfer exactly one MessagePort
+ * Mount one invisible same-site, cross-origin iframe and transfer exactly one MessagePort
  * after load. gtag suppresses collection in an opaque third-party frame, so the receiver
  * needs a real same-site origin. The exact origin, iframe window, and one-shot transfer
  * are the authority boundary. No general parent `message` listener is installed.
@@ -170,7 +167,7 @@ export function createNativeGa4SandboxTransport(
     mounted.setAttribute("aria-hidden", "true");
     mounted.setAttribute("tabindex", "-1");
     mounted.setAttribute("title", "Analytics transport");
-    mounted.hidden = true;
+    for (const [name, value] of Object.entries(NATIVE_GA4_SANDBOX_FRAME_STYLE)) mounted.style.setProperty(name, value);
     mounted.src = sandboxUrl;
 
     mounted.addEventListener("load", () => {

package/packages/public-runtime/src/integration/native-ga4.ts

@@ -24,7 +24,12 @@ import {
   resolveAdapterDestinationIds,
 } from "./platform-adapters.js";
 import { INTEGRATION_ENVIRONMENTS, type IntegrationEnvironment } from "./environment.js";
-import { resemblesManagedAnalyticsProtectedValue } from "./managed-analytics-value-safety.js";
+import {
+  resemblesManagedAnalyticsProtectedValue,
+  screenManagedAnalyticsCampaign,
+  isGoogleAdsClickIds,
+  type GoogleAdsClickIds,
+} from "./managed-analytics-value-safety.js";
 import {
   createVisitorContinuity,
   NO_SESSION_ID,
@@ -88,6 +93,11 @@ export interface NativeGa4ModuleOptions {
   continuity?: VisitorContinuity;
   /** Epoch-millisecond clock for session activity; defaults to the wall clock. */
   now?: () => number;
+  /**
+   * The host's one-shot landing click identifiers for a page view at `path`. The host
+   * owns the consent and region decision and returns them at most once per document.
+   */
+  takeLandingClickIds?: (path: string) => GoogleAdsClickIds | undefined;
 }
 
 interface ActiveGa4Config {
@@ -220,12 +230,8 @@ function mapEvent(
       }
       const utm = record["utm"];
       if (typeof utm === "object" && utm !== null && !Array.isArray(utm)) {
-        const campaign: NonNullable<typeof command.campaign> = {};
-        for (const key of ["source", "medium", "campaign", "term", "content"] as const) {
-          const value = (utm as Record<string, unknown>)[key];
-          if (typeof value === "string" && !resemblesManagedAnalyticsProtectedValue(value)) campaign[key] = value;
-        }
-        if (Object.keys(campaign).length > 0) command.campaign = campaign;
+        const { kept } = screenManagedAnalyticsCampaign(utm as Record<string, unknown>);
+        if (Object.keys(kept).length > 0) command.campaign = kept;
       }
     }
     return Object.freeze(command);
@@ -332,8 +338,15 @@ export function createNativeGa4Module(options: NativeGa4ModuleOptions): Integrat
             const oldest = deliveredOrder.shift();
             if (oldest !== undefined) delivered.delete(oldest);
           }
+          let outgoing = command;
+          if (command.type === "page_view" && options.takeLandingClickIds) {
+            try {
+              const clickIds = options.takeLandingClickIds(command.path);
+              if (isGoogleAdsClickIds(clickIds)) outgoing = Object.freeze({ ...command, clickIds: { ...clickIds } });
+            } catch { /* a page view never waits on attribution */ }
+          }
           try {
-            const result = send(command);
+            const result = send(outgoing);
             if (result && typeof result.then === "function") {
               void result.catch(() => observeSafely(options.observe, "transport_failed"));
             }

package/packages/public-runtime/src/integration/plan.ts

@@ -83,11 +83,13 @@ export interface NormalizedContribution {
 /**
  * The tenant's analytics policy for visitors in the EU/EEA, the UK and Switzerland, and
  * for visitors whose region is unknown:
- *   - `count-only` (default): page views are delivered, nothing is stored on the device.
+ *   - `ask` (default): page views are counted without storing anything, and the visitor is
+ *     prompted; an Allow applies the default behavior for that visitor.
+ *   - `count-only`: page views are delivered, nothing is stored on the device, no prompt.
  *   - `full`: the tenant takes responsibility for EU/UK consent; the default behavior applies.
  *   - `none`: no analytics or marketing destination runs for those visitors.
  */
-export const EU_UK_VISITOR_POLICIES = ["count-only", "full", "none"] as const;
+export const EU_UK_VISITOR_POLICIES = ["ask", "count-only", "full", "none"] as const;
 export type EuUkVisitorPolicy = (typeof EU_UK_VISITOR_POLICIES)[number];
 
 export function isEuUkVisitorPolicy(value: unknown): value is EuUkVisitorPolicy {
@@ -102,9 +104,9 @@ export interface EffectivePlan {
   tenantPublicId: string;
   /**
    * The tenant's {@link EuUkVisitorPolicy}, present only when it is not the
-   * `count-only` default. It participates in `planRevision`.
+   * `ask` default. It participates in `planRevision`.
    */
-  euUkVisitors?: Exclude<EuUkVisitorPolicy, "count-only">;
+  euUkVisitors?: Exclude<EuUkVisitorPolicy, "ask">;
   integrations: PlanIntegration[];
   contributions: NormalizedContribution[];
   /** Resolved execution order over contribution ids. */

package/packages/public-runtime/src/integration/platform-adapter-runtime.ts

@@ -24,6 +24,7 @@ import {
   NATIVE_GA4_RUNTIME_ID,
   type NativeGa4Transport,
 } from "./native-ga4.js";
+import type { GoogleAdsClickIds } from "./managed-analytics-value-safety.js";
 import { AMPLITUDE_HTTP_ADAPTER, GOOGLE_MEASUREMENT_ADAPTER } from "./platform-adapters.js";
 
 export const PLATFORM_ADAPTER_ENTRY_SCHEMA_VERSION = 1 as const;
@@ -43,6 +44,8 @@ export interface PlatformAdapterRuntimeHost {
   nativeGa4Transport?: NativeGa4Transport;
   /** The host's persistent visitor store, shared by GA4 and Amplitude; absent keeps visitors memory-only. */
   visitorContinuity?: VisitorContinuity;
+  /** GA4 only: the host's consent- and region-gated one-shot landing click identifiers. */
+  takeLandingClickIds?: (path: string) => GoogleAdsClickIds | undefined;
 }
 
 export interface PlatformAdapterRuntimeRegistration {
@@ -74,9 +77,9 @@ const AMPLITUDE_MARKER: PlatformAdapterEntryMarker = Object.freeze({
 export const PLATFORM_ADAPTER_RUNTIME_REGISTRY: readonly PlatformAdapterRuntimeRegistration[] = Object.freeze([
   Object.freeze({
     marker: GA4_MARKER,
-    create: ({ nativeGa4Transport, visitorContinuity }: PlatformAdapterRuntimeHost) => {
+    create: ({ nativeGa4Transport, visitorContinuity, takeLandingClickIds }: PlatformAdapterRuntimeHost) => {
       if (!nativeGa4Transport) throw new Error("platform_adapter_ga4_sandbox_unavailable");
-      return createNativeGa4Module({ transport: nativeGa4Transport, continuity: visitorContinuity });
+      return createNativeGa4Module({ transport: nativeGa4Transport, continuity: visitorContinuity, takeLandingClickIds });
     },
   }),
   Object.freeze({
@@ -92,6 +95,7 @@ export interface PlatformAdapterRuntimeLoaderOptions {
   fetchCapability?: typeof fetch;
   nativeGa4Transport?: () => NativeGa4Transport;
   visitorContinuity?: VisitorContinuity;
+  takeLandingClickIds?: (path: string) => GoogleAdsClickIds | undefined;
   importModule?: (url: string) => Promise<unknown>;
   fallback: IntegrationModuleLoader;
 }
@@ -156,6 +160,9 @@ export function makePlatformAdapterRuntimeLoader(
         : undefined,
       // One store for both destinations, so they agree on visitors and sessions.
       visitorContinuity: options.visitorContinuity,
+      takeLandingClickIds: registration.marker.appId === GOOGLE_MEASUREMENT_ADAPTER.adapterId
+        ? options.takeLandingClickIds
+        : undefined,
     });
   };
 }