@tracelog/capture-web 2.1.0 → 2.3.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 CHANGED
@@ -18,6 +18,18 @@ 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.3.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.2.0...capture-web@2.3.0) (2026-10-17)
22
+
23
+
24
+ ### Added
25
+
26
+ * **capture-web:** the page it loads on opens the session ([259cad7](https://github.com/nacorga/tracelog-sdk/commit/259cad70dc2f4bc14c0b1827b80c870fe443bd93))
27
+
28
+ ## [2.2.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.1.0...capture-web@2.2.0) (2026-10-16)
29
+
30
+
31
+ * **capture-web:** Synchronize tracelog-sdk versions
32
+
21
33
  ## [2.1.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.0.1...capture-web@2.1.0) (2026-10-06)
22
34
 
23
35
 
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.1.0
25
+ npm install --save-exact @tracelog/capture-web@2.3.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.1.0/tracelog.js"></script>
31
+ <script src="https://cdn.tracelog.io/v/2.3.0/tracelog.js"></script>
32
32
  ```
33
33
 
34
34
  <!-- x-release-please-end -->
@@ -97,9 +97,12 @@ type a name TraceLog already knows.
97
97
 
98
98
  ## What it captures
99
99
 
100
- The events your tracking plan declares, with their context. Not page views, not
101
- clicks, not scroll, not keystrokes. Errors are captured only when they occur
102
- inside the conversion path, attached to the step where they happened.
100
+ The events your tracking plan declares, with their context, and once consent is
101
+ granted, one session record a visit, made on its first page: where the visit
102
+ came from and the page it landed on. No later page is recorded — not page
103
+ views, not clicks, not scroll, not keystrokes. Errors are captured only when
104
+ they occur inside the conversion path, attached to the step where they
105
+ happened.
103
106
 
104
107
  A conversion may carry its items, the day a booking is for and whether it
105
108
  recurs, and a step the items it shows; a malformed one is left out and the
@@ -121,10 +124,10 @@ An IP address is read once when the event arrives to derive a two-letter country
121
124
  code, then discarded.
122
125
 
123
126
  Events queue locally once consent allows, batch, and deliver with retry, backoff
124
- and circuit breaking. A step is sent when it is taken, and every send uses
125
- `keepalive`, so a click that leaves the page — even for another site — does not
126
- cancel it. Delivery failure surfaces as a diagnosable condition, never as
127
- silent loss.
127
+ and circuit breaking. A session start and a step are sent when they are taken,
128
+ and every send uses `keepalive`, so a click that leaves the page — even for
129
+ another site — does not cancel it. Delivery failure surfaces as a diagnosable
130
+ condition, never as silent loss.
128
131
 
129
132
  ## Where it runs
130
133
 
@@ -234,6 +234,8 @@ function createCaptureEngine(ports, acquisition) {
234
234
  let consecutiveFailures = 0;
235
235
  let circuit = "closed";
236
236
  let nextProbeAt = 0;
237
+ let pageOpen = false;
238
+ let opened = false;
237
239
  function scheduleFlush(delay) {
238
240
  if (flushTimer !== undefined)
239
241
  clearTimeout(flushTimer);
@@ -272,6 +274,28 @@ function createCaptureEngine(ports, acquisition) {
272
274
  ...(acquisition.mode === undefined ? {} : { mode: acquisition.mode }),
273
275
  };
274
276
  }
277
+ function sessionStart(now, sessionId) {
278
+ return {
279
+ ...baseEvent(now, sessionId),
280
+ kind: "session_start",
281
+ name: "session_started",
282
+ ...(acquisition.referrer === undefined
283
+ ? {}
284
+ : { referrer: acquisition.referrer }),
285
+ utm: acquisition.utm,
286
+ landingPage: acquisition.landingPage,
287
+ device: acquisition.device,
288
+ };
289
+ }
290
+ function openNow() {
291
+ opened = true;
292
+ const now = ports.clock.now();
293
+ const session = sessionFor(now);
294
+ if (session.started) {
295
+ persistEvent({ ...sessionStart(now, session.id), opening: "page" });
296
+ sendTaken();
297
+ }
298
+ }
275
299
  function recordInvalidEvent() {
276
300
  const queue = readQueue(ports.storage);
277
301
  addDrop(queue, "invalid_event");
@@ -289,19 +313,8 @@ function createCaptureEngine(ports, acquisition) {
289
313
  }
290
314
  const now = ports.clock.now();
291
315
  const session = sessionFor(now);
292
- if (session.started) {
293
- persistEvent({
294
- ...baseEvent(now, session.id),
295
- kind: "session_start",
296
- name: "session_started",
297
- ...(acquisition.referrer === undefined
298
- ? {}
299
- : { referrer: acquisition.referrer }),
300
- utm: acquisition.utm,
301
- landingPage: acquisition.landingPage,
302
- device: acquisition.device,
303
- });
304
- }
316
+ if (session.started)
317
+ persistEvent(sessionStart(now, session.id));
305
318
  if (pendingEvent.kind === "step") {
306
319
  const context = jsonContext(pendingEvent.context);
307
320
  const items = itemsOf(pendingEvent.options?.items);
@@ -537,6 +550,8 @@ function createCaptureEngine(ports, acquisition) {
537
550
  consentState = "granted";
538
551
  safeRemove(ports.storage, CONSENT_KEY);
539
552
  ports.sightings?.start();
553
+ if (pageOpen && !opened)
554
+ openNow();
540
555
  const buffered = pending;
541
556
  pending = [];
542
557
  for (const pendingEvent of buffered)
@@ -549,6 +564,7 @@ function createCaptureEngine(ports, acquisition) {
549
564
  if (!initialized)
550
565
  return;
551
566
  consentState = "denied";
567
+ opened = false;
552
568
  pending = [];
553
569
  lastDeclaredName = undefined;
554
570
  ports.sightings?.stop();
@@ -588,19 +604,8 @@ function createCaptureEngine(ports, acquisition) {
588
604
  }
589
605
  const now = ports.clock.now();
590
606
  const session = sessionFor(now);
591
- if (session.started) {
592
- persistEvent({
593
- ...baseEvent(now, session.id),
594
- kind: "session_start",
595
- name: "session_started",
596
- ...(acquisition.referrer === undefined
597
- ? {}
598
- : { referrer: acquisition.referrer }),
599
- utm: acquisition.utm,
600
- landingPage: acquisition.landingPage,
601
- device: acquisition.device,
602
- });
603
- }
607
+ if (session.started)
608
+ persistEvent(sessionStart(now, session.id));
604
609
  persistEvent({
605
610
  ...baseEvent(now, session.id),
606
611
  kind: "error",
@@ -609,6 +614,18 @@ function createCaptureEngine(ports, acquisition) {
609
614
  stepName: lastDeclaredName,
610
615
  });
611
616
  },
617
+ open() {
618
+ if (!initialized)
619
+ return;
620
+ pageOpen = true;
621
+ if (consentState === "granted" && !opened)
622
+ openNow();
623
+ },
624
+ pageRestored() {
625
+ opened = false;
626
+ if (pageOpen && consentState === "granted")
627
+ openNow();
628
+ },
612
629
  drops() {
613
630
  const queue = readQueue(ports.storage);
614
631
  return ["queue_overflow", "server_rejected", "invalid_event"]
@@ -850,6 +867,7 @@ let engine;
850
867
  let verification;
851
868
  let configValid = false;
852
869
  let listenersInstalled = false;
870
+ let pageOpened = false;
853
871
  let early = [];
854
872
  function heldForInit(call) {
855
873
  if (engine !== undefined)
@@ -1000,6 +1018,22 @@ function installListeners() {
1000
1018
  void runtime?.flush(true).finally(reportDiagnostic);
1001
1019
  }
1002
1020
  });
1021
+ window.addEventListener("pageshow", (event) => {
1022
+ if (event.persisted)
1023
+ runtime?.pageRestored();
1024
+ });
1025
+ }
1026
+ function openPage() {
1027
+ if (pageOpened || window.top !== window)
1028
+ return;
1029
+ if (window.document.prerendering === true) {
1030
+ window.document.addEventListener("prerenderingchange", openPage, {
1031
+ once: true,
1032
+ });
1033
+ return;
1034
+ }
1035
+ pageOpened = true;
1036
+ runtime?.open();
1003
1037
  }
1004
1038
  function init(options) {
1005
1039
  verification = verificationMode();
@@ -1042,6 +1076,7 @@ function init(options) {
1042
1076
  ...(options.endpoint === undefined ? {} : { endpoint }),
1043
1077
  });
1044
1078
  installListeners();
1079
+ openPage();
1045
1080
  const held = early;
1046
1081
  early = [];
1047
1082
  for (const call of held)
@@ -235,6 +235,8 @@ function createCaptureEngine(ports, acquisition) {
235
235
  let consecutiveFailures = 0;
236
236
  let circuit = "closed";
237
237
  let nextProbeAt = 0;
238
+ let pageOpen = false;
239
+ let opened = false;
238
240
  function scheduleFlush(delay) {
239
241
  if (flushTimer !== undefined)
240
242
  clearTimeout(flushTimer);
@@ -273,6 +275,28 @@ function createCaptureEngine(ports, acquisition) {
273
275
  ...(acquisition.mode === undefined ? {} : { mode: acquisition.mode }),
274
276
  };
275
277
  }
278
+ function sessionStart(now, sessionId) {
279
+ return {
280
+ ...baseEvent(now, sessionId),
281
+ kind: "session_start",
282
+ name: "session_started",
283
+ ...(acquisition.referrer === undefined
284
+ ? {}
285
+ : { referrer: acquisition.referrer }),
286
+ utm: acquisition.utm,
287
+ landingPage: acquisition.landingPage,
288
+ device: acquisition.device,
289
+ };
290
+ }
291
+ function openNow() {
292
+ opened = true;
293
+ const now = ports.clock.now();
294
+ const session = sessionFor(now);
295
+ if (session.started) {
296
+ persistEvent({ ...sessionStart(now, session.id), opening: "page" });
297
+ sendTaken();
298
+ }
299
+ }
276
300
  function recordInvalidEvent() {
277
301
  const queue = readQueue(ports.storage);
278
302
  addDrop(queue, "invalid_event");
@@ -290,19 +314,8 @@ function createCaptureEngine(ports, acquisition) {
290
314
  }
291
315
  const now = ports.clock.now();
292
316
  const session = sessionFor(now);
293
- if (session.started) {
294
- persistEvent({
295
- ...baseEvent(now, session.id),
296
- kind: "session_start",
297
- name: "session_started",
298
- ...(acquisition.referrer === undefined
299
- ? {}
300
- : { referrer: acquisition.referrer }),
301
- utm: acquisition.utm,
302
- landingPage: acquisition.landingPage,
303
- device: acquisition.device,
304
- });
305
- }
317
+ if (session.started)
318
+ persistEvent(sessionStart(now, session.id));
306
319
  if (pendingEvent.kind === "step") {
307
320
  const context = jsonContext(pendingEvent.context);
308
321
  const items = itemsOf(pendingEvent.options?.items);
@@ -538,6 +551,8 @@ function createCaptureEngine(ports, acquisition) {
538
551
  consentState = "granted";
539
552
  safeRemove(ports.storage, CONSENT_KEY);
540
553
  ports.sightings?.start();
554
+ if (pageOpen && !opened)
555
+ openNow();
541
556
  const buffered = pending;
542
557
  pending = [];
543
558
  for (const pendingEvent of buffered)
@@ -550,6 +565,7 @@ function createCaptureEngine(ports, acquisition) {
550
565
  if (!initialized)
551
566
  return;
552
567
  consentState = "denied";
568
+ opened = false;
553
569
  pending = [];
554
570
  lastDeclaredName = undefined;
555
571
  ports.sightings?.stop();
@@ -589,19 +605,8 @@ function createCaptureEngine(ports, acquisition) {
589
605
  }
590
606
  const now = ports.clock.now();
591
607
  const session = sessionFor(now);
592
- if (session.started) {
593
- persistEvent({
594
- ...baseEvent(now, session.id),
595
- kind: "session_start",
596
- name: "session_started",
597
- ...(acquisition.referrer === undefined
598
- ? {}
599
- : { referrer: acquisition.referrer }),
600
- utm: acquisition.utm,
601
- landingPage: acquisition.landingPage,
602
- device: acquisition.device,
603
- });
604
- }
608
+ if (session.started)
609
+ persistEvent(sessionStart(now, session.id));
605
610
  persistEvent({
606
611
  ...baseEvent(now, session.id),
607
612
  kind: "error",
@@ -610,6 +615,18 @@ function createCaptureEngine(ports, acquisition) {
610
615
  stepName: lastDeclaredName,
611
616
  });
612
617
  },
618
+ open() {
619
+ if (!initialized)
620
+ return;
621
+ pageOpen = true;
622
+ if (consentState === "granted" && !opened)
623
+ openNow();
624
+ },
625
+ pageRestored() {
626
+ opened = false;
627
+ if (pageOpen && consentState === "granted")
628
+ openNow();
629
+ },
613
630
  drops() {
614
631
  const queue = readQueue(ports.storage);
615
632
  return ["queue_overflow", "server_rejected", "invalid_event"]
@@ -851,6 +868,7 @@ let engine;
851
868
  let verification;
852
869
  let configValid = false;
853
870
  let listenersInstalled = false;
871
+ let pageOpened = false;
854
872
  let early = [];
855
873
  function heldForInit(call) {
856
874
  if (engine !== undefined)
@@ -1001,6 +1019,22 @@ function installListeners() {
1001
1019
  void runtime?.flush(true).finally(reportDiagnostic);
1002
1020
  }
1003
1021
  });
1022
+ window.addEventListener("pageshow", (event) => {
1023
+ if (event.persisted)
1024
+ runtime?.pageRestored();
1025
+ });
1026
+ }
1027
+ function openPage() {
1028
+ if (pageOpened || window.top !== window)
1029
+ return;
1030
+ if (window.document.prerendering === true) {
1031
+ window.document.addEventListener("prerenderingchange", openPage, {
1032
+ once: true,
1033
+ });
1034
+ return;
1035
+ }
1036
+ pageOpened = true;
1037
+ runtime?.open();
1004
1038
  }
1005
1039
  function init(options) {
1006
1040
  verification = verificationMode();
@@ -1043,6 +1077,7 @@ function init(options) {
1043
1077
  ...(options.endpoint === undefined ? {} : { endpoint }),
1044
1078
  });
1045
1079
  installListeners();
1080
+ openPage();
1046
1081
  const held = early;
1047
1082
  early = [];
1048
1083
  for (const call of held)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tracelog/capture-web",
3
- "version": "2.1.0",
3
+ "version": "2.3.0",
4
4
  "description": "The TraceLog browser capture runtime: consent-first, pinned per version.",
5
5
  "keywords": [
6
6
  "conversion",
@@ -46,8 +46,8 @@
46
46
  },
47
47
  "devDependencies": {
48
48
  "typescript": "5.9.3",
49
- "@tracelog/capture-core": "2.1.0",
50
- "@tracelog/event-contract": "2.1.0"
49
+ "@tracelog/capture-core": "2.3.0",
50
+ "@tracelog/event-contract": "2.3.0"
51
51
  },
52
52
  "scripts": {
53
53
  "build": "tsc -p tsconfig.build.json && node build.mjs",