@tracelog/capture-web 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -18,6 +18,13 @@ patch, and neither requires reading your code.
 Entries after 1.0.0 are drafted from the commits that touched this package and
 edited before release.
 
+## [1.1.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.0.0...capture-web@1.1.0) (2026-09-21)
+
+
+### Added
+
+* **capture-web:** read the page's tag requests through Resource Timing ([3de9b5c](https://github.com/nacorga/tracelog-sdk/commit/3de9b5ccea21ed82f198b9885c1d6143f7ca71c1))
+
 ## 1.0.0
 
 The first published runtime.

package/README.md

@@ -1,7 +1,9 @@
 # @tracelog/capture-web
 
 The TraceLog browser capture runtime. It captures the conversion path a project
-declares — each conversion and the steps preceding it — and nothing else.
+declares — each conversion and the steps preceding it — and, beside each
+conversion, which GA4, Meta and Google Ads tags the page requested; nothing
+else.
 
 TraceLog is Trustworthy Conversion Intelligence — conversion intelligence you
 can verify: it verifies the conversion path a project declares against the
@@ -12,20 +14,21 @@ incomplete, and never makes up a number.
 
 ## Install
 
-**Every integration names a version.** There is no `latest` on npm and no
-`v/latest/` on the CDN, so the version you pin is the bytes you get, for as long
+**Every integration names a version, exactly.** Install with `--save-exact`,
+so your manifest names this version rather than a range, and there is no
+`v/latest/` on the CDN: the version you pin is the bytes you get, for as long
 as they are served.
 
 <!-- x-release-please-start-version -->
 
 ```bash
-npm install @tracelog/capture-web@1.0.0
+npm install --save-exact @tracelog/capture-web@1.1.0
 ```
 
 Without a build step, the same runtime as a script tag:
 
 ```html
-<script src="https://cdn.tracelog.io/v/1.0.0/tracelog.js"></script>
+<script src="https://cdn.tracelog.io/v/1.1.0/tracelog.js"></script>
 ```
 
 <!-- x-release-please-end -->
@@ -86,6 +89,14 @@ The events your tracking plan declares, with their context. Not page views, not
 clicks, not scroll, not keystrokes. Errors are captured only when they occur
 inside the conversion path, attached to the step where they happened.
 
+Beside each conversion, which GA4, Meta and Google Ads tags the page requested
+just before and after it — the tag's kind, its id and, for Meta, the event —
+read from the browser's own record of the page's requests. Nothing else of
+those requests is kept. A conversion is held ten seconds so those requests can
+be seen, sent at once when the page is hidden — its report then says whether it
+was cut short — and never held in verification mode. Context keys beginning
+with `__tl.` are TraceLog's and are removed.
+
 Identity is first-party and per site: no cross-site tracking, no fingerprinting.
 An IP address is read once when the event arrives to derive a two-letter country
 code, then discarded.

package/dist/tracelog.esm.js

@@ -3,10 +3,16 @@ const MAX_BATCH_BYTES = 262144;
 const MAX_BATCH_EVENTS = 50;
 const MAX_CONTEXT_BYTES = 8192;
 const MAX_ERROR_MESSAGE_BYTES = 1024;
+const MAX_TAG_SIGHTINGS = 16;
+const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
+const TAG_ID_PATTERNS = {"ga4":"^G-[A-Z0-9]{4,15}$","meta":"^[0-9]{6,20}$","google_ads":"^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$"};
+const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
 const CONSENT_KEY = "__tl.c";
 const SESSION_KEY = "__tl.s";
 const ACTIVITY_KEY = "__tl.a";
 const QUEUE_KEY = "__tl.q";
