@tracelog/capture-web 2.0.0 → 2.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +18 -0
- package/README.md +14 -10
- package/dist/tracelog.d.ts +18 -1
- package/dist/tracelog.esm.js +66 -174
- package/dist/tracelog.iife.js +66 -174
- package/package.json +4 -3
package/CHANGELOG.md
CHANGED
|
@@ -18,6 +18,24 @@ patch, and neither requires reading your code.
|
|
|
18
18
|
Entries after 1.0.0 are drafted from the commits that touched this package and
|
|
19
19
|
edited before release.
|
|
20
20
|
|
|
21
|
+
## [2.1.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.0.1...capture-web@2.1.0) (2026-10-06)
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
### Added
|
|
25
|
+
|
|
26
|
+
* **capture-core:** a conversion's items, day and recurrence, and a step's items ([98a5dd6](https://github.com/nacorga/tracelog-sdk/commit/98a5dd6daa131cbc92ddf8ad271a53bc243d4e72))
|
|
27
|
+
* **capture-web:** step takes its items as a third argument ([32eddbf](https://github.com/nacorga/tracelog-sdk/commit/32eddbfa4023eaff4dfb24e4b80c081266b3dd50))
|
|
28
|
+
|
|
29
|
+
|
|
30
|
+
### Fixed
|
|
31
|
+
|
|
32
|
+
* **capture-web:** the bundle carries no comments ([da8d145](https://github.com/nacorga/tracelog-sdk/commit/da8d145e9bb8ac5bece5e9a59fb0f1e47bc212e3))
|
|
33
|
+
|
|
34
|
+
## [2.0.1](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.0.0...capture-web@2.0.1) (2026-10-02)
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
* **capture-web:** Synchronize tracelog-sdk versions
|
|
38
|
+
|
|
21
39
|
## [2.0.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@1.3.1...capture-web@2.0.0) (2026-10-01)
|
|
22
40
|
|
|
23
41
|
|
package/README.md
CHANGED
|
@@ -22,13 +22,13 @@ as they are served.
|
|
|
22
22
|
<!-- x-release-please-start-version -->
|
|
23
23
|
|
|
24
24
|
```bash
|
|
25
|
-
npm install --save-exact @tracelog/capture-web@2.
|
|
25
|
+
npm install --save-exact @tracelog/capture-web@2.1.0
|
|
26
26
|
```
|
|
27
27
|
|
|
28
28
|
Without a build step, the same runtime as a script tag:
|
|
29
29
|
|
|
30
30
|
```html
|
|
31
|
-
<script src="https://cdn.tracelog.io/v/2.
|
|
31
|
+
<script src="https://cdn.tracelog.io/v/2.1.0/tracelog.js"></script>
|
|
32
32
|
```
|
|
33
33
|
|
|
34
34
|
<!-- x-release-please-end -->
|
|
@@ -69,14 +69,14 @@ visitors nothing.
|
|
|
69
69
|
|
|
70
70
|
That is all of it, and it is what the major version protects.
|
|
71
71
|
|
|
72
|
-
| Call
|
|
73
|
-
|
|
|
74
|
-
| `TraceLog.init(options)`
|
|
75
|
-
| `TraceLog.consent.grant()`
|
|
76
|
-
| `TraceLog.consent.deny()`
|
|
77
|
-
| `TraceLog.consent.state()`
|
|
78
|
-
| `TraceLog.step(name, context?)`
|
|
79
|
-
| `TraceLog.conversion(name, opts)`
|
|
72
|
+
| Call | Does |
|
|
73
|
+
| -------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
74
|
+
| `TraceLog.init(options)` | Configures the runtime. `key` is the project's public key. |
|
|
75
|
+
| `TraceLog.consent.grant()` | Allows capture. Queued delivery begins. |
|
|
76
|
+
| `TraceLog.consent.deny()` | Keeps the runtime inert. |
|
|
77
|
+
| `TraceLog.consent.state()` | `"unknown" \| "granted" \| "denied"`. |
|
|
78
|
+
| `TraceLog.step(name, context?, opts?)` | A declared step of the conversion path. `opts.items` are the items it shows. |
|
|
79
|
+
| `TraceLog.conversion(name, opts)` | A declared conversion. `opts.identifier` is its stable identifier. `opts.items`, `opts.scheduledFor` and `opts.recurring` say what it was for. |
|
|
80
80
|
|
|
81
81
|
`init` also accepts `mode: "verification"`, which a distributed platform artifact
|
|
82
82
|
declares for its platform's own test order. A site's own snippet never sets it —
|
|
@@ -101,6 +101,10 @@ The events your tracking plan declares, with their context. Not page views, not
|
|
|
101
101
|
clicks, not scroll, not keystrokes. Errors are captured only when they occur
|
|
102
102
|
inside the conversion path, attached to the step where they happened.
|
|
103
103
|
|
|
104
|
+
A conversion may carry its items, the day a booking is for and whether it
|
|
105
|
+
recurs, and a step the items it shows; a malformed one is left out and the
|
|
106
|
+
event sent without it.
|
|
107
|
+
|
|
104
108
|
Beside each conversion, which GA4, Meta and Google Ads tags the page requested
|
|
105
109
|
just before and after it — the tag's kind, its id and, for Meta, the event —
|
|
106
110
|
read from the browser's own record of the page's requests and, for the one
|
package/dist/tracelog.d.ts
CHANGED
|
@@ -7,17 +7,34 @@ export interface InitOptions {
|
|
|
7
7
|
mode?: "verification";
|
|
8
8
|
}
|
|
9
9
|
|
|
10
|
+
export interface Item {
|
|
11
|
+
id: string;
|
|
12
|
+
name: string;
|
|
13
|
+
category?: string;
|
|
14
|
+
quantity: number;
|
|
15
|
+
/** The price of one unit; on a conversion, in its currency. */
|
|
16
|
+
price?: number;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
export interface StepOptions {
|
|
20
|
+
items?: Item[];
|
|
21
|
+
}
|
|
22
|
+
|
|
10
23
|
export interface ConversionOptions {
|
|
11
24
|
identifier: string;
|
|
12
25
|
value?: number;
|
|
13
26
|
currency?: string;
|
|
14
27
|
context?: object;
|
|
28
|
+
items?: Item[];
|
|
29
|
+
/** The day a booking is for, YYYY-MM-DD. */
|
|
30
|
+
scheduledFor?: string;
|
|
31
|
+
recurring?: boolean;
|
|
15
32
|
}
|
|
16
33
|
|
|
17
34
|
declare const TraceLog: {
|
|
18
35
|
init(options: InitOptions): void;
|
|
19
36
|
consent: { grant(): void; deny(): void; state(): ConsentState };
|
|
20
|
-
step(name: string, context?: object): void;
|
|
37
|
+
step(name: string, context?: object, options?: StepOptions): void;
|
|
21
38
|
conversion(name: string, options: ConversionOptions): void;
|
|
22
39
|
};
|
|
23
40
|
|
package/dist/tracelog.esm.js
CHANGED
|
@@ -3,22 +3,19 @@ const MAX_BATCH_BYTES = 262144;
|
|
|
3
3
|
const MAX_BATCH_EVENTS = 50;
|
|
4
4
|
const MAX_CONTEXT_BYTES = 8192;
|
|
5
5
|
const MAX_ERROR_MESSAGE_BYTES = 1024;
|
|
6
|
+
const MAX_ITEMS = 100;
|
|
7
|
+
const MAX_ITEMS_BYTES = 16384;
|
|
8
|
+
const MAX_ITEM_TEXT_LENGTH = 256;
|
|
6
9
|
const MAX_TAG_SIGHTINGS = 16;
|
|
7
10
|
const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
|
|
8
|
-
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})?$"};
|
|
11
|
+
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})?$" };
|
|
9
12
|
const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
|
|
10
|
-
const tagSightingKinds = ["ga4","meta","google_ads"];
|
|
13
|
+
const tagSightingKinds = ["ga4", "meta", "google_ads"];
|
|
11
14
|
const CONSENT_KEY = "__tl.c";
|
|
12
15
|
const SESSION_KEY = "__tl.s";
|
|
13
16
|
const ACTIVITY_KEY = "__tl.a";
|
|
14
17
|
const QUEUE_KEY = "__tl.q";
|
|
15
|
-
/** The namespace the runtime owns, in storage and in an event's context. */
|
|
16
18
|
const RUNTIME_KEY_PREFIX = "__tl.";
|
|
17
|
-
/**
|
|
18
|
-
* How many events wait in memory before consent. A platform artifact that
|
|
19
|
-
* buffers its own platform's events ahead of this engine holds the same line,
|
|
20
|
-
* so the number is exported rather than mirrored.
|
|
21
|
-
*/
|
|
22
19
|
const PRE_CONSENT_CAP = 100;
|
|
23
20
|
const QUEUE_CAP = 200;
|
|
24
21
|
const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
|
|
@@ -27,29 +24,13 @@ const RETRY_BASE_MS = 1000;
|
|
|
27
24
|
const RETRY_CAP_MS = 60 * 1000;
|
|
28
25
|
const CIRCUIT_FAILURE_THRESHOLD = 5;
|
|
29
26
|
const CIRCUIT_PROBE_MS = 60 * 1000;
|
|
30
|
-
/**
|
|
31
|
-
* What the browser lets `keepalive` bodies in flight add up to. Every send
|
|
32
|
-
* uses `keepalive`, so no navigation cancels one, and every send fits what is
|
|
33
|
-
* left of this beside the sends already in flight ([spec/capture.md]
|
|
34
|
-
* § Delivery). It is below the contract's `MAX_BATCH_BYTES`, so it is the
|
|
35
|
-
* batch budget too.
|
|
36
|
-
*/
|
|
37
27
|
const KEEPALIVE_BUDGET_BYTES = 64 * 1024;
|
|
38
28
|
const EVENT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
|
|
39
29
|
const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
|
|
40
|
-
/**
|
|
41
|
-
* The contract states these inside its schemas (`conversionEventSchema`,
|
|
42
|
-
* `currencySchema`) and exports no constant for them; the schemas themselves
|
|
43
|
-
* are not imported because zod is not part of the runtime a visitor loads.
|
|
44
|
-
*/
|
|
45
30
|
const MAX_IDENTIFIER_LENGTH = 256;
|
|
46
31
|
const CURRENCY_PATTERN = /^[A-Z]{3}$/;
|
|
32
|
+
const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
|
|
47
33
|
const textEncoder = new TextEncoder();
|
|
48
|
-
/**
|
|
49
|
-
* The tag sighting window around a conversion ([spec/capture.md] § Tag
|
|
50
|
-
* sightings). Ten seconds after is almost twice the longest hold measured:
|
|
51
|
-
* GA4 was measured holding a purchase 5.0 to 5.6 seconds.
|
|
52
|
-
*/
|
|
53
34
|
const TAG_SIGHTING_BEFORE_MS = 30000;
|
|
54
35
|
const TAG_SIGHTING_AFTER_MS = 10000;
|
|
55
36
|
function safeGet(storage, key) {
|
|
@@ -65,7 +46,6 @@ function safeSet(storage, key, value) {
|
|
|
65
46
|
storage.setItem(key, value);
|
|
66
47
|
}
|
|
67
48
|
catch {
|
|
68
|
-
// Capture must never break the host page when storage is unavailable.
|
|
69
49
|
}
|
|
70
50
|
}
|
|
71
51
|
function safeRemove(storage, key) {
|
|
@@ -73,7 +53,6 @@ function safeRemove(storage, key) {
|
|
|
73
53
|
storage.removeItem(key);
|
|
74
54
|
}
|
|
75
55
|
catch {
|
|
76
|
-
// Capture must never break the host page when storage is unavailable.
|
|
77
56
|
}
|
|
78
57
|
}
|
|
79
58
|
function emptyQueue() {
|
|
@@ -124,8 +103,8 @@ function uuidv7(at) {
|
|
|
124
103
|
bytes[index] = timestamp % 256;
|
|
125
104
|
timestamp = Math.floor(timestamp / 256);
|
|
126
105
|
}
|
|
127
|
-
bytes[6] =
|
|
128
|
-
bytes[8] =
|
|
106
|
+
bytes[6] = 112 | (bytes[6] & 15);
|
|
107
|
+
bytes[8] = 128 | (bytes[8] & 63);
|
|
129
108
|
const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
|
|
130
109
|
return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
|
|
131
110
|
}
|
|
@@ -169,21 +148,56 @@ function truncateUtf8(value, maxBytes) {
|
|
|
169
148
|
}
|
|
170
149
|
return value.slice(0, low);
|
|
171
150
|
}
|
|
151
|
+
function isAmount(value) {
|
|
152
|
+
return typeof value === "number" && Number.isFinite(value) && value >= 0;
|
|
153
|
+
}
|
|
172
154
|
function isConversionValid(options) {
|
|
173
155
|
return (options.identifier.length >= 1 &&
|
|
174
156
|
options.identifier.length <= MAX_IDENTIFIER_LENGTH &&
|
|
175
|
-
(options.value === undefined ||
|
|
176
|
-
(Number.isFinite(options.value) && options.value >= 0)) &&
|
|
157
|
+
(options.value === undefined || isAmount(options.value)) &&
|
|
177
158
|
(options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
|
|
178
159
|
}
|
|
160
|
+
function isItemText(value) {
|
|
161
|
+
return (typeof value === "string" &&
|
|
162
|
+
value.length >= 1 &&
|
|
163
|
+
value.length <= MAX_ITEM_TEXT_LENGTH);
|
|
164
|
+
}
|
|
165
|
+
function itemsOf(value) {
|
|
166
|
+
if (!Array.isArray(value) || value.length < 1 || value.length > MAX_ITEMS)
|
|
167
|
+
return undefined;
|
|
168
|
+
const items = [];
|
|
169
|
+
for (const item of value) {
|
|
170
|
+
if (typeof item !== "object" || item === null)
|
|
171
|
+
return undefined;
|
|
172
|
+
const { id, name, category, quantity, price } = item;
|
|
173
|
+
if (!isItemText(id) ||
|
|
174
|
+
!isItemText(name) ||
|
|
175
|
+
(category !== undefined && !isItemText(category)) ||
|
|
176
|
+
!Number.isSafeInteger(quantity) ||
|
|
177
|
+
quantity < 1 ||
|
|
178
|
+
(price !== undefined && !isAmount(price)))
|
|
179
|
+
return undefined;
|
|
180
|
+
items.push({
|
|
181
|
+
id,
|
|
182
|
+
name,
|
|
183
|
+
...(category === undefined ? {} : { category }),
|
|
184
|
+
quantity: quantity,
|
|
185
|
+
...(price === undefined ? {} : { price }),
|
|
186
|
+
});
|
|
187
|
+
}
|
|
188
|
+
return serializedBytes(items) <= MAX_ITEMS_BYTES ? items : undefined;
|
|
189
|
+
}
|
|
190
|
+
function scheduledForOf(value) {
|
|
191
|
+
if (typeof value !== "string" || !DAY_PATTERN.test(value))
|
|
192
|
+
return undefined;
|
|
193
|
+
const day = new Date(`${value}T00:00:00.000Z`);
|
|
194
|
+
return !Number.isNaN(day.getTime()) && day.toISOString().startsWith(value)
|
|
195
|
+
? value
|
|
196
|
+
: undefined;
|
|
197
|
+
}
|
|
179
198
|
function serializedBytes(value) {
|
|
180
199
|
return textEncoder.encode(JSON.stringify(value)).byteLength;
|
|
181
200
|
}
|
|
182
|
-
/**
|
|
183
|
-
* As many events as fit `room`, oldest first. An event that alone exceeds the
|
|
184
|
-
* whole keepalive budget can never be sent; one that only exceeds what the
|
|
185
|
-
* sends in flight leave waits for them.
|
|
186
|
-
*/
|
|
187
201
|
function batchFrom(events, room) {
|
|
188
202
|
const selected = [];
|
|
189
203
|
const unsendable = [];
|
|
@@ -212,21 +226,9 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
212
226
|
let config = { key: "", endpoint: "/v1/events" };
|
|
213
227
|
let pending = [];
|
|
214
228
|
let lastDeclaredName;
|
|
215
|
-
/**
|
|
216
|
-
* Every send in flight, by count, by bytes and by the union of their event
|
|
217
|
-
* ids: a step taken and a page hide send beside one rather than wait for
|
|
218
|
-
* it, so there can be several, each must leave the others' events alone,
|
|
219
|
-
* and together they stay within the keepalive budget.
|
|
220
|
-
*/
|
|
221
229
|
let sendsInFlight = 0;
|
|
222
230
|
let bytesInFlight = 0;
|
|
223
231
|
const inFlight = new Set();
|
|
224
|
-
/**
|
|
225
|
-
* The conversions this page emitted and holds for their tag sighting
|
|
226
|
-
* window: the instant each was emitted, and whether its report can be
|
|
227
|
-
* complete. In memory only — a held conversion is in the stored queue like
|
|
228
|
-
* any other, and a reload sends it as it is.
|
|
229
|
-
*/
|
|
230
232
|
const held = new Map();
|
|
231
233
|
let flushTimer;
|
|
232
234
|
let consecutiveFailures = 0;
|
|
@@ -275,11 +277,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
275
277
|
addDrop(queue, "invalid_event");
|
|
276
278
|
writeQueue(ports.storage, queue);
|
|
277
279
|
}
|
|
278
|
-
/**
|
|
279
|
-
* `buffered` is a conversion made before consent was granted and emitted
|
|
280
|
-
* at the grant: its window is placed there, after the conversion itself,
|
|
281
|
-
* so its report is never complete.
|
|
282
|
-
*/
|
|
283
280
|
function emit(pendingEvent, buffered = false) {
|
|
284
281
|
if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
|
|
285
282
|
recordInvalidEvent();
|
|
@@ -307,16 +304,20 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
307
304
|
}
|
|
308
305
|
if (pendingEvent.kind === "step") {
|
|
309
306
|
const context = jsonContext(pendingEvent.context);
|
|
307
|
+
const items = itemsOf(pendingEvent.options?.items);
|
|
310
308
|
persistEvent({
|
|
311
309
|
...baseEvent(now, session.id),
|
|
312
310
|
kind: "step",
|
|
313
311
|
name: pendingEvent.name,
|
|
314
312
|
...(context === undefined ? {} : { context }),
|
|
313
|
+
...(items === undefined ? {} : { items }),
|
|
315
314
|
});
|
|
316
315
|
}
|
|
317
316
|
else {
|
|
318
317
|
const options = pendingEvent.options;
|
|
319
318
|
const context = jsonContext(options.context);
|
|
319
|
+
const items = itemsOf(options.items);
|
|
320
|
+
const scheduledFor = scheduledForOf(options.scheduledFor);
|
|
320
321
|
const base = baseEvent(now, session.id);
|
|
321
322
|
if (acquisition.mode !== "verification" &&
|
|
322
323
|
ports.sightings?.observing() === true) {
|
|
@@ -332,6 +333,11 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
332
333
|
? {}
|
|
333
334
|
: { currency: options.currency }),
|
|
334
335
|
...(context === undefined ? {} : { context }),
|
|
336
|
+
...(items === undefined ? {} : { items }),
|
|
337
|
+
...(scheduledFor === undefined ? {} : { scheduledFor }),
|
|
338
|
+
...(typeof options.recurring === "boolean"
|
|
339
|
+
? { recurring: options.recurring }
|
|
340
|
+
: {}),
|
|
335
341
|
});
|
|
336
342
|
}
|
|
337
343
|
lastDeclaredName = pendingEvent.name;
|
|
@@ -347,21 +353,11 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
347
353
|
emit(pendingEvent);
|
|
348
354
|
sendTaken();
|
|
349
355
|
}
|
|
350
|
-
/**
|
|
351
|
-
* A step, and a conversion that is not held, leaves when it is taken: a
|
|
352
|
-
* click that navigates to another site may fire no hide event at all, and a
|
|
353
|
-
* send started by the click itself is the one that arrives ([spec/capture.md]
|
|
354
|
-
* § Delivery). An open circuit keeps it queued for the probe.
|
|
355
|
-
*/
|
|
356
356
|
function sendTaken() {
|
|
357
357
|
if (circuit !== "closed" || !PUBLIC_KEY_PATTERN.test(config.key))
|
|
358
358
|
return;
|
|
359
359
|
void sendNow();
|
|
360
360
|
}
|
|
361
|
-
/**
|
|
362
|
-
* Sends at once what is queued and in no send in flight, beside any send in
|
|
363
|
-
* flight, within what the keepalive budget has left.
|
|
364
|
-
*/
|
|
365
361
|
async function sendNow() {
|
|
366
362
|
const queue = readQueue(ports.storage);
|
|
367
363
|
const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
|
|
@@ -378,10 +374,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
378
374
|
addDrop(queue, "invalid_event", unsendable.length);
|
|
379
375
|
writeQueue(ports.storage, queue);
|
|
380
376
|
}
|
|
381
|
-
/**
|
|
382
|
-
* Gives each held conversion whose window has closed — or every one, at
|
|
383
|
-
* page hide — the report of what the port saw around it, and lets it go.
|
|
384
|
-
*/
|
|
385
377
|
function release(all) {
|
|
386
378
|
if (held.size === 0)
|
|
387
379
|
return;
|
|
@@ -393,7 +385,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
393
385
|
let reported = false;
|
|
394
386
|
for (const [eventId, hold] of due) {
|
|
395
387
|
held.delete(eventId);
|
|
396
|
-
// Gone from the queue — sent by another tab, or dropped by overflow.
|
|
397
388
|
const event = queue.events.find((candidate) => candidate.eventId === eventId);
|
|
398
389
|
const answer = event === undefined
|
|
399
390
|
? null
|
|
@@ -420,7 +411,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
420
411
|
if (reported)
|
|
421
412
|
writeQueue(ports.storage, queue);
|
|
422
413
|
}
|
|
423
|
-
/** Until the earliest held conversion's window closes. */
|
|
424
414
|
function untilRelease() {
|
|
425
415
|
const now = ports.clock.now().getTime();
|
|
426
416
|
let earliest = Number.POSITIVE_INFINITY;
|
|
@@ -433,11 +423,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
433
423
|
release(hidden);
|
|
434
424
|
if (!initialized || consentState !== "granted")
|
|
435
425
|
return;
|
|
436
|
-
/**
|
|
437
|
-
* A page being hidden gets no later chance, so it sends what no send in
|
|
438
|
-
* flight carries at once, whatever the circuit's state, and the answer is
|
|
439
|
-
* read as any other's.
|
|
440
|
-
*/
|
|
441
426
|
if (hidden) {
|
|
442
427
|
if (PUBLIC_KEY_PATTERN.test(config.key))
|
|
443
428
|
await sendNow();
|
|
@@ -471,11 +456,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
471
456
|
}
|
|
472
457
|
await deliver(batch);
|
|
473
458
|
}
|
|
474
|
-
/**
|
|
475
|
-
* One send, and its answer. It removes from the stored queue exactly what
|
|
476
|
-
* it carried, by its own read, filter and write at the moment it settles,
|
|
477
|
-
* so a send beside it keeps what it delivered.
|
|
478
|
-
*/
|
|
479
459
|
async function deliver(batch) {
|
|
480
460
|
const carried = new Set(batch.events.map((event) => event.eventId));
|
|
481
461
|
const bytes = serializedBytes(batch);
|
|
@@ -502,14 +482,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
502
482
|
scheduleFlush(currentQueue.events.length === 0 ? FLUSH_INTERVAL_MS : 0);
|
|
503
483
|
return;
|
|
504
484
|
}
|
|
505
|
-
/**
|
|
506
|
-
* A 4xx is the server's word that this batch will never be accepted —
|
|
507
|
-
* except a 429, which is the server's word that it will be accepted
|
|
508
|
-
* later: the ingestion limit is per public key, shared by every visitor
|
|
509
|
-
* of one site, so a busy minute answers 429 to visitors whose events
|
|
510
|
-
* are sound. Dropping those is silent loss ([spec/capture.md]
|
|
511
|
-
* § Delivery); they take the retry path with everything else transient.
|
|
512
|
-
*/
|
|
513
485
|
if (response.status >= 400 &&
|
|
514
486
|
response.status < 500 &&
|
|
515
487
|
response.status !== 429) {
|
|
@@ -550,12 +522,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
550
522
|
endpoint: options.endpoint ?? "/v1/events",
|
|
551
523
|
};
|
|
552
524
|
initialized = true;
|
|
553
|
-
/**
|
|
554
|
-
* Only a denial is remembered; a grant is the integrator's on every load
|
|
555
|
-
* while consent stands, so it never outlives the banner that gave it
|
|
556
|
-
* ([spec/capture.md] § Consent first). A grant an earlier runtime
|
|
557
|
-
* stored is deleted. A second init keeps the decision this page made.
|
|
558
|
-
*/
|
|
559
525
|
if (consentState !== "unknown")
|
|
560
526
|
return;
|
|
561
527
|
const storedConsent = safeGet(ports.storage, CONSENT_KEY);
|
|
@@ -599,11 +565,12 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
599
565
|
return consentState;
|
|
600
566
|
},
|
|
601
567
|
},
|
|
602
|
-
step(name, context) {
|
|
568
|
+
step(name, context, options) {
|
|
603
569
|
capture({
|
|
604
570
|
kind: "step",
|
|
605
571
|
name,
|
|
606
572
|
...(context === undefined ? {} : { context }),
|
|
573
|
+
...(options === undefined ? {} : { options }),
|
|
607
574
|
});
|
|
608
575
|
},
|
|
609
576
|
conversion(name, options) {
|
|
@@ -653,31 +620,12 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
653
620
|
},
|
|
654
621
|
};
|
|
655
622
|
}
|
|
656
|
-
/**
|
|
657
|
-
* The browser's clock, and the one file in this package allowed to read it
|
|
658
|
-
* ([CLAUDE.md] § Invariants: time is injected). `capture-core` declares the
|
|
659
|
-
* port and reads no clock at all — it runs inside sandboxes that have none —
|
|
660
|
-
* so the implementation lives here, with the runtime that has a `Date`.
|
|
661
|
-
*/
|
|
662
623
|
const systemClock = {
|
|
663
624
|
now: () => new Date(Date.now()),
|
|
664
625
|
};
|
|
665
|
-
/**
|
|
666
|
-
* A Resource Timing entry's start, on the system clock: its reading minus the
|
|
667
|
-
* entry's monotonic age. `performance.timeOrigin` would be a second clock, and
|
|
668
|
-
* it can disagree with this one by as much as the machine's clock drifted
|
|
669
|
-
* since the page loaded; the age is read on one clock and the instant on the
|
|
670
|
-
* other, so a sighting and the conversion it is compared with are dated alike
|
|
671
|
-
* ([spec/capture.md] § Tag sightings).
|
|
672
|
-
*/
|
|
673
626
|
function instantOfEntry(startTime) {
|
|
674
627
|
return new Date(systemClock.now().getTime() - (performance.now() - startTime));
|
|
675
628
|
}
|
|
676
|
-
/**
|
|
677
|
-
* How many matches the port keeps. A page making more tag requests than this
|
|
678
|
-
* inside one window is one whose report the port declines to give, never one
|
|
679
|
-
* it gives short.
|
|
680
|
-
*/
|
|
681
629
|
const TAG_SIGHTING_MEMORY = 100;
|
|
682
630
|
const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
|
|
683
631
|
const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
|
|
@@ -689,7 +637,6 @@ function onMetaEndpoint(url) {
|
|
|
689
637
|
return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
|
|
690
638
|
(url.pathname === "/tr" || url.pathname === "/tr/"));
|
|
691
639
|
}
|
|
692
|
-
/** A request on Meta's endpoint whose pixel id does not fit is Meta, unread. */
|
|
693
640
|
function metaMatch(id, event) {
|
|
694
641
|
return id !== null && metaIdPattern.test(id)
|
|
695
642
|
? {
|
|
@@ -701,15 +648,6 @@ function metaMatch(id, event) {
|
|
|
701
648
|
}
|
|
702
649
|
: { unread: "meta" };
|
|
703
650
|
}
|
|
704
|
-
/**
|
|
705
|
-
* The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
|
|
706
|
-
* key on the path and the id, so a regional host and a first-party tagging
|
|
707
|
-
* domain that keeps the path both match; Meta keys on its host as well. What
|
|
708
|
-
* is answered is the tag's kind, its id and Meta's event — nothing else of
|
|
709
|
-
* the URL, which carries the page address and the vendor's client id. Meta's
|
|
710
|
-
* beacon leaves an entry named by its bare endpoint, which names no pixel:
|
|
711
|
-
* that is Meta, unread.
|
|
712
|
-
*/
|
|
713
651
|
function matchTagRequest(url) {
|
|
714
652
|
let parsed;
|
|
715
653
|
try {
|
|
@@ -743,13 +681,6 @@ function matchTagRequest(url) {
|
|
|
743
681
|
}
|
|
744
682
|
return null;
|
|
745
683
|
}
|
|
746
|
-
/**
|
|
747
|
-
* Meta's long request in Chrome: a form posted into a hidden frame, which
|
|
748
|
-
* leaves no Resource Timing entry ([spec/capture.md] § Tag sightings, _Meta's
|
|
749
|
-
* long request_). Two fields are asked for, the ones that name the pixel and
|
|
750
|
-
* the event, and nothing else of the form is read: its other fields carry the
|
|
751
|
-
* visitor's identifiers, hashed.
|
|
752
|
-
*/
|
|
753
684
|
function matchTagForm(form) {
|
|
754
685
|
let action;
|
|
755
686
|
try {
|
|
@@ -760,30 +691,14 @@ function matchTagForm(form) {
|
|
|
760
691
|
}
|
|
761
692
|
if (!onMetaEndpoint(action))
|
|
762
693
|
return null;
|
|
763
|
-
const id = form.querySelector(
|
|
764
|
-
const event = form.querySelector(
|
|
694
|
+
const id = form.querySelector("input[name=\"id\"]");
|
|
695
|
+
const event = form.querySelector("input[name=\"ev\"]");
|
|
765
696
|
return metaMatch(id?.value ?? null, event?.value ?? null);
|
|
766
697
|
}
|
|
767
|
-
/**
|
|
768
|
-
* The browser's own record of the page's requests, read through a buffered
|
|
769
|
-
* `PerformanceObserver` once consent is granted and never before — and, for
|
|
770
|
-
* the one request that record leaves out, the forms the page's body gains,
|
|
771
|
-
* read through a `MutationObserver` on the body's own children. Nothing is
|
|
772
|
-
* wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
|
|
773
|
-
* because the runtime runs on somebody else's page and nothing it does may
|
|
774
|
-
* change what another script sees.
|
|
775
|
-
*/
|
|
776
698
|
function createTagSightingPort() {
|
|
777
699
|
let observer;
|
|
778
700
|
let bodyObserver;
|
|
779
|
-
/**
|
|
780
|
-
* From when the body's children were watched, on the system clock: minus
|
|
781
|
-
* infinity when observation began before the body existed, and so saw every
|
|
782
|
-
* form a script added to it; undefined while no body observer runs — never
|
|
783
|
-
* created, still waiting for the body, or failed.
|
|
784
|
-
*/
|
|
785
701
|
let watchedFrom;
|
|
786
|
-
/** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
|
|
787
702
|
let matches = [];
|
|
788
703
|
function remember(match, at) {
|
|
789
704
|
if (match === null)
|
|
@@ -800,10 +715,6 @@ function createTagSightingPort() {
|
|
|
800
715
|
remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
|
|
801
716
|
}
|
|
802
717
|
}
|
|
803
|
-
/**
|
|
804
|
-
* One observer, on the body's children and nothing below them. Before the
|
|
805
|
-
* body exists it watches the root's children for the body, and moves to it.
|
|
806
|
-
*/
|
|
807
718
|
function watchBody() {
|
|
808
719
|
try {
|
|
809
720
|
const document = window.document;
|
|
@@ -829,7 +740,6 @@ function createTagSightingPort() {
|
|
|
829
740
|
}
|
|
830
741
|
}
|
|
831
742
|
catch {
|
|
832
|
-
// Capture must never break the host page.
|
|
833
743
|
}
|
|
834
744
|
});
|
|
835
745
|
if (body === null) {
|
|
@@ -845,12 +755,9 @@ function createTagSightingPort() {
|
|
|
845
755
|
watchedFrom = undefined;
|
|
846
756
|
}
|
|
847
757
|
}
|
|
848
|
-
/** What was matched inside the window around `at`, or null. */
|
|
849
758
|
function within(at) {
|
|
850
759
|
if (observer === undefined)
|
|
851
760
|
return null;
|
|
852
|
-
// What the browser recorded and has not delivered yet: a page being
|
|
853
|
-
// hidden may not run the callback before the conversion leaves.
|
|
854
761
|
record(observer.takeRecords());
|
|
855
762
|
const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
|
|
856
763
|
const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
|
|
@@ -922,7 +829,6 @@ function createTagSightingPort() {
|
|
|
922
829
|
};
|
|
923
830
|
}
|
|
924
831
|
const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
|
|
925
|
-
/** The tab's verification nonce, in `sessionStorage`, written at the grant. */
|
|
926
832
|
const VERIFICATION_KEY = "__tl.v";
|
|
927
833
|
class MemoryStorage {
|
|
928
834
|
constructor() {
|
|
@@ -944,13 +850,7 @@ let engine;
|
|
|
944
850
|
let verification;
|
|
945
851
|
let configValid = false;
|
|
946
852
|
let listenersInstalled = false;
|
|
947
|
-
/**
|
|
948
|
-
* Calls made before `init`, made in order once it has run, up to the same 100
|
|
949
|
-
* the engine holds before consent; past that they are dropped
|
|
950
|
-
* ([spec/capture.md] § Consent first).
|
|
951
|
-
*/
|
|
952
853
|
let early = [];
|
|
953
|
-
/** True when there is no engine yet, and the call was held, or dropped. */
|
|
954
854
|
function heldForInit(call) {
|
|
955
855
|
if (engine !== undefined)
|
|
956
856
|
return false;
|
|
@@ -966,12 +866,6 @@ function browserStorage() {
|
|
|
966
866
|
return new MemoryStorage();
|
|
967
867
|
}
|
|
968
868
|
}
|
|
969
|
-
/**
|
|
970
|
-
* A page opened from a verification session carries the marker and has an
|
|
971
|
-
* opener. Once consent is granted there, the tab keeps the nonce, so the mark
|
|
972
|
-
* follows it to the site's next pages and back from a payment taken
|
|
973
|
-
* elsewhere, to the same origin ([spec/capture.md] § Verification mode).
|
|
974
|
-
*/
|
|
975
869
|
function verificationMode() {
|
|
976
870
|
const nonce = new URL(window.location.href).searchParams.get("__tl_verify");
|
|
977
871
|
if (nonce !== null && nonce.length > 0 && window.opener !== null) {
|
|
@@ -982,7 +876,6 @@ function verificationMode() {
|
|
|
982
876
|
kept = window.sessionStorage.getItem(VERIFICATION_KEY);
|
|
983
877
|
}
|
|
984
878
|
catch {
|
|
985
|
-
// An unreadable tab storage keeps no mark.
|
|
986
879
|
}
|
|
987
880
|
return kept === null || kept.length === 0
|
|
988
881
|
? undefined
|
|
@@ -997,7 +890,6 @@ function keepVerification(keep) {
|
|
|
997
890
|
}
|
|
998
891
|
}
|
|
999
892
|
catch {
|
|
1000
|
-
// A tab that cannot keep it marks this page only.
|
|
1001
893
|
}
|
|
1002
894
|
}
|
|
1003
895
|
function landingPage() {
|
|
@@ -1178,10 +1070,10 @@ const TraceLog = {
|
|
|
1178
1070
|
return engine?.consent.state() ?? "unknown";
|
|
1179
1071
|
},
|
|
1180
1072
|
},
|
|
1181
|
-
step(name, context) {
|
|
1182
|
-
if (heldForInit(() => TraceLog.step(name, context)))
|
|
1073
|
+
step(name, context, options) {
|
|
1074
|
+
if (heldForInit(() => TraceLog.step(name, context, options)))
|
|
1183
1075
|
return;
|
|
1184
|
-
engine?.step(name, context);
|
|
1076
|
+
engine?.step(name, context, options);
|
|
1185
1077
|
reportDiagnostic();
|
|
1186
1078
|
},
|
|
1187
1079
|
conversion(name, options) {
|
package/dist/tracelog.iife.js
CHANGED
|
@@ -4,22 +4,19 @@ const MAX_BATCH_BYTES = 262144;
|
|
|
4
4
|
const MAX_BATCH_EVENTS = 50;
|
|
5
5
|
const MAX_CONTEXT_BYTES = 8192;
|
|
6
6
|
const MAX_ERROR_MESSAGE_BYTES = 1024;
|
|
7
|
+
const MAX_ITEMS = 100;
|
|
8
|
+
const MAX_ITEMS_BYTES = 16384;
|
|
9
|
+
const MAX_ITEM_TEXT_LENGTH = 256;
|
|
7
10
|
const MAX_TAG_SIGHTINGS = 16;
|
|
8
11
|
const TAG_SIGHTINGS_CONTEXT_KEY = "__tl.tags";
|
|
9
|
-
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})?$"};
|
|
12
|
+
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})?$" };
|
|
10
13
|
const TAG_EVENT_PATTERN = "^[A-Za-z0-9_]{1,64}$";
|
|
11
|
-
const tagSightingKinds = ["ga4","meta","google_ads"];
|
|
14
|
+
const tagSightingKinds = ["ga4", "meta", "google_ads"];
|
|
12
15
|
const CONSENT_KEY = "__tl.c";
|
|
13
16
|
const SESSION_KEY = "__tl.s";
|
|
14
17
|
const ACTIVITY_KEY = "__tl.a";
|
|
15
18
|
const QUEUE_KEY = "__tl.q";
|
|
16
|
-
/** The namespace the runtime owns, in storage and in an event's context. */
|
|
17
19
|
const RUNTIME_KEY_PREFIX = "__tl.";
|
|
18
|
-
/**
|
|
19
|
-
* How many events wait in memory before consent. A platform artifact that
|
|
20
|
-
* buffers its own platform's events ahead of this engine holds the same line,
|
|
21
|
-
* so the number is exported rather than mirrored.
|
|
22
|
-
*/
|
|
23
20
|
const PRE_CONSENT_CAP = 100;
|
|
24
21
|
const QUEUE_CAP = 200;
|
|
25
22
|
const SESSION_INACTIVITY_MS = 30 * 60 * 1000;
|
|
@@ -28,29 +25,13 @@ const RETRY_BASE_MS = 1000;
|
|
|
28
25
|
const RETRY_CAP_MS = 60 * 1000;
|
|
29
26
|
const CIRCUIT_FAILURE_THRESHOLD = 5;
|
|
30
27
|
const CIRCUIT_PROBE_MS = 60 * 1000;
|
|
31
|
-
/**
|
|
32
|
-
* What the browser lets `keepalive` bodies in flight add up to. Every send
|
|
33
|
-
* uses `keepalive`, so no navigation cancels one, and every send fits what is
|
|
34
|
-
* left of this beside the sends already in flight ([spec/capture.md]
|
|
35
|
-
* § Delivery). It is below the contract's `MAX_BATCH_BYTES`, so it is the
|
|
36
|
-
* batch budget too.
|
|
37
|
-
*/
|
|
38
28
|
const KEEPALIVE_BUDGET_BYTES = 64 * 1024;
|
|
39
29
|
const EVENT_NAME_PATTERN = /^[a-z][a-z0-9_]{0,63}$/;
|
|
40
30
|
const PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
|
|
41
|
-
/**
|
|
42
|
-
* The contract states these inside its schemas (`conversionEventSchema`,
|
|
43
|
-
* `currencySchema`) and exports no constant for them; the schemas themselves
|
|
44
|
-
* are not imported because zod is not part of the runtime a visitor loads.
|
|
45
|
-
*/
|
|
46
31
|
const MAX_IDENTIFIER_LENGTH = 256;
|
|
47
32
|
const CURRENCY_PATTERN = /^[A-Z]{3}$/;
|
|
33
|
+
const DAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/;
|
|
48
34
|
const textEncoder = new TextEncoder();
|
|
49
|
-
/**
|
|
50
|
-
* The tag sighting window around a conversion ([spec/capture.md] § Tag
|
|
51
|
-
* sightings). Ten seconds after is almost twice the longest hold measured:
|
|
52
|
-
* GA4 was measured holding a purchase 5.0 to 5.6 seconds.
|
|
53
|
-
*/
|
|
54
35
|
const TAG_SIGHTING_BEFORE_MS = 30000;
|
|
55
36
|
const TAG_SIGHTING_AFTER_MS = 10000;
|
|
56
37
|
function safeGet(storage, key) {
|
|
@@ -66,7 +47,6 @@ function safeSet(storage, key, value) {
|
|
|
66
47
|
storage.setItem(key, value);
|
|
67
48
|
}
|
|
68
49
|
catch {
|
|
69
|
-
// Capture must never break the host page when storage is unavailable.
|
|
70
50
|
}
|
|
71
51
|
}
|
|
72
52
|
function safeRemove(storage, key) {
|
|
@@ -74,7 +54,6 @@ function safeRemove(storage, key) {
|
|
|
74
54
|
storage.removeItem(key);
|
|
75
55
|
}
|
|
76
56
|
catch {
|
|
77
|
-
// Capture must never break the host page when storage is unavailable.
|
|
78
57
|
}
|
|
79
58
|
}
|
|
80
59
|
function emptyQueue() {
|
|
@@ -125,8 +104,8 @@ function uuidv7(at) {
|
|
|
125
104
|
bytes[index] = timestamp % 256;
|
|
126
105
|
timestamp = Math.floor(timestamp / 256);
|
|
127
106
|
}
|
|
128
|
-
bytes[6] =
|
|
129
|
-
bytes[8] =
|
|
107
|
+
bytes[6] = 112 | (bytes[6] & 15);
|
|
108
|
+
bytes[8] = 128 | (bytes[8] & 63);
|
|
130
109
|
const hex = Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0"));
|
|
131
110
|
return `${hex.slice(0, 4).join("")}-${hex.slice(4, 6).join("")}-${hex.slice(6, 8).join("")}-${hex.slice(8, 10).join("")}-${hex.slice(10).join("")}`;
|
|
132
111
|
}
|
|
@@ -170,21 +149,56 @@ function truncateUtf8(value, maxBytes) {
|
|
|
170
149
|
}
|
|
171
150
|
return value.slice(0, low);
|
|
172
151
|
}
|
|
152
|
+
function isAmount(value) {
|
|
153
|
+
return typeof value === "number" && Number.isFinite(value) && value >= 0;
|
|
154
|
+
}
|
|
173
155
|
function isConversionValid(options) {
|
|
174
156
|
return (options.identifier.length >= 1 &&
|
|
175
157
|
options.identifier.length <= MAX_IDENTIFIER_LENGTH &&
|
|
176
|
-
(options.value === undefined ||
|
|
177
|
-
(Number.isFinite(options.value) && options.value >= 0)) &&
|
|
158
|
+
(options.value === undefined || isAmount(options.value)) &&
|
|
178
159
|
(options.currency === undefined || CURRENCY_PATTERN.test(options.currency)));
|
|
179
160
|
}
|
|
161
|
+
function isItemText(value) {
|
|
162
|
+
return (typeof value === "string" &&
|
|
163
|
+
value.length >= 1 &&
|
|
164
|
+
value.length <= MAX_ITEM_TEXT_LENGTH);
|
|
165
|
+
}
|
|
166
|
+
function itemsOf(value) {
|
|
167
|
+
if (!Array.isArray(value) || value.length < 1 || value.length > MAX_ITEMS)
|
|
168
|
+
return undefined;
|
|
169
|
+
const items = [];
|
|
170
|
+
for (const item of value) {
|
|
171
|
+
if (typeof item !== "object" || item === null)
|
|
172
|
+
return undefined;
|
|
173
|
+
const { id, name, category, quantity, price } = item;
|
|
174
|
+
if (!isItemText(id) ||
|
|
175
|
+
!isItemText(name) ||
|
|
176
|
+
(category !== undefined && !isItemText(category)) ||
|
|
177
|
+
!Number.isSafeInteger(quantity) ||
|
|
178
|
+
quantity < 1 ||
|
|
179
|
+
(price !== undefined && !isAmount(price)))
|
|
180
|
+
return undefined;
|
|
181
|
+
items.push({
|
|
182
|
+
id,
|
|
183
|
+
name,
|
|
184
|
+
...(category === undefined ? {} : { category }),
|
|
185
|
+
quantity: quantity,
|
|
186
|
+
...(price === undefined ? {} : { price }),
|
|
187
|
+
});
|
|
188
|
+
}
|
|
189
|
+
return serializedBytes(items) <= MAX_ITEMS_BYTES ? items : undefined;
|
|
190
|
+
}
|
|
191
|
+
function scheduledForOf(value) {
|
|
192
|
+
if (typeof value !== "string" || !DAY_PATTERN.test(value))
|
|
193
|
+
return undefined;
|
|
194
|
+
const day = new Date(`${value}T00:00:00.000Z`);
|
|
195
|
+
return !Number.isNaN(day.getTime()) && day.toISOString().startsWith(value)
|
|
196
|
+
? value
|
|
197
|
+
: undefined;
|
|
198
|
+
}
|
|
180
199
|
function serializedBytes(value) {
|
|
181
200
|
return textEncoder.encode(JSON.stringify(value)).byteLength;
|
|
182
201
|
}
|
|
183
|
-
/**
|
|
184
|
-
* As many events as fit `room`, oldest first. An event that alone exceeds the
|
|
185
|
-
* whole keepalive budget can never be sent; one that only exceeds what the
|
|
186
|
-
* sends in flight leave waits for them.
|
|
187
|
-
*/
|
|
188
202
|
function batchFrom(events, room) {
|
|
189
203
|
const selected = [];
|
|
190
204
|
const unsendable = [];
|
|
@@ -213,21 +227,9 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
213
227
|
let config = { key: "", endpoint: "/v1/events" };
|
|
214
228
|
let pending = [];
|
|
215
229
|
let lastDeclaredName;
|
|
216
|
-
/**
|
|
217
|
-
* Every send in flight, by count, by bytes and by the union of their event
|
|
218
|
-
* ids: a step taken and a page hide send beside one rather than wait for
|
|
219
|
-
* it, so there can be several, each must leave the others' events alone,
|
|
220
|
-
* and together they stay within the keepalive budget.
|
|
221
|
-
*/
|
|
222
230
|
let sendsInFlight = 0;
|
|
223
231
|
let bytesInFlight = 0;
|
|
224
232
|
const inFlight = new Set();
|
|
225
|
-
/**
|
|
226
|
-
* The conversions this page emitted and holds for their tag sighting
|
|
227
|
-
* window: the instant each was emitted, and whether its report can be
|
|
228
|
-
* complete. In memory only — a held conversion is in the stored queue like
|
|
229
|
-
* any other, and a reload sends it as it is.
|
|
230
|
-
*/
|
|
231
233
|
const held = new Map();
|
|
232
234
|
let flushTimer;
|
|
233
235
|
let consecutiveFailures = 0;
|
|
@@ -276,11 +278,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
276
278
|
addDrop(queue, "invalid_event");
|
|
277
279
|
writeQueue(ports.storage, queue);
|
|
278
280
|
}
|
|
279
|
-
/**
|
|
280
|
-
* `buffered` is a conversion made before consent was granted and emitted
|
|
281
|
-
* at the grant: its window is placed there, after the conversion itself,
|
|
282
|
-
* so its report is never complete.
|
|
283
|
-
*/
|
|
284
281
|
function emit(pendingEvent, buffered = false) {
|
|
285
282
|
if (!EVENT_NAME_PATTERN.test(pendingEvent.name)) {
|
|
286
283
|
recordInvalidEvent();
|
|
@@ -308,16 +305,20 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
308
305
|
}
|
|
309
306
|
if (pendingEvent.kind === "step") {
|
|
310
307
|
const context = jsonContext(pendingEvent.context);
|
|
308
|
+
const items = itemsOf(pendingEvent.options?.items);
|
|
311
309
|
persistEvent({
|
|
312
310
|
...baseEvent(now, session.id),
|
|
313
311
|
kind: "step",
|
|
314
312
|
name: pendingEvent.name,
|
|
315
313
|
...(context === undefined ? {} : { context }),
|
|
314
|
+
...(items === undefined ? {} : { items }),
|
|
316
315
|
});
|
|
317
316
|
}
|
|
318
317
|
else {
|
|
319
318
|
const options = pendingEvent.options;
|
|
320
319
|
const context = jsonContext(options.context);
|
|
320
|
+
const items = itemsOf(options.items);
|
|
321
|
+
const scheduledFor = scheduledForOf(options.scheduledFor);
|
|
321
322
|
const base = baseEvent(now, session.id);
|
|
322
323
|
if (acquisition.mode !== "verification" &&
|
|
323
324
|
ports.sightings?.observing() === true) {
|
|
@@ -333,6 +334,11 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
333
334
|
? {}
|
|
334
335
|
: { currency: options.currency }),
|
|
335
336
|
...(context === undefined ? {} : { context }),
|
|
337
|
+
...(items === undefined ? {} : { items }),
|
|
338
|
+
...(scheduledFor === undefined ? {} : { scheduledFor }),
|
|
339
|
+
...(typeof options.recurring === "boolean"
|
|
340
|
+
? { recurring: options.recurring }
|
|
341
|
+
: {}),
|
|
336
342
|
});
|
|
337
343
|
}
|
|
338
344
|
lastDeclaredName = pendingEvent.name;
|
|
@@ -348,21 +354,11 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
348
354
|
emit(pendingEvent);
|
|
349
355
|
sendTaken();
|
|
350
356
|
}
|
|
351
|
-
/**
|
|
352
|
-
* A step, and a conversion that is not held, leaves when it is taken: a
|
|
353
|
-
* click that navigates to another site may fire no hide event at all, and a
|
|
354
|
-
* send started by the click itself is the one that arrives ([spec/capture.md]
|
|
355
|
-
* § Delivery). An open circuit keeps it queued for the probe.
|
|
356
|
-
*/
|
|
357
357
|
function sendTaken() {
|
|
358
358
|
if (circuit !== "closed" || !PUBLIC_KEY_PATTERN.test(config.key))
|
|
359
359
|
return;
|
|
360
360
|
void sendNow();
|
|
361
361
|
}
|
|
362
|
-
/**
|
|
363
|
-
* Sends at once what is queued and in no send in flight, beside any send in
|
|
364
|
-
* flight, within what the keepalive budget has left.
|
|
365
|
-
*/
|
|
366
362
|
async function sendNow() {
|
|
367
363
|
const queue = readQueue(ports.storage);
|
|
368
364
|
const ready = queue.events.filter((event) => !held.has(event.eventId) && !inFlight.has(event.eventId));
|
|
@@ -379,10 +375,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
379
375
|
addDrop(queue, "invalid_event", unsendable.length);
|
|
380
376
|
writeQueue(ports.storage, queue);
|
|
381
377
|
}
|
|
382
|
-
/**
|
|
383
|
-
* Gives each held conversion whose window has closed — or every one, at
|
|
384
|
-
* page hide — the report of what the port saw around it, and lets it go.
|
|
385
|
-
*/
|
|
386
378
|
function release(all) {
|
|
387
379
|
if (held.size === 0)
|
|
388
380
|
return;
|
|
@@ -394,7 +386,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
394
386
|
let reported = false;
|
|
395
387
|
for (const [eventId, hold] of due) {
|
|
396
388
|
held.delete(eventId);
|
|
397
|
-
// Gone from the queue — sent by another tab, or dropped by overflow.
|
|
398
389
|
const event = queue.events.find((candidate) => candidate.eventId === eventId);
|
|
399
390
|
const answer = event === undefined
|
|
400
391
|
? null
|
|
@@ -421,7 +412,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
421
412
|
if (reported)
|
|
422
413
|
writeQueue(ports.storage, queue);
|
|
423
414
|
}
|
|
424
|
-
/** Until the earliest held conversion's window closes. */
|
|
425
415
|
function untilRelease() {
|
|
426
416
|
const now = ports.clock.now().getTime();
|
|
427
417
|
let earliest = Number.POSITIVE_INFINITY;
|
|
@@ -434,11 +424,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
434
424
|
release(hidden);
|
|
435
425
|
if (!initialized || consentState !== "granted")
|
|
436
426
|
return;
|
|
437
|
-
/**
|
|
438
|
-
* A page being hidden gets no later chance, so it sends what no send in
|
|
439
|
-
* flight carries at once, whatever the circuit's state, and the answer is
|
|
440
|
-
* read as any other's.
|
|
441
|
-
*/
|
|
442
427
|
if (hidden) {
|
|
443
428
|
if (PUBLIC_KEY_PATTERN.test(config.key))
|
|
444
429
|
await sendNow();
|
|
@@ -472,11 +457,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
472
457
|
}
|
|
473
458
|
await deliver(batch);
|
|
474
459
|
}
|
|
475
|
-
/**
|
|
476
|
-
* One send, and its answer. It removes from the stored queue exactly what
|
|
477
|
-
* it carried, by its own read, filter and write at the moment it settles,
|
|
478
|
-
* so a send beside it keeps what it delivered.
|
|
479
|
-
*/
|
|
480
460
|
async function deliver(batch) {
|
|
481
461
|
const carried = new Set(batch.events.map((event) => event.eventId));
|
|
482
462
|
const bytes = serializedBytes(batch);
|
|
@@ -503,14 +483,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
503
483
|
scheduleFlush(currentQueue.events.length === 0 ? FLUSH_INTERVAL_MS : 0);
|
|
504
484
|
return;
|
|
505
485
|
}
|
|
506
|
-
/**
|
|
507
|
-
* A 4xx is the server's word that this batch will never be accepted —
|
|
508
|
-
* except a 429, which is the server's word that it will be accepted
|
|
509
|
-
* later: the ingestion limit is per public key, shared by every visitor
|
|
510
|
-
* of one site, so a busy minute answers 429 to visitors whose events
|
|
511
|
-
* are sound. Dropping those is silent loss ([spec/capture.md]
|
|
512
|
-
* § Delivery); they take the retry path with everything else transient.
|
|
513
|
-
*/
|
|
514
486
|
if (response.status >= 400 &&
|
|
515
487
|
response.status < 500 &&
|
|
516
488
|
response.status !== 429) {
|
|
@@ -551,12 +523,6 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
551
523
|
endpoint: options.endpoint ?? "/v1/events",
|
|
552
524
|
};
|
|
553
525
|
initialized = true;
|
|
554
|
-
/**
|
|
555
|
-
* Only a denial is remembered; a grant is the integrator's on every load
|
|
556
|
-
* while consent stands, so it never outlives the banner that gave it
|
|
557
|
-
* ([spec/capture.md] § Consent first). A grant an earlier runtime
|
|
558
|
-
* stored is deleted. A second init keeps the decision this page made.
|
|
559
|
-
*/
|
|
560
526
|
if (consentState !== "unknown")
|
|
561
527
|
return;
|
|
562
528
|
const storedConsent = safeGet(ports.storage, CONSENT_KEY);
|
|
@@ -600,11 +566,12 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
600
566
|
return consentState;
|
|
601
567
|
},
|
|
602
568
|
},
|
|
603
|
-
step(name, context) {
|
|
569
|
+
step(name, context, options) {
|
|
604
570
|
capture({
|
|
605
571
|
kind: "step",
|
|
606
572
|
name,
|
|
607
573
|
...(context === undefined ? {} : { context }),
|
|
574
|
+
...(options === undefined ? {} : { options }),
|
|
608
575
|
});
|
|
609
576
|
},
|
|
610
577
|
conversion(name, options) {
|
|
@@ -654,31 +621,12 @@ function createCaptureEngine(ports, acquisition) {
|
|
|
654
621
|
},
|
|
655
622
|
};
|
|
656
623
|
}
|
|
657
|
-
/**
|
|
658
|
-
* The browser's clock, and the one file in this package allowed to read it
|
|
659
|
-
* ([CLAUDE.md] § Invariants: time is injected). `capture-core` declares the
|
|
660
|
-
* port and reads no clock at all — it runs inside sandboxes that have none —
|
|
661
|
-
* so the implementation lives here, with the runtime that has a `Date`.
|
|
662
|
-
*/
|
|
663
624
|
const systemClock = {
|
|
664
625
|
now: () => new Date(Date.now()),
|
|
665
626
|
};
|
|
666
|
-
/**
|
|
667
|
-
* A Resource Timing entry's start, on the system clock: its reading minus the
|
|
668
|
-
* entry's monotonic age. `performance.timeOrigin` would be a second clock, and
|
|
669
|
-
* it can disagree with this one by as much as the machine's clock drifted
|
|
670
|
-
* since the page loaded; the age is read on one clock and the instant on the
|
|
671
|
-
* other, so a sighting and the conversion it is compared with are dated alike
|
|
672
|
-
* ([spec/capture.md] § Tag sightings).
|
|
673
|
-
*/
|
|
674
627
|
function instantOfEntry(startTime) {
|
|
675
628
|
return new Date(systemClock.now().getTime() - (performance.now() - startTime));
|
|
676
629
|
}
|
|
677
|
-
/**
|
|
678
|
-
* How many matches the port keeps. A page making more tag requests than this
|
|
679
|
-
* inside one window is one whose report the port declines to give, never one
|
|
680
|
-
* it gives short.
|
|
681
|
-
*/
|
|
682
630
|
const TAG_SIGHTING_MEMORY = 100;
|
|
683
631
|
const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
|
|
684
632
|
const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
|
|
@@ -690,7 +638,6 @@ function onMetaEndpoint(url) {
|
|
|
690
638
|
return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
|
|
691
639
|
(url.pathname === "/tr" || url.pathname === "/tr/"));
|
|
692
640
|
}
|
|
693
|
-
/** A request on Meta's endpoint whose pixel id does not fit is Meta, unread. */
|
|
694
641
|
function metaMatch(id, event) {
|
|
695
642
|
return id !== null && metaIdPattern.test(id)
|
|
696
643
|
? {
|
|
@@ -702,15 +649,6 @@ function metaMatch(id, event) {
|
|
|
702
649
|
}
|
|
703
650
|
: { unread: "meta" };
|
|
704
651
|
}
|
|
705
|
-
/**
|
|
706
|
-
* The matching table ([spec/capture.md] § Tag sightings): GA4 and Google Ads
|
|
707
|
-
* key on the path and the id, so a regional host and a first-party tagging
|
|
708
|
-
* domain that keeps the path both match; Meta keys on its host as well. What
|
|
709
|
-
* is answered is the tag's kind, its id and Meta's event — nothing else of
|
|
710
|
-
* the URL, which carries the page address and the vendor's client id. Meta's
|
|
711
|
-
* beacon leaves an entry named by its bare endpoint, which names no pixel:
|
|
712
|
-
* that is Meta, unread.
|
|
713
|
-
*/
|
|
714
652
|
function matchTagRequest(url) {
|
|
715
653
|
let parsed;
|
|
716
654
|
try {
|
|
@@ -744,13 +682,6 @@ function matchTagRequest(url) {
|
|
|
744
682
|
}
|
|
745
683
|
return null;
|
|
746
684
|
}
|
|
747
|
-
/**
|
|
748
|
-
* Meta's long request in Chrome: a form posted into a hidden frame, which
|
|
749
|
-
* leaves no Resource Timing entry ([spec/capture.md] § Tag sightings, _Meta's
|
|
750
|
-
* long request_). Two fields are asked for, the ones that name the pixel and
|
|
751
|
-
* the event, and nothing else of the form is read: its other fields carry the
|
|
752
|
-
* visitor's identifiers, hashed.
|
|
753
|
-
*/
|
|
754
685
|
function matchTagForm(form) {
|
|
755
686
|
let action;
|
|
756
687
|
try {
|
|
@@ -761,30 +692,14 @@ function matchTagForm(form) {
|
|
|
761
692
|
}
|
|
762
693
|
if (!onMetaEndpoint(action))
|
|
763
694
|
return null;
|
|
764
|
-
const id = form.querySelector(
|
|
765
|
-
const event = form.querySelector(
|
|
695
|
+
const id = form.querySelector("input[name=\"id\"]");
|
|
696
|
+
const event = form.querySelector("input[name=\"ev\"]");
|
|
766
697
|
return metaMatch(id?.value ?? null, event?.value ?? null);
|
|
767
698
|
}
|
|
768
|
-
/**
|
|
769
|
-
* The browser's own record of the page's requests, read through a buffered
|
|
770
|
-
* `PerformanceObserver` once consent is granted and never before — and, for
|
|
771
|
-
* the one request that record leaves out, the forms the page's body gains,
|
|
772
|
-
* read through a `MutationObserver` on the body's own children. Nothing is
|
|
773
|
-
* wrapped, patched or replaced — no `fetch`, no beacon, no vendor's global —
|
|
774
|
-
* because the runtime runs on somebody else's page and nothing it does may
|
|
775
|
-
* change what another script sees.
|
|
776
|
-
*/
|
|
777
699
|
function createTagSightingPort() {
|
|
778
700
|
let observer;
|
|
779
701
|
let bodyObserver;
|
|
780
|
-
/**
|
|
781
|
-
* From when the body's children were watched, on the system clock: minus
|
|
782
|
-
* infinity when observation began before the body existed, and so saw every
|
|
783
|
-
* form a script added to it; undefined while no body observer runs — never
|
|
784
|
-
* created, still waiting for the body, or failed.
|
|
785
|
-
*/
|
|
786
702
|
let watchedFrom;
|
|
787
|
-
/** Ordered by `at`, oldest first; at most `TAG_SIGHTING_MEMORY`. */
|
|
788
703
|
let matches = [];
|
|
789
704
|
function remember(match, at) {
|
|
790
705
|
if (match === null)
|
|
@@ -801,10 +716,6 @@ function createTagSightingPort() {
|
|
|
801
716
|
remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
|
|
802
717
|
}
|
|
803
718
|
}
|
|
804
|
-
/**
|
|
805
|
-
* One observer, on the body's children and nothing below them. Before the
|
|
806
|
-
* body exists it watches the root's children for the body, and moves to it.
|
|
807
|
-
*/
|
|
808
719
|
function watchBody() {
|
|
809
720
|
try {
|
|
810
721
|
const document = window.document;
|
|
@@ -830,7 +741,6 @@ function createTagSightingPort() {
|
|
|
830
741
|
}
|
|
831
742
|
}
|
|
832
743
|
catch {
|
|
833
|
-
// Capture must never break the host page.
|
|
834
744
|
}
|
|
835
745
|
});
|
|
836
746
|
if (body === null) {
|
|
@@ -846,12 +756,9 @@ function createTagSightingPort() {
|
|
|
846
756
|
watchedFrom = undefined;
|
|
847
757
|
}
|
|
848
758
|
}
|
|
849
|
-
/** What was matched inside the window around `at`, or null. */
|
|
850
759
|
function within(at) {
|
|
851
760
|
if (observer === undefined)
|
|
852
761
|
return null;
|
|
853
|
-
// What the browser recorded and has not delivered yet: a page being
|
|
854
|
-
// hidden may not run the callback before the conversion leaves.
|
|
855
762
|
record(observer.takeRecords());
|
|
856
763
|
const from = at.getTime() - TAG_SIGHTING_BEFORE_MS;
|
|
857
764
|
const to = at.getTime() + TAG_SIGHTING_AFTER_MS;
|
|
@@ -923,7 +830,6 @@ function createTagSightingPort() {
|
|
|
923
830
|
};
|
|
924
831
|
}
|
|
925
832
|
const WEB_PUBLIC_KEY_PATTERN = /^tl_pk_[a-z2-7]{26}$/;
|
|
926
|
-
/** The tab's verification nonce, in `sessionStorage`, written at the grant. */
|
|
927
833
|
const VERIFICATION_KEY = "__tl.v";
|
|
928
834
|
class MemoryStorage {
|
|
929
835
|
constructor() {
|
|
@@ -945,13 +851,7 @@ let engine;
|
|
|
945
851
|
let verification;
|
|
946
852
|
let configValid = false;
|
|
947
853
|
let listenersInstalled = false;
|
|
948
|
-
/**
|
|
949
|
-
* Calls made before `init`, made in order once it has run, up to the same 100
|
|
950
|
-
* the engine holds before consent; past that they are dropped
|
|
951
|
-
* ([spec/capture.md] § Consent first).
|
|
952
|
-
*/
|
|
953
854
|
let early = [];
|
|
954
|
-
/** True when there is no engine yet, and the call was held, or dropped. */
|
|
955
855
|
function heldForInit(call) {
|
|
956
856
|
if (engine !== undefined)
|
|
957
857
|
return false;
|
|
@@ -967,12 +867,6 @@ function browserStorage() {
|
|
|
967
867
|
return new MemoryStorage();
|
|
968
868
|
}
|
|
969
869
|
}
|
|
970
|
-
/**
|
|
971
|
-
* A page opened from a verification session carries the marker and has an
|
|
972
|
-
* opener. Once consent is granted there, the tab keeps the nonce, so the mark
|
|
973
|
-
* follows it to the site's next pages and back from a payment taken
|
|
974
|
-
* elsewhere, to the same origin ([spec/capture.md] § Verification mode).
|
|
975
|
-
*/
|
|
976
870
|
function verificationMode() {
|
|
977
871
|
const nonce = new URL(window.location.href).searchParams.get("__tl_verify");
|
|
978
872
|
if (nonce !== null && nonce.length > 0 && window.opener !== null) {
|
|
@@ -983,7 +877,6 @@ function verificationMode() {
|
|
|
983
877
|
kept = window.sessionStorage.getItem(VERIFICATION_KEY);
|
|
984
878
|
}
|
|
985
879
|
catch {
|
|
986
|
-
// An unreadable tab storage keeps no mark.
|
|
987
880
|
}
|
|
988
881
|
return kept === null || kept.length === 0
|
|
989
882
|
? undefined
|
|
@@ -998,7 +891,6 @@ function keepVerification(keep) {
|
|
|
998
891
|
}
|
|
999
892
|
}
|
|
1000
893
|
catch {
|
|
1001
|
-
// A tab that cannot keep it marks this page only.
|
|
1002
894
|
}
|
|
1003
895
|
}
|
|
1004
896
|
function landingPage() {
|
|
@@ -1179,10 +1071,10 @@ const TraceLog = {
|
|
|
1179
1071
|
return engine?.consent.state() ?? "unknown";
|
|
1180
1072
|
},
|
|
1181
1073
|
},
|
|
1182
|
-
step(name, context) {
|
|
1183
|
-
if (heldForInit(() => TraceLog.step(name, context)))
|
|
1074
|
+
step(name, context, options) {
|
|
1075
|
+
if (heldForInit(() => TraceLog.step(name, context, options)))
|
|
1184
1076
|
return;
|
|
1185
|
-
engine?.step(name, context);
|
|
1077
|
+
engine?.step(name, context, options);
|
|
1186
1078
|
reportDiagnostic();
|
|
1187
1079
|
},
|
|
1188
1080
|
conversion(name, options) {
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@tracelog/capture-web",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.1.0",
|
|
4
4
|
"description": "The TraceLog browser capture runtime: consent-first, pinned per version.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"conversion",
|
|
@@ -45,8 +45,9 @@
|
|
|
45
45
|
"access": "public"
|
|
46
46
|
},
|
|
47
47
|
"devDependencies": {
|
|
48
|
-
"
|
|
49
|
-
"@tracelog/
|
|
48
|
+
"typescript": "5.9.3",
|
|
49
|
+
"@tracelog/capture-core": "2.1.0",
|
|
50
|
+
"@tracelog/event-contract": "2.1.0"
|
|
50
51
|
},
|
|
51
52
|
"scripts": {
|
|
52
53
|
"build": "tsc -p tsconfig.build.json && node build.mjs",
|