@analitikisler/ai-tag-debugger 0.20.1 → 0.22.0

package/src/browser.js

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
 import { readFile, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
@@ -7,6 +8,9 @@ import { parseTrackingRequest, isCollectionEndpoint, providerOf, vendorOf, resol
 import { redactBody, redactParams, redactPush, redactUrl } from "./redact.js";
 import { hostScope, isPrivateAddress, navigationError, privateHostChecker } from "./guard.js";
 import { startEgressProxy } from "./egress.js";
+import { campaignParamsIn } from "./campaign.js";
+import { detectCmpInPage } from "./cmp.js";
+import { callersOf, containerOf } from "./containers.js";
 
 // Consent banners of the common consent platforms (CMPs), by their container. A cover that matches
 // one of these always blocks the journey, and a reject click is checked against them afterwards.
@@ -26,10 +30,12 @@ export function installBrowser() {
 export const CMP_BANNER_SELECTORS = `#onetrust-banner-sdk, #onetrust-consent-sdk, #CybotCookiebotDialog, #usercentrics-root, #didomi-host, #cookiescript_injected, .cky-consent-container, .cc-window, #cmpbox, .qc-cmp2-container, \
 #truste-consent-track, #consent_blackbar, .osano-cm-window, #iubenda-cs-banner, .iubenda-cs-container, #cmplz-cookiebanner-container, .cmplz-cookiebanner, #cookiefirst-root, .cookiefirst-root, #axeptio_overlay, \
 #sp_message_container, [id^="sp_message_container_"], #cookie-law-info-bar, #BorlabsCookieBox, .klaro, #termly-code-snippet-support, #cookie-information-template-wrapper, #coiOverlay, \
-#cmpwrapper, #cmpbox2, .fc-consent-root, #ppms_cm_popup_overlay, [aria-label*="cookie" i][role=dialog]`;
+#cmpwrapper, #cmpbox2, .fc-consent-root, #ppms_cm_popup_overlay, [aria-label*="cookie" i][role=dialog], \
+[data-name^="Banner"][efl-consent-not-saved]`;
+// Efilli draws its banner inside the open shadow root of <efilli-layout-dynamic>, so the checks below also look inside open shadow roots.
 
 // Caps on what one audit records, so a looping page can't grow memory without limit.
-const LOG_LIMITS = { hits: 5000, dataLayerLog: 5000, network: 10000 };
+const LOG_LIMITS = { hits: 5000, dataLayerLog: 5000, network: 10000, containerLoads: 500 };
 
 // Secrets the browser process has no use for. It gets the rest of the environment
 // (PATH, HOME, DISPLAY...) so Chromium still starts normally.
@@ -55,8 +61,57 @@ const hostOf = (url) => {
   }
 };
 
+// Runs inside INIT_SCRIPT: records each Google container script (gtm.js, gtag/js) the page adds, through
+// window.__atdLoad, with how it got there. One set by a script carries that moment's call stack, whose script
+// addresses tell who asked for it (see src/containers.js); one the HTML parser inserted never passes through
+// the setters, so a MutationObserver reports it. A container reading another dataLayer gets it watched.
+const CONTAINER_HOOK = `
+  const docUrl = location.href;
+  const doc = Math.random().toString(36).slice(2, 10);
+  const isContainer = (src) => /\\/(gtm\\.js|gtag\\/js)\\?/.test(String(src)) && /[?&]id=/.test(String(src));
+  const seen = new WeakSet();
+  const report = (el, src, how) => {
+    try {
+      const abs = new URL(String(src), document.baseURI).href;
+      if (!isContainer(abs) || !window.__atdLoad) return;
+      const layer = new URL(abs).searchParams.get("l") || "dataLayer";
+      watch(layer);
+      let frames = [];
+      if (how === "script") {
+        const limit = Error.stackTraceLimit;
+        Error.stackTraceLimit = 50;
+        const stack = String(new Error().stack || "");
+        Error.stackTraceLimit = limit;
+        // The first two frames are report() and the setter, both from this script; injected inline code
+        // (a Custom HTML tag) has no address and shows as <anonymous>.
+        frames = stack.split("\\n").filter((line) => /^\\s+at /.test(line)).slice(2)
+          .map((line) => (line.match(/(https?:\\/\\/[^\\s()]+?):\\d+:\\d+/) || [])[1] || (/<anonymous>/.test(line) ? "inline" : null))
+          .filter(Boolean);
+      }
+      window.__atdLoad({ src: abs, how, frames, documentUrl: docUrl, page: location.href, doc });
+    } catch {}
+  };
+  try {
+    const desc = Object.getOwnPropertyDescriptor(HTMLScriptElement.prototype, "src");
+    Object.defineProperty(HTMLScriptElement.prototype, "src", {
+      ...desc,
+      set(v) { if (!seen.has(this)) { seen.add(this); report(this, v, "script"); } return desc.set.call(this, v); },
+    });
+    const setAttribute = Element.prototype.setAttribute;
+    Element.prototype.setAttribute = function (name, v) {
+      if (this instanceof HTMLScriptElement && String(name).toLowerCase() === "src" && !seen.has(this)) { seen.add(this); report(this, v, "script"); }
+      return setAttribute.call(this, name, v);
+    };
+    new MutationObserver((list) => {
+      for (const m of list) for (const n of m.addedNodes) {
+        if (n instanceof HTMLScriptElement && n.src && !seen.has(n)) { seen.add(n); report(n, n.src, "parser"); }
+      }
+    }).observe(document, { childList: true, subtree: true });
+  } catch {}
+`;
+
 const INIT_SCRIPT = `(() => {
-  const record = (entry) => {
+  const record = (entry, layer = "dataLayer") => {
     let value = entry;
     try {
       // gtag() pushes an arguments object; store it as a plain array.
@@ -90,22 +145,32 @@ const INIT_SCRIPT = `(() => {
       };
       value = JSON.parse(JSON.stringify(copy(value, [])));
     } catch { value = String(entry); }
-    if (window.__atdRecord) window.__atdRecord({ url: location.href, value });
+    if (window.__atdRecord) window.__atdRecord({ url: location.href, value, ...(layer === "dataLayer" ? {} : { layer }) });
   };
-  const wrap = (dl) => {
-    if (!dl || dl.__atdWrapped) return dl;
-    dl.forEach(record);
+  const wrap = (dl, layer) => {
+    if (!dl || dl.__atdWrapped || typeof dl.push !== "function") return dl;
+    dl.forEach((e) => record(e, layer));
     const push = dl.push.bind(dl);
-    dl.push = (...items) => { items.forEach(record); return push(...items); };
+    dl.push = (...items) => { items.forEach((e) => record(e, layer)); return push(...items); };
     dl.__atdWrapped = true;
     return dl;
   };
-  let current = wrap(window.dataLayer || []);
-  Object.defineProperty(window, "dataLayer", {
-    configurable: true,
-    get: () => current,
-    set: (v) => { current = wrap(v); },
-  });
+  const watched = new Set();
+  // A container can read a dataLayer of another name (gtm.js?l=myDataLayer); it is watched once one is seen.
+  const watch = (layer) => {
+    if (watched.has(layer) || !/^[A-Za-z_$][\\w$]*$/.test(layer)) return;
+    watched.add(layer);
+    try {
+      let current = layer === "dataLayer" ? wrap(window[layer] || [], layer) : wrap(window[layer], layer);
+      Object.defineProperty(window, layer, {
+        configurable: true,
+        get: () => current,
+        set: (v) => { current = wrap(v, layer); },
+      });
+    } catch { /* a property the page made unconfigurable */ }
+  };
+  watch("dataLayer");
+${CONTAINER_HOOK}
 })();`;
 
 // Labels the interactive elements of one frame with numeric refs, starting at
@@ -113,7 +178,7 @@ const INIT_SCRIPT = `(() => {
 // and form fields, it finds custom controls that sites build from divs and spans
 // (role attributes, tabindex, or a pointer cursor). Elements on screen come first,
 // so a long menu or footer can't push the button the agent needs out of the list.
-function snapshotInPage({ first, limit, textLimit, frameBox }) {
+function snapshotInPage({ first, limit, textLimit, frameBox, offscreenLimit = null }) {
   const visible = (el) => {
     const r = el.getBoundingClientRect();
     if (r.width <= 0 || r.height <= 0) return false;
@@ -187,8 +252,11 @@ function snapshotInPage({ first, limit, textLimit, frameBox }) {
     .map((el, order) => ({ el, order, tier: tierOf(el) }))
     .sort((a, b) => a.tier - b.tier || a.order - b.order);
   const firstCovered = ranked.findIndex((x) => x.tier === 2);
+  let offscreen = 0;
   const items = ranked
     .filter((item, i) => item.tier < 2 || i - firstCovered < 30) // only a few covered or clipped ones
+    // A compact view keeps a few elements above or below the screen; scrolling brings the rest on screen.
+    .filter((item) => item.tier !== 1 || offscreenLimit === null || offscreen++ < offscreenLimit)
     .slice(0, limit)
     .map((item) => ({ ...item, onScreen: item.tier === 0 }));
   const lines = [];
@@ -377,6 +445,72 @@ export function isTransientNavigationError(err, failedLoad) {
   return code === "timeout" || TRANSIENT_NET_ERRORS.test(code);
 }
 
+/**
+ * What a step's analytics and ad cookies say, without keeping their values: the GA4 client id from _ga
+ * (the cid GA4 hits carry anyway), whether _gcl_aw and _fbc hold the click ids the landing page was opened
+ * with ("landing") or other ones ("other"), and whether _gcl_au and _fbp exist. Null when none of them do.
+ */
+export function identityOf(cookies, landingUrl) {
+  const value = (name) => cookies.find((c) => c.name === name)?.value ?? "";
+  const sent = landingUrl ? campaignParamsIn(landingUrl) : {};
+  const out = {};
+  const ga = /^GA\d\.\d+\.(\d+\.\d+)$/.exec(value("_ga"));
+  if (ga) out.ga_client_id = ga[1];
+  // _gcl_aw is GCL.<time>.<gclid>; _fbc is fb.<n>.<time>.<fbclid>.
+  const aw = /^GCL\.\d+\.(.+)$/.exec(value("_gcl_aw"));
+  if (aw) out.gcl_aw = aw[1] === sent.gclid ? "landing" : "other";
+  const fbc = /^fb\.\d+\.\d+\.(.+)$/.exec(value("_fbc"));
+  if (fbc) out.fbc = fbc[1] === sent.fbclid ? "landing" : "other";
+  if (value("_gcl_au")) out.gcl_au = true;
+  if (value("_fbp")) out.fbp = true;
+  return Object.keys(out).length ? out : null;
+}
+
+/**
+ * Runs in the page: the Google tag's own consent state (google_tag_data.ics), or null before a Google tag loaded.
+ * Per consent type the default and update it holds, and whether it applied a default and an update at all, whether
+ * the default came after a tag had already read consent (wasSetLate), and whether wait_for_update ran out. It is how
+ * the tag sees consent, wherever it was set: gtag() in the page, or a consent platform's GTM template, which never
+ * shows in the dataLayer. Not documented by Google; read defensively.
+ */
+export function googleConsentStateInPage() {
+  const ics = window.google_tag_data?.ics;
+  if (!ics || typeof ics !== "object") return null;
+  const word = (v) => (v === true ? "granted" : v === false ? "denied" : undefined);
+  const entries = {};
+  for (const [type, e] of Object.entries(ics.entries ?? {})) {
+    if (!e || typeof e !== "object") continue;
+    const d = word(e.default);
+    const u = word(e.update);
+    entries[type] = { ...(d ? { default: d } : {}), ...(u ? { update: u } : {}) };
+  }
+  return { entries, usedDefault: Boolean(ics.usedDefault), usedUpdate: Boolean(ics.usedUpdate), wasSetLate: Boolean(ics.wasSetLate), waitPeriodTimedOut: Boolean(ics.waitPeriodTimedOut) };
+}
+
+/**
+ * Runs in the page: whether it is something other than the site, so what a step captured there says nothing about
+ * the site's tracking. A bot challenge in its place (Cloudflare, DataDome, HUMAN, Akamai), or a page that crashed in
+ * the browser (the error screen a Next.js app shows when its scripts fail). Null for a page that looks like itself.
+ * @returns {null | { kind: "challenge"|"crash", vendor?: string }}
+ */
+export function pageProblemInPage() {
+  const title = (document.title || "").trim();
+  const text = (document.body?.innerText || "").replace(/\s+/g, " ").trim().slice(0, 3000);
+  const has = (selector) => {
+    try {
+      return Boolean(document.querySelector(selector));
+    } catch {
+      return false;
+    }
+  };
+  if (/^just a moment\.\.\.$|^attention required! \| cloudflare$/i.test(title) || has("#challenge-form, #challenge-running, #cf-challenge-running")) return { kind: "challenge", vendor: "Cloudflare" };
+  if (has('iframe[src*="captcha-delivery.com"]')) return { kind: "challenge", vendor: "DataDome" };
+  if (has("#px-captcha")) return { kind: "challenge", vendor: "HUMAN" };
+  if (/^access denied$/i.test(title) && /reference\s*#\s*[\d.a-f]+/i.test(text)) return { kind: "challenge", vendor: "Akamai" };
+  if (/^application error: a client-side exception has occurred/i.test(text)) return { kind: "crash", vendor: "Next.js" };
+  return null;
+}
+
 export class AuditSession {
   /**
    * @param {{ viewport: string, site?: string, allowedHosts?: string[], providers?: string[], keepBodies?: boolean, blockPrivate?: boolean | ((ip: string) => boolean), blockHits?: boolean, headless?: boolean }} opts
@@ -406,8 +540,13 @@ export class AuditSession {
     this.consentStep = null;
     this.rejectStep = null;
     this.cookieLog = []; // each cookie name and domain with the step it was first seen at (never values)
+    this.cookieChanges = []; // { step, name, domain, change: added|changed|removed }, never values
+    this.cookieHashes = new Map(); // domain|name -> a hash of the value at the last step, kept in memory only
+    this.cmp = null; // the consent platform and its setup, from detectCmpInPage, with the step it was first seen at
+    this.refusedScripts = new Map(); // step -> how many of the page's scripts were refused for coming back as HTML
     this.errors = [];
     this.dataLayerLog = [];
+    this.containerLoads = []; // each Google container script the page added, with how (see src/containers.js)
     this.network = [];
     this.providers = resolveProviders(this.opts.providers);
     this.landing = null; // the first page: { step, requested, chain, final }
@@ -452,9 +591,14 @@ export class AuditSession {
       this.lastTrackingAt = Date.now();
       this.record("dataLayerLog", { ...this.redactEntry(entry), step: this.currentStep, t: Date.now() });
     });
+    await this.context.exposeBinding("__atdLoad", (_source, entry) => this.recordLoad(entry));
     await this.context.addInitScript(INIT_SCRIPT);
     this.page = await this.context.newPage();
     this.page.on("pageerror", (err) => this.errors.push({ step: this.currentStep, message: err.message }));
+    // A script that comes back as an HTML page (a bot check, or files a new deployment no longer has) is refused.
+    this.page.on("console", (msg) => {
+      if (msg.type() === "error" && /^Refused to execute script from .*MIME type \('text\/html'\)/.test(msg.text())) this.refusedScripts.set(this.currentStep, (this.refusedScripts.get(this.currentStep) ?? 0) + 1);
+    });
     this.page.on("framenavigated", (frame) => {
       if (frame !== this.page.mainFrame()) return;
       if (frame.url().startsWith("chrome-error:")) this.errorPageShown = true;
@@ -521,7 +665,14 @@ export class AuditSession {
     });
     this.context.on("response", (response) => {
       const call = calls.get(response.request());
-      if (call) call.status = response.status();
+      if (!call) return;
+      call.status = response.status();
+      // A consent platform's script or setup file date tells which build of its setup the site serves. Setup files
+      // (OneTrust's, Cookiebot's) are fetched by script rather than loaded as one.
+      if (call.provider === "consent" && ["script", "fetch", "xhr"].includes(call.type)) {
+        const lastModified = response.headers()["last-modified"];
+        if (lastModified) call.lastModified = lastModified;
+      }
     });
     this.context.on("requestfailed", (request) => {
       const call = calls.get(request);
@@ -667,6 +818,25 @@ export class AuditSession {
     return { postData: this.opts.keepBodies ? body : redactBody(body).text };
   }
 
+  /**
+   * A container script the page added: its ID, dataLayer and host, whether the HTML parser inserted it or a
+   * script did and, for a script, the callers on the stack. Only addresses without their query are kept, so
+   * the environment token (gtm_auth) and user data in a page's query string never reach the capture.
+   */
+  recordLoad(entry) {
+    const container = containerOf(entry?.src);
+    if (!container) return;
+    this.record("containerLoads", {
+      ...container,
+      how: entry.how === "parser" ? "parser" : "script",
+      ...(entry.how === "parser" ? {} : { callers: callersOf(entry.frames, entry.documentUrl) }),
+      page: pagePath(entry.page),
+      doc: String(entry.doc ?? "").slice(0, 16),
+      step: this.currentStep,
+      t: Date.now(),
+    });
+  }
+
   /** Adds an entry to one of the logs, up to its limit. Returns false once the limit is reached. */
   record(log, entry) {
     if (this[log].length >= LOG_LIMITS[log]) {
@@ -783,20 +953,21 @@ export class AuditSession {
     }
   }
 
-  async snapshot() {
+  /** @param {{ offscreenLimit?: number|null }} [opts] offscreenLimit: how many elements above or below the screen to list; null for all. */
+  async snapshot({ offscreenLimit = null } = {}) {
     const blocked = await this.enforce();
     if (blocked && this.page.url() === "about:blank") return { url: "about:blank", title: "", elements: "", text: `(${blocked})` };
     try {
       // The main page first, then iframes (booking and payment widgets often live in one).
       const frames = await this.visibleFrames();
-      const main = await this.page.evaluate(snapshotInPage, { first: 1, limit: frames.length ? MAX_ELEMENTS - 60 : MAX_ELEMENTS, textLimit: 3000 });
+      const main = await this.page.evaluate(snapshotInPage, { first: 1, limit: frames.length ? MAX_ELEMENTS - 60 : MAX_ELEMENTS, textLimit: 3000, offscreenLimit });
       this.refFrames = new Map();
       const lines = [...main.lines];
       let next = main.next;
       let more = main.more;
       for (const { frame, frameBox } of frames) {
         if (next > MAX_ELEMENTS) break;
-        const sub = await frame.evaluate(snapshotInPage, { first: next, limit: MAX_ELEMENTS - next + 1, textLimit: 0, frameBox }).catch(() => null);
+        const sub = await frame.evaluate(snapshotInPage, { first: next, limit: MAX_ELEMENTS - next + 1, textLimit: 0, frameBox, offscreenLimit }).catch(() => null);
         if (!sub?.lines.length) continue;
         lines.push(`(inside an embedded frame from ${new URL(sub.url).host})`, ...sub.lines);
         for (let r = next; r < sub.next; r++) this.refFrames.set(r, frame);
@@ -940,7 +1111,7 @@ export class AuditSession {
    */
   async act(a) {
     const error = await this.perform(a);
-    await this.trackCookies();
+    await this.observe();
     // A scripted replay of this step may fail the same way, which must not end the journey there.
     if (error) this.steps[this.currentStep].error = error;
     this.steps[this.currentStep].pagePath = pagePath(this.page.url());
@@ -948,6 +1119,28 @@ export class AuditSession {
     return error;
   }
 
+  /**
+   * What the step just taken left behind, beyond its requests: the cookies it changed, the consent platform the
+   * first time one is seen, and the Google tag's consent state when it changed. act() calls it after every action;
+   * the consent scenarios call it after the steps they take themselves.
+   */
+  async observe() {
+    await this.trackCookies();
+    if (!this.cmp) {
+      const cmp = await this.evaluateWithin(detectCmpInPage);
+      if (cmp) this.cmp = { ...cmp, step: this.currentStep };
+    }
+    const problem = await this.evaluateWithin(pageProblemInPage);
+    if (problem) {
+      const refused = this.refusedScripts.get(this.currentStep) ?? 0;
+      this.steps[this.currentStep].pageProblem = { ...problem, ...(refused ? { refusedScripts: refused } : {}) };
+    }
+    // Kept on the step only when it changed, so the steps that hold one are where the Google tag's state moved.
+    const tagConsent = await this.evaluateWithin(googleConsentStateInPage);
+    const before = this.steps.slice(0, this.currentStep).map((st) => st.tagConsent).filter(Boolean).at(-1);
+    if (tagConsent && JSON.stringify(tagConsent) !== JSON.stringify(before)) this.steps[this.currentStep].tagConsent = tagConsent;
+  }
+
   async perform(a) {
     const describe = a.reason || `${a.action} ${a.selector ?? (a.ref != null ? `#${a.ref}` : a.text != null ? `"${a.text}"` : a.url ?? "")}`.trim();
     this.beginStep(describe, { action: a.action, acceptsConsent: !!a.accepts_consent, rejectsConsent: !!a.rejects_consent });
@@ -1021,10 +1214,14 @@ export class AuditSession {
       if (a.rejects_consent && this.rejectStep === null) {
         this.rejectStep = this.currentStep;
         // A rejected banner should close; one that is still showing means the button did nothing.
-        step.bannerOpenAfter = await this.page.evaluate((sel) => [...document.querySelectorAll(sel)].some((n) => {
-          const r = n.getBoundingClientRect();
-          return r.width > 0 && r.height > 0 && getComputedStyle(n).visibility !== "hidden";
-        }), CMP_BANNER_SELECTORS).catch(() => false);
+        step.bannerOpenAfter = await this.page.evaluate((sel) => {
+          const roots = [document];
+          for (let i = 0; i < roots.length; i++) for (const n of roots[i].querySelectorAll("*")) if (n.shadowRoot) roots.push(n.shadowRoot);
+          return roots.flatMap((r) => [...r.querySelectorAll(sel)]).some((n) => {
+            const r = n.getBoundingClientRect();
+            return r.width > 0 && r.height > 0 && getComputedStyle(n).visibility !== "hidden";
+          });
+        }, CMP_BANNER_SELECTORS).catch(() => false);
       }
       return null;
     } catch (err) {
@@ -1032,20 +1229,56 @@ export class AuditSession {
     }
   }
 
-  /** Notes which cookies appeared during the step just taken (names and domains only). */
+  /**
+   * Notes the cookies the step just taken added, changed or removed, and what the analytics and ad cookies
+   * say (identityOf). Values never leave this function: a short hash of each, held until the next step,
+   * is enough to tell that one changed.
+   */
   async trackCookies() {
+    const all = await this.rawCookies();
     const seen = new Set(this.cookieLog.map((c) => `${c.domain}|${c.name}`));
-    for (const c of await this.cookies()) {
-      if (!seen.has(`${c.domain}|${c.name}`) && this.cookieLog.length < 500) this.cookieLog.push({ ...c, step: this.currentStep });
+    const now = new Map();
+    for (const c of all) {
+      const k = `${c.domain}|${c.name}`;
+      const hash = createHash("sha256").update(c.value).digest("base64").slice(0, 16);
+      now.set(k, hash);
+      if (!seen.has(k) && this.cookieLog.length < 500) this.cookieLog.push({ name: c.name, domain: c.domain, step: this.currentStep });
+      const before = this.cookieHashes.get(k);
+      const change = before === undefined ? "added" : before !== hash ? "changed" : null;
+      if (change && this.cookieChanges.length < 2000) this.cookieChanges.push({ step: this.currentStep, name: c.name, domain: c.domain, change });
     }
+    for (const k of this.cookieHashes.keys()) {
+      if (now.has(k) || this.cookieChanges.length >= 2000) continue;
+      const [domain, ...name] = k.split("|");
+      this.cookieChanges.push({ step: this.currentStep, name: name.join("|"), domain, change: "removed" });
+    }
+    this.cookieHashes = now;
+    const identity = identityOf(all, this.landing?.requested);
+    if (identity) this.steps[this.currentStep].identity = identity;
   }
 
-  async cookies() {
+  /** page.evaluate(fn), or null when it fails or the page does not answer within ms: a page stuck in a script never answers, and the next page read reports that. */
+  async evaluateWithin(fn, ms = 2000) {
+    let timer;
+    const result = await Promise.race([
+      this.page.evaluate(fn).catch(() => null),
+      new Promise((resolve) => (timer = setTimeout(() => resolve(null), ms))),
+    ]);
+    clearTimeout(timer);
+    return result;
+  }
+
+  /** The browser's cookies with their values, for trackCookies only; [] when the browser takes too long. */
+  async rawCookies() {
     let timer;
     const tooLong = new Promise((resolve) => (timer = setTimeout(() => resolve([]), 10_000)));
     const cookies = await Promise.race([this.context.cookies().catch(() => []), tooLong]);
     clearTimeout(timer);
-    return cookies.map((c) => ({ name: c.name, domain: c.domain }));
+    return cookies;
+  }
+
+  async cookies() {
+    return (await this.rawCookies()).map((c) => ({ name: c.name, domain: c.domain }));
   }
 
   async close() {

package/src/campaign.js

@@ -19,10 +19,13 @@ export function campaignParamsIn(url) {
   }
 }
 
-/** The address with test campaign parameters added, unless it already carries campaign parameters. */
-export function withCampaignParams(url) {
-  if (Object.keys(campaignParamsIn(url)).length) return url;
+/**
+ * The address with test campaign parameters added, unless it already carries campaign parameters.
+ * Given parameters of the caller's own (a real campaign's UTM values, a gclid), those are set instead, always.
+ */
+export function withCampaignParams(url, own = null) {
+  if (!own && Object.keys(campaignParamsIn(url)).length) return url;
   const u = new URL(url);
-  for (const [k, v] of Object.entries(TEST_PARAMS)) u.searchParams.set(k, v);
+  for (const [k, v] of Object.entries(own ?? TEST_PARAMS)) u.searchParams.set(k, v);
   return u.href;
 }