+/** The namespace the runtime owns, in storage and in an event's context. */
+const RUNTIME_KEY_PREFIX = "__tl.";
 /**
  * How many events wait in memory before consent. A platform artifact that
  * buffers its own platform's events ahead of this engine holds the same line,
@@ -30,6 +36,13 @@ const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 const MAX_IDENTIFIER_LENGTH = 256;
 const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 const textEncoder = new TextEncoder();
+/**
+ * The tag sighting window around a conversion ([spec/capture.md] § Tag
+ * sightings). Ten seconds after is almost twice the longest hold measured:
+ * GA4 was measured holding a purchase 5.0 to 5.6 seconds.
+ */
+const TAG_SIGHTING_BEFORE_MS = 30000;
+const TAG_SIGHTING_AFTER_MS = 10000;
 function safeGet(storage, key) {
     try {
         return storage.getItem(key);
@@ -120,7 +133,12 @@ function jsonContext(value) {
             Array.isArray(parsed)) {
             return undefined;
         }
-        return parsed;
+        const context = parsed;
+        for (const key of Object.keys(context)) {
+            if (key.startsWith(RUNTIME_KEY_PREFIX))
+                delete context[key];
+        }
+        return context;
     }
     catch {
         return undefined;
@@ -149,6 +167,9 @@ function isConversionValid(options) {
             (Number.isFinite(options.value) && options.value >= 0)) &&
         (options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
 }
+function serializedBytes(value) {
+    return textEncoder.encode(JSON.stringify(value)).byteLength;
+}
 function batchFrom(events) {
     const selected = [];
     const unsendable = [];
@@ -159,7 +180,7 @@ function batchFrom(events) {
             v: EVENT_ENVELOPE_VERSION,
             events: [...selected, event],
         };
-        if (textEncoder.encode(JSON.stringify(candidate)).byteLength > MAX_BATCH_BYTES) {
+        if (serializedBytes(candidate) > MAX_BATCH_BYTES) {
             if (selected.length === 0) {
                 unsendable.push(event);
                 continue;
@@ -176,7 +197,20 @@ function createCaptureEngine(ports, acquisition) {
     let config = { key: "", endpoint: "/v1/events" };
     let pending = [];
     let lastDeclaredName;
-    let sending = false;
+    /**
+     * Every send in flight, by count and by the union of their event ids: a
+     * page hide sends alongside one rather than wait for it, so there can be
+     * two, and each must leave the other's events alone.
+     */
+    let sendsInFlight = 0;
+    const inFlight = new Set();
+    /**
+     * The conversions this page emitted and holds for their tag sighting
+     * window: the instant each was emitted, and whether its report can be
+     * complete. In memory only — a held conversion is in the stored queue like
+     * any other, and a reload sends it as it is.
+     */
+    const held = new Map();
     let flushTimer;
     let consecutiveFailures = 0;
     let circuit = "closed";
@@ -224,7 +258,12 @@ function createCaptureEngine(ports, acquisition) {
         addDrop(queue, "invalid_event");
         writeQueue(ports.storage, queue);
     }
-    function emit(pendingEvent) {
+    /**
+     * `buffered` is a conversion made before consent was granted and emitted
+     * at the grant: its window is placed there, after the conversion itself,
+     * so its report is never complete.
+     */
+    function emit(pendingEvent, buffered = false) {
         if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
             recordInvalidEvent();
             return;
@@ -261,8 +300,13 @@ function createCaptureEngine(ports, acquisition) {
         else {
             const options = pendingEvent.options;
             const context = jsonContext(options.context);
+            const base = baseEvent(now, session.id);
+            if (acquisition.mode !== "verification" &&
+                ports.sightings?.observing() === true) {
+                held.set(base.eventId, { at: now.getTime(), whole: !buffered });
+            }
             persistEvent({
-                ...baseEvent(now, session.id),
+                ...base,
                 kind: "conversion",
                 name: pendingEvent.name,
                 identifier: options.identifier,
@@ -285,12 +329,80 @@ function createCaptureEngine(ports, acquisition) {
         }
         emit(pendingEvent);
     }
+    /**
+     * Gives each held conversion whose window has closed — or every one, at
+     * page hide — the report of what the port saw around it, and lets it go.
+     */
+    function release(all) {
+        if (held.size === 0)
+            return;
+        const now = ports.clock.now().getTime();
+        const due = [...held].filter(([, hold]) => all || now - hold.at >= TAG_SIGHTING_AFTER_MS);
+        if (due.length === 0)
+            return;
+        const queue = readQueue(ports.storage);
+        let reported = false;
+        for (const [eventId, hold] of due) {
+            held.delete(eventId);
+            // Gone from the queue — sent by another tab, or dropped by overflow.
+            const event = queue.events.find((candidate) => candidate.eventId === eventId);
+            const answer = event === undefined
+                ? null
+                : (ports.sightings?.around(new Date(hold.at)) ?? null);
+            if (event === undefined || answer === null)
+                continue;
+            const report = {
+                complete: hold.whole &&
+                    now - hold.at >= TAG_SIGHTING_AFTER_MS &&
+                    answer.length <= MAX_TAG_SIGHTINGS,
+                sightings: answer.slice(0, MAX_TAG_SIGHTINGS),
+            };
+            const context = {
+                ...event.context,
+                [TAG_SIGHTINGS_CONTEXT_KEY]: report,
+            };
+            if (serializedBytes(context) <= MAX_CONTEXT_BYTES) {
+                event.context = context;
+                reported = true;
+            }
+        }
+        if (reported)
+            writeQueue(ports.storage, queue);
+    }
+    /** Until the earliest held conversion's window closes. */
+    function untilRelease() {
+        const now = ports.clock.now().getTime();
+        let earliest = Number.POSITIVE_INFINITY;
+        for (const hold of held.values()) {
+            earliest = Math.min(earliest, hold.at + TAG_SIGHTING_AFTER_MS);
+        }
+        return Math.max(0, earliest - now);
+    }
     async function flush(keepalive = false) {
-        if (!initialized || consentState !== "granted" || sending)
+        release(keepalive);
+        if (!initialized || consentState !== "granted")
+            return;
+        if (sendsInFlight > 0 && !keepalive)
             return;
         const queue = readQueue(ports.storage);
-        if (queue.events.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
-            scheduleFlush(FLUSH_INTERVAL_MS);
+        const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
+        if (ready.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
+            if (sendsInFlight === 0) {
+                scheduleFlush(ready.length === 0 && held.size > 0
+                    ? untilRelease()
+                    : FLUSH_INTERVAL_MS);
+            }
+            return;
+        }
+        /**
+         * A page being hidden gets no later chance, so it sends what no send in
+         * flight carries at once, whatever the circuit's state, and the answer is
+         * read as any other's.
+         */
+        if (sendsInFlight > 0) {
+            const { batch } = batchFrom(ready);
+            if (batch.events.length > 0)
+                await deliver(batch, true);
             return;
         }
         const now = ports.clock.now().getTime();
@@ -301,7 +413,7 @@ function createCaptureEngine(ports, acquisition) {
             }
             circuit = "half_open";
         }
-        const { batch, unsendable } = batchFrom(queue.events);
+        const { batch, unsendable } = batchFrom(ready);
         if (unsendable.length > 0) {
             const dropped = new Set(unsendable.map((event) => event.eventId));
             queue.events = queue.events.filter((event) => !dropped.has(event.eventId));
@@ -312,7 +424,18 @@ function createCaptureEngine(ports, acquisition) {
             scheduleFlush(FLUSH_INTERVAL_MS);
             return;
         }
-        sending = true;
+        await deliver(batch, keepalive);
+    }
+    /**
+     * One send, and its answer. It removes from the stored queue exactly what
+     * it carried, by its own read, filter and write at the moment it settles,
+     * so a send beside it keeps what it delivered.
+     */
+    async function deliver(batch, keepalive) {
+        const carried = new Set(batch.events.map((event) => event.eventId));
+        for (const eventId of carried)
+            inFlight.add(eventId);
+        sendsInFlight += 1;
         try {
             const response = await ports.transport.send({
                 endpoint: config.endpoint,
@@ -322,8 +445,7 @@ function createCaptureEngine(ports, acquisition) {
             });
             if (response.status >= 200 && response.status < 300) {
                 const currentQueue = readQueue(ports.storage);
-                const delivered = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !delivered.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 if ((response.rejected ?? 0) > 0) {
                     addDrop(currentQueue, "server_rejected", response.rejected);
                 }
@@ -345,8 +467,7 @@ function createCaptureEngine(ports, acquisition) {
                 response.status < 500 &&
                 response.status !== 429) {
                 const currentQueue = readQueue(ports.storage);
-                const rejected = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !rejected.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 addDrop(currentQueue, "server_rejected", batch.events.length);
                 writeQueue(ports.storage, currentQueue);
                 consecutiveFailures = 0;
@@ -369,7 +490,9 @@ function createCaptureEngine(ports, acquisition) {
             }
         }
         finally {
-            sending = false;
+            for (const eventId of carried)
+                inFlight.delete(eventId);
+            sendsInFlight -= 1;
         }
     }
     const engine = {
@@ -384,8 +507,10 @@ function createCaptureEngine(ports, acquisition) {
                 storedConsent === "granted" || storedConsent === "denied"
                     ? storedConsent
                     : "unknown";
-            if (consentState === "granted")
+            if (consentState === "granted") {
+                ports.sightings?.start();
                 scheduleFlush(FLUSH_INTERVAL_MS);
+            }
         },
         consent: {
             grant() {
@@ -393,10 +518,11 @@ function createCaptureEngine(ports, acquisition) {
                     return;
                 consentState = "granted";
                 safeSet(ports.storage, CONSENT_KEY, "granted");
+                ports.sightings?.start();
                 const buffered = pending;
                 pending = [];
                 for (const pendingEvent of buffered)
-                    emit(pendingEvent);
+                    emit(pendingEvent, true);
                 scheduleFlush(FLUSH_INTERVAL_MS);
             },
             deny() {
@@ -405,6 +531,8 @@ function createCaptureEngine(ports, acquisition) {
                 consentState = "denied";
                 pending = [];
                 lastDeclaredName = undefined;
+                ports.sightings?.stop();
+                held.clear();
                 safeSet(ports.storage, CONSENT_KEY, "denied");
                 safeRemove(ports.storage, SESSION_KEY);
                 safeRemove(ports.storage, ACTIVITY_KEY);
@@ -480,6 +608,153 @@ function createCaptureEngine(ports, acquisition) {
 const systemClock = {
     now: () => new Date(Date.now()),
 };
+/**
+ * A Resource Timing entry's start, on the system clock: its reading minus the
+ * entry's monotonic age. `performance.timeOrigin` would be a second clock, and
+ * it can disagree with this one by as much as the machine's clock drifted
+ * since the page loaded; the age is read on one clock and the instant on the
+ * other, so a sighting and the conversion it is compared with are dated alike
+ * ([spec/capture.md] § Tag sightings).
+ */
+function instantOfEntry(startTime) {
+    return new Date(systemClock.now().getTime() - (performance.now() - startTime));
+}
+/**
+ * How many matches the port keeps. A page making more tag requests than this
+ * inside one window is one whose report the port declines to give, never one
+ * it gives short.
+ */
+const TAG_SIGHTING_MEMORY = 100;
+const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
+const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
+const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
+const tagEventPattern = new RegExp(TAG_EVENT_PATTERN);
+const adsPathPattern = /^\/pagead\/(?:conversion|viewthroughconversion|1p-conversion)\/([0-9]{6,15})\/$/;
+/**
+ * The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
+ * key on the path and the id, so a regional host and a first-party tagging
+ * domain that keeps the path both match; Meta keys on its host as well. What
+ * is answered is the tag's kind, its id and Meta's event — nothing else of
+ * the URL, which carries the page address and the vendor's client id.
+ */
+function matchTagRequest(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const path = parsed.pathname;
+    const parameters = parsed.searchParams;
+    if (path.endsWith("/g/collect")) {
+        const id = parameters.get("tid");
+        return id !== null && ga4IdPattern.test(id)
+            ? { kind: "ga4", id, event: null }
+            : null;
+    }
+    const host = parsed.hostname;
+    if ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
+        (path === "/tr" || path === "/tr/")) {
+        const id = parameters.get("id");
+        if (id === null || !metaIdPattern.test(id))
+            return null;
+        const event = parameters.get("ev");
+        return {
+            kind: "meta",
+            id,
+            event: event !== null && tagEventPattern.test(event) ? event : null,
+        };
+    }
+    const ads = adsPathPattern.exec(path);
+    if (ads !== null) {
+        const id = `AW-${ads[1]}`;
+        const labelled = `${id}/${parameters.get("label") ?? ""}`;
+        return {
+            kind: "google_ads",
+            id: adsIdPattern.test(labelled) ? labelled : id,
+            event: null,
+        };
+    }
+    return null;
+}
+/**
+ * The browser's own record of the page's requests, read through a buffered
+ * `PerformanceObserver` once consent is granted and never before. Nothing is
+ * wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
+ * because the runtime runs on somebody else's page and nothing it does may
+ * change what another script sees.
+ */
+function createTagSightingPort() {
+    let observer;
+    /** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
+    let matches = [];
+    function record(entries) {
+        for (const entry of entries) {
+            const sighting = matchTagRequest(entry.name);
+            if (sighting === null)
+                continue;
+            const match = { sighting, at: instantOfEntry(entry.startTime).getTime() };
+            let index = matches.length;
+            while (index > 0 && matches[index - 1].at > match.at)
+                index -= 1;
+            matches.splice(index, 0, match);
+            if (matches.length > TAG_SIGHTING_MEMORY)
+                matches.shift();
+        }
+    }
+    return {
+        start() {
+            if (observer !== undefined)
+                return;
+            try {
+                const Observer = window.PerformanceObserver;
+                if (Observer === undefined ||
+                    !Observer.supportedEntryTypes.includes("resource")) {
+                    return;
+                }
+                const created = new Observer((list) => record(list.getEntries()));
+                created.observe({ type: "resource", buffered: true });
+                observer = created;
+            }
+            catch {
+                observer = undefined;
+            }
+        },
+        stop() {
+            observer?.disconnect();
+            observer = undefined;
+            matches = [];
+        },
+        observing() {
+            return observer !== undefined;
+        },
+        around(at) {
+            if (observer === undefined)
+                return null;
+            // What the browser recorded and has not delivered yet: a page being
+            // hidden may not run the callback before the conversion leaves.
+            record(observer.takeRecords());
+            const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
+            const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
+            if (matches.length >= TAG_SIGHTING_MEMORY && matches[0].at > from) {
+                return null;
+            }
+            const seen = new Set();
+            const sightings = [];
+            for (const { sighting, at: started } of matches) {
+                if (started < from || started > to)
+                    continue;
+                const key = `${sighting.kind} ${sighting.id} ${sighting.event ?? ""}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                sightings.push(sighting);
+            }
+            return sightings;
+        },
+    };
+}
 const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 class MemoryStorage {
     constructor() {
@@ -656,6 +931,7 @@ function init(options) {
                     }
                 },
             },
+            sightings: createTagSightingPort(),
         }, acquisition());
         engine = runtime.engine;
     }

package/dist/tracelog.iife.js

@@ -4,10 +4,16 @@ const MAX_BATCH_BYTES = 262144;
 const MAX_BATCH_EVENTS = 50;
 const MAX_CONTEXT_BYTES = 8192;
 const MAX_ERROR_MESSAGE_BYTES = 1024;
+const MAX_TAG_SIGHTINGS = 16;
+const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
+const TAG_ID_PATTERNS = {"ga4":"^G-[A-Z0-9]{4,15}$","meta":"^[0-9]{6,20}$","google_ads":"^AW-[0-9]{6,15}(?:/[A-Za-z0-9_-]{1,64})?$"};
+const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
 const CONSENT_KEY = "__tl.c";
 const SESSION_KEY = "__tl.s";
 const ACTIVITY_KEY = "__tl.a";
 const QUEUE_KEY = "__tl.q";
+/** The namespace the runtime owns, in storage and in an event's context. */
+const RUNTIME_KEY_PREFIX = "__tl.";
 /**
  * How many events wait in memory before consent. A platform artifact that
  * buffers its own platform's events ahead of this engine holds the same line,
@@ -31,6 +37,13 @@ const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 const MAX_IDENTIFIER_LENGTH = 256;
 const CURRENCY_PATTERN = /^[A-Z]{3}$/;
 const textEncoder = new TextEncoder();
+/**
+ * The tag sighting window around a conversion ([spec/capture.md] § Tag
+ * sightings). Ten seconds after is almost twice the longest hold measured:
+ * GA4 was measured holding a purchase 5.0 to 5.6 seconds.
+ */
+const TAG_SIGHTING_BEFORE_MS = 30000;
+const TAG_SIGHTING_AFTER_MS = 10000;
 function safeGet(storage, key) {
     try {
         return storage.getItem(key);
@@ -121,7 +134,12 @@ function jsonContext(value) {
             Array.isArray(parsed)) {
             return undefined;
         }
-        return parsed;
+        const context = parsed;
+        for (const key of Object.keys(context)) {
+            if (key.startsWith(RUNTIME_KEY_PREFIX))
+                delete context[key];
+        }
+        return context;
     }
     catch {
         return undefined;
@@ -150,6 +168,9 @@ function isConversionValid(options) {
             (Number.isFinite(options.value) && options.value >= 0)) &&
         (options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
 }
+function serializedBytes(value) {
+    return textEncoder.encode(JSON.stringify(value)).byteLength;
+}
 function batchFrom(events) {
     const selected = [];
     const unsendable = [];
@@ -160,7 +181,7 @@ function batchFrom(events) {
             v: EVENT_ENVELOPE_VERSION,
             events: [...selected, event],
         };
-        if (textEncoder.encode(JSON.stringify(candidate)).byteLength > MAX_BATCH_BYTES) {
+        if (serializedBytes(candidate) > MAX_BATCH_BYTES) {
             if (selected.length === 0) {
                 unsendable.push(event);
                 continue;
@@ -177,7 +198,20 @@ function createCaptureEngine(ports, acquisition) {
     let config = { key: "", endpoint: "/v1/events" };
     let pending = [];
     let lastDeclaredName;
-    let sending = false;
+    /**
+     * Every send in flight, by count and by the union of their event ids: a
+     * page hide sends alongside one rather than wait for it, so there can be
+     * two, and each must leave the other's events alone.
+     */
+    let sendsInFlight = 0;
+    const inFlight = new Set();
+    /**
+     * The conversions this page emitted and holds for their tag sighting
+     * window: the instant each was emitted, and whether its report can be
+     * complete. In memory only — a held conversion is in the stored queue like
+     * any other, and a reload sends it as it is.
+     */
+    const held = new Map();
     let flushTimer;
     let consecutiveFailures = 0;
     let circuit = "closed";
@@ -225,7 +259,12 @@ function createCaptureEngine(ports, acquisition) {
         addDrop(queue, "invalid_event");
         writeQueue(ports.storage, queue);
     }
-    function emit(pendingEvent) {
+    /**
+     * `buffered` is a conversion made before consent was granted and emitted
+     * at the grant: its window is placed there, after the conversion itself,
+     * so its report is never complete.
+     */
+    function emit(pendingEvent, buffered = false) {
         if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
             recordInvalidEvent();
             return;
@@ -262,8 +301,13 @@ function createCaptureEngine(ports, acquisition) {
         else {
             const options = pendingEvent.options;
             const context = jsonContext(options.context);
+            const base = baseEvent(now, session.id);
+            if (acquisition.mode !== "verification" &&
+                ports.sightings?.observing() === true) {
+                held.set(base.eventId, { at: now.getTime(), whole: !buffered });
+            }
             persistEvent({
-                ...baseEvent(now, session.id),
+                ...base,
                 kind: "conversion",
                 name: pendingEvent.name,
                 identifier: options.identifier,
@@ -286,12 +330,80 @@ function createCaptureEngine(ports, acquisition) {
         }
         emit(pendingEvent);
     }
+    /**
+     * Gives each held conversion whose window has closed — or every one, at
+     * page hide — the report of what the port saw around it, and lets it go.
+     */
+    function release(all) {
+        if (held.size === 0)
+            return;
+        const now = ports.clock.now().getTime();
+        const due = [...held].filter(([, hold]) => all || now - hold.at >= TAG_SIGHTING_AFTER_MS);
+        if (due.length === 0)
+            return;
+        const queue = readQueue(ports.storage);
+        let reported = false;
+        for (const [eventId, hold] of due) {
+            held.delete(eventId);
+            // Gone from the queue — sent by another tab, or dropped by overflow.
+            const event = queue.events.find((candidate) => candidate.eventId === eventId);
+            const answer = event === undefined
+                ? null
+                : (ports.sightings?.around(new Date(hold.at)) ?? null);
+            if (event === undefined || answer === null)
+                continue;
+            const report = {
+                complete: hold.whole &&
+                    now - hold.at >= TAG_SIGHTING_AFTER_MS &&
+                    answer.length <= MAX_TAG_SIGHTINGS,
+                sightings: answer.slice(0, MAX_TAG_SIGHTINGS),
+            };
+            const context = {
+                ...event.context,
+                [TAG_SIGHTINGS_CONTEXT_KEY]: report,
+            };
+            if (serializedBytes(context) <= MAX_CONTEXT_BYTES) {
+                event.context = context;
+                reported = true;
+            }
+        }
+        if (reported)
+            writeQueue(ports.storage, queue);
+    }
+    /** Until the earliest held conversion's window closes. */
+    function untilRelease() {
+        const now = ports.clock.now().getTime();
+        let earliest = Number.POSITIVE_INFINITY;
+        for (const hold of held.values()) {
+            earliest = Math.min(earliest, hold.at + TAG_SIGHTING_AFTER_MS);
+        }
+        return Math.max(0, earliest - now);
+    }
     async function flush(keepalive = false) {
-        if (!initialized || consentState !== "granted" || sending)
+        release(keepalive);
+        if (!initialized || consentState !== "granted")
+            return;
+        if (sendsInFlight > 0 && !keepalive)
             return;
         const queue = readQueue(ports.storage);
-        if (queue.events.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
-            scheduleFlush(FLUSH_INTERVAL_MS);
+        const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
+        if (ready.length === 0 || !PUBLIC_KEY_PATTERN.test(config.key)) {
+            if (sendsInFlight === 0) {
+                scheduleFlush(ready.length === 0 && held.size > 0
+                    ? untilRelease()
+                    : FLUSH_INTERVAL_MS);
+            }
+            return;
+        }
+        /**
+         * A page being hidden gets no later chance, so it sends what no send in
+         * flight carries at once, whatever the circuit's state, and the answer is
+         * read as any other's.
+         */
+        if (sendsInFlight > 0) {
+            const { batch } = batchFrom(ready);
+            if (batch.events.length > 0)
+                await deliver(batch, true);
             return;
         }
         const now = ports.clock.now().getTime();
@@ -302,7 +414,7 @@ function createCaptureEngine(ports, acquisition) {
             }
             circuit = "half_open";
         }
-        const { batch, unsendable } = batchFrom(queue.events);
+        const { batch, unsendable } = batchFrom(ready);
         if (unsendable.length > 0) {
             const dropped = new Set(unsendable.map((event) => event.eventId));
             queue.events = queue.events.filter((event) => !dropped.has(event.eventId));
@@ -313,7 +425,18 @@ function createCaptureEngine(ports, acquisition) {
             scheduleFlush(FLUSH_INTERVAL_MS);
             return;
         }
-        sending = true;
+        await deliver(batch, keepalive);
+    }
+    /**
+     * One send, and its answer. It removes from the stored queue exactly what
+     * it carried, by its own read, filter and write at the moment it settles,
+     * so a send beside it keeps what it delivered.
+     */
+    async function deliver(batch, keepalive) {
+        const carried = new Set(batch.events.map((event) => event.eventId));
+        for (const eventId of carried)
+            inFlight.add(eventId);
+        sendsInFlight += 1;
         try {
             const response = await ports.transport.send({
                 endpoint: config.endpoint,
@@ -323,8 +446,7 @@ function createCaptureEngine(ports, acquisition) {
             });
             if (response.status >= 200 && response.status < 300) {
                 const currentQueue = readQueue(ports.storage);
-                const delivered = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !delivered.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 if ((response.rejected ?? 0) > 0) {
                     addDrop(currentQueue, "server_rejected", response.rejected);
                 }
@@ -346,8 +468,7 @@ function createCaptureEngine(ports, acquisition) {
                 response.status < 500 &&
                 response.status !== 429) {
                 const currentQueue = readQueue(ports.storage);
-                const rejected = new Set(batch.events.map((event) => event.eventId));
-                currentQueue.events = currentQueue.events.filter((event) => !rejected.has(event.eventId));
+                currentQueue.events = currentQueue.events.filter((event) => !carried.has(event.eventId));
                 addDrop(currentQueue, "server_rejected", batch.events.length);
                 writeQueue(ports.storage, currentQueue);
                 consecutiveFailures = 0;
@@ -370,7 +491,9 @@ function createCaptureEngine(ports, acquisition) {
             }
         }
         finally {
-            sending = false;
+            for (const eventId of carried)
+                inFlight.delete(eventId);
+            sendsInFlight -= 1;
         }
     }
     const engine = {
@@ -385,8 +508,10 @@ function createCaptureEngine(ports, acquisition) {
                 storedConsent === "granted" || storedConsent === "denied"
                     ? storedConsent
                     : "unknown";
-            if (consentState === "granted")
+            if (consentState === "granted") {
+                ports.sightings?.start();
                 scheduleFlush(FLUSH_INTERVAL_MS);
+            }
         },
         consent: {
             grant() {
@@ -394,10 +519,11 @@ function createCaptureEngine(ports, acquisition) {
                     return;
                 consentState = "granted";
                 safeSet(ports.storage, CONSENT_KEY, "granted");
+                ports.sightings?.start();
                 const buffered = pending;
                 pending = [];
                 for (const pendingEvent of buffered)
-                    emit(pendingEvent);
+                    emit(pendingEvent, true);
                 scheduleFlush(FLUSH_INTERVAL_MS);
             },
             deny() {
@@ -406,6 +532,8 @@ function createCaptureEngine(ports, acquisition) {
                 consentState = "denied";
                 pending = [];
                 lastDeclaredName = undefined;
+                ports.sightings?.stop();
+                held.clear();
                 safeSet(ports.storage, CONSENT_KEY, "denied");
                 safeRemove(ports.storage, SESSION_KEY);
                 safeRemove(ports.storage, ACTIVITY_KEY);
@@ -481,6 +609,153 @@ function createCaptureEngine(ports, acquisition) {
 const systemClock = {
     now: () => new Date(Date.now()),
 };
+/**
+ * A Resource Timing entry's start, on the system clock: its reading minus the
+ * entry's monotonic age. `performance.timeOrigin` would be a second clock, and
+ * it can disagree with this one by as much as the machine's clock drifted
+ * since the page loaded; the age is read on one clock and the instant on the
+ * other, so a sighting and the conversion it is compared with are dated alike
+ * ([spec/capture.md] § Tag sightings).
+ */
+function instantOfEntry(startTime) {
+    return new Date(systemClock.now().getTime() - (performance.now() - startTime));
+}
+/**
+ * How many matches the port keeps. A page making more tag requests than this
+ * inside one window is one whose report the port declines to give, never one
+ * it gives short.
+ */
+const TAG_SIGHTING_MEMORY = 100;
+const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
+const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
+const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
+const tagEventPattern = new RegExp(TAG_EVENT_PATTERN);
+const adsPathPattern = /^\/pagead\/(?:conversion|viewthroughconversion|1p-conversion)\/([0-9]{6,15})\/$/;
+/**
+ * The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
+ * key on the path and the id, so a regional host and a first-party tagging
+ * domain that keeps the path both match; Meta keys on its host as well. What
+ * is answered is the tag's kind, its id and Meta's event — nothing else of
+ * the URL, which carries the page address and the vendor's client id.
+ */
+function matchTagRequest(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        return null;
+    }
+    const path = parsed.pathname;
+    const parameters = parsed.searchParams;
+    if (path.endsWith("/g/collect")) {
+        const id = parameters.get("tid");
+        return id !== null && ga4IdPattern.test(id)
+            ? { kind: "ga4", id, event: null }
+            : null;
+    }
+    const host = parsed.hostname;
+    if ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
+        (path === "/tr" || path === "/tr/")) {
+        const id = parameters.get("id");
+        if (id === null || !metaIdPattern.test(id))
+            return null;
+        const event = parameters.get("ev");
+        return {
+            kind: "meta",
+            id,
+            event: event !== null && tagEventPattern.test(event) ? event : null,
+        };
+    }
+    const ads = adsPathPattern.exec(path);
+    if (ads !== null) {
+        const id = `AW-${ads[1]}`;
+        const labelled = `${id}/${parameters.get("label") ?? ""}`;
+        return {
+            kind: "google_ads",
+            id: adsIdPattern.test(labelled) ? labelled : id,
+            event: null,
+        };
+    }
+    return null;
+}
+/**
+ * The browser's own record of the page's requests, read through a buffered
+ * `PerformanceObserver` once consent is granted and never before. Nothing is
+ * wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
+ * because the runtime runs on somebody else's page and nothing it does may
+ * change what another script sees.
+ */
+function createTagSightingPort() {
+    let observer;
+    /** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
+    let matches = [];
+    function record(entries) {
+        for (const entry of entries) {
+            const sighting = matchTagRequest(entry.name);
+            if (sighting === null)
+                continue;
+            const match = { sighting, at: instantOfEntry(entry.startTime).getTime() };
+            let index = matches.length;
+            while (index > 0 && matches[index - 1].at > match.at)
+                index -= 1;
+            matches.splice(index, 0, match);
+            if (matches.length > TAG_SIGHTING_MEMORY)
+                matches.shift();
+        }
+    }
+    return {
+        start() {
+            if (observer !== undefined)
+                return;
+            try {
+                const Observer = window.PerformanceObserver;
+                if (Observer === undefined ||
+                    !Observer.supportedEntryTypes.includes("resource")) {
+                    return;
+                }
+                const created = new Observer((list) => record(list.getEntries()));
+                created.observe({ type: "resource", buffered: true });
+                observer = created;
+            }
+            catch {
+                observer = undefined;
+            }
+        },
+        stop() {
+            observer?.disconnect();
+            observer = undefined;
+            matches = [];
+        },
+        observing() {
+            return observer !== undefined;
+        },
+        around(at) {
+            if (observer === undefined)
+                return null;
+            // What the browser recorded and has not delivered yet: a page being
+            // hidden may not run the callback before the conversion leaves.
+            record(observer.takeRecords());
+            const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
+            const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
+            if (matches.length >= TAG_SIGHTING_MEMORY && matches[0].at > from) {
+                return null;
+            }
+            const seen = new Set();
+            const sightings = [];
+            for (const { sighting, at: started } of matches) {
+                if (started < from || started > to)
+                    continue;
+                const key = `${sighting.kind} ${sighting.id} ${sighting.event ?? ""}`;
+                if (seen.has(key))
+                    continue;
+                seen.add(key);
+                sightings.push(sighting);
+            }
+            return sightings;
+        },
+    };
+}
 const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
 class MemoryStorage {
     constructor() {
@@ -657,6 +932,7 @@ function init(options) {
                     }
                 },
             },
+            sightings: createTagSightingPort(),
         }, acquisition());
         engine = runtime.engine;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tracelog/capture-web",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "The TraceLog browser capture runtime: consent-first, pinned per version.",
   "keywords": [
     "conversion",
@@ -45,7 +45,8 @@
     "access": "public"
   },
   "devDependencies": {
-    "@tracelog/capture-core": "1.0.0"
+    "@tracelog/capture-core": "1.1.0",
+    "@tracelog/event-contract": "1.1.0"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node build.mjs",