@tracelog/capture-web 2.2.0 → 2.3.1

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,20 @@ 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.1](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.3.0...capture-web@2.3.1) (2026-10-26)
22
+
23
+
24
+ ### Fixed
25
+
26
+ * **capture-web:** a deferred runtime rules out the Meta form it could not have missed ([aa0eb2b](https://github.com/nacorga/tracelog-sdk/commit/aa0eb2b3506d0ba7bfb9549e9a5f851af89b4577))
27
+
28
+ ## [2.3.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.2.0...capture-web@2.3.0) (2026-10-17)
29
+
30
+
31
+ ### Added
32
+
33
+ * **capture-web:** the page it loads on opens the session ([259cad7](https://github.com/nacorga/tracelog-sdk/commit/259cad70dc2f4bc14c0b1827b80c870fe443bd93))
34
+
21
35
  ## [2.2.0](https://github.com/nacorga/tracelog-sdk/compare/capture-web@2.1.0...capture-web@2.2.0) (2026-10-16)
22
36
 
23
37
 
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.2.0
25
+ npm install --save-exact @tracelog/capture-web@2.3.1
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.2.0/tracelog.js"></script>
31
+ <script src="https://cdn.tracelog.io/v/2.3.1/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"]
@@ -627,6 +644,7 @@ function instantOfEntry(startTime) {
627
644
  return new Date(systemClock.now().getTime() - (performance.now() - startTime));
628
645
  }
629
646
  const TAG_SIGHTING_MEMORY = 100;
647
+ const RESOURCE_TIMING_BUFFER = 250;
630
648
  const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
631
649
  const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
632
650
  const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
@@ -637,6 +655,16 @@ function onMetaEndpoint(url) {
637
655
  return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
638
656
  (url.pathname === "/tr" || url.pathname === "/tr/"));
639
657
  }
658
+ function isMetaConfiguration(url) {
659
+ try {
660
+ const parsed = new URL(url);
661
+ return (parsed.hostname === "connect.facebook.net" &&
662
+ parsed.pathname.startsWith("/signals/config/"));
663
+ }
664
+ catch {
665
+ return false;
666
+ }
667
+ }
640
668
  function metaMatch(id, event) {
641
669
  return id !== null && metaIdPattern.test(id)
642
670
  ? {
@@ -699,6 +727,9 @@ function createTagSightingPort() {
699
727
  let observer;
700
728
  let bodyObserver;
701
729
  let watchedFrom;
730
+ let metaFrom = Number.POSITIVE_INFINITY;
731
+ let startedAt = 0;
732
+ let buffered = 0;
702
733
  let matches = [];
703
734
  function remember(match, at) {
704
735
  if (match === null)
@@ -712,7 +743,19 @@ function createTagSightingPort() {
712
743
  }
713
744
  function record(entries) {
714
745
  for (const entry of entries) {
715
- remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
746
+ if (entry.startTime < startedAt)
747
+ buffered += 1;
748
+ const at = instantOfEntry(entry.startTime).getTime();
749
+ const match = matchTagRequest(entry.name);
750
+ remember(match, at);
751
+ const meta = match !== null &&
752
+ ("unread" in match ? match.unread : match.sighting.kind) === "meta";
753
+ if (meta) {
754
+ metaFrom = Math.min(metaFrom, at);
755
+ }
756
+ else if (isMetaConfiguration(entry.name)) {
757
+ metaFrom = Math.min(metaFrom, instantOfEntry(entry.startTime + entry.duration).getTime());
758
+ }
716
759
  }
717
760
  }
718
761
  function watchBody() {
@@ -779,6 +822,7 @@ function createTagSightingPort() {
779
822
  return;
780
823
  }
781
824
  const created = new Observer((list) => record(list.getEntries()));
825
+ startedAt = performance.now();
782
826
  created.observe({ type: "resource", buffered: true });
783
827
  observer = created;
784
828
  }
@@ -794,6 +838,8 @@ function createTagSightingPort() {
794
838
  bodyObserver?.disconnect();
795
839
  bodyObserver = undefined;
796
840
  watchedFrom = undefined;
841
+ metaFrom = Number.POSITIVE_INFINITY;
842
+ buffered = 0;
797
843
  matches = [];
798
844
  },
799
845
  observing() {
@@ -819,11 +865,12 @@ function createTagSightingPort() {
819
865
  },
820
866
  unreadAround(at) {
821
867
  const found = within(at);
822
- if (found === null ||
823
- watchedFrom === undefined ||
824
- watchedFrom > at.getTime() - TAG_SIGHTING_BEFORE_MS) {
868
+ if (found === null || watchedFrom === undefined)
869
+ return null;
870
+ const missedNone = watchedFrom <= at.getTime() - TAG_SIGHTING_BEFORE_MS ||
871
+ (watchedFrom <= metaFrom && buffered < RESOURCE_TIMING_BUFFER);
872
+ if (!missedNone)
825
873
  return null;
826
- }
827
874
  return tagSightingKinds.filter((kind) => found.some((match) => "unread" in match && match.unread === kind));
828
875
  },
829
876
  };
@@ -850,6 +897,7 @@ let engine;
850
897
  let verification;
851
898
  let configValid = false;
852
899
  let listenersInstalled = false;
900
+ let pageOpened = false;
853
901
  let early = [];
854
902
  function heldForInit(call) {
855
903
  if (engine !== undefined)
@@ -1000,6 +1048,22 @@ function installListeners() {
1000
1048
  void runtime?.flush(true).finally(reportDiagnostic);
1001
1049
  }
1002
1050
  });
1051
+ window.addEventListener("pageshow", (event) => {
1052
+ if (event.persisted)
1053
+ runtime?.pageRestored();
1054
+ });
1055
+ }
1056
+ function openPage() {
1057
+ if (pageOpened || window.top !== window)
1058
+ return;
1059
+ if (window.document.prerendering === true) {
1060
+ window.document.addEventListener("prerenderingchange", openPage, {
1061
+ once: true,
1062
+ });
1063
+ return;
1064
+ }
1065
+ pageOpened = true;
1066
+ runtime?.open();
1003
1067
  }
1004
1068
  function init(options) {
1005
1069
  verification = verificationMode();
@@ -1042,6 +1106,7 @@ function init(options) {
1042
1106
  ...(options.endpoint === undefined ? {} : { endpoint }),
1043
1107
  });
1044
1108
  installListeners();
1109
+ openPage();
1045
1110
  const held = early;
1046
1111
  early = [];
1047
1112
  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"]
@@ -628,6 +645,7 @@ function instantOfEntry(startTime) {
628
645
  return new Date(systemClock.now().getTime() - (performance.now() - startTime));
629
646
  }
630
647
  const TAG_SIGHTING_MEMORY = 100;
648
+ const RESOURCE_TIMING_BUFFER = 250;
631
649
  const ga4IdPattern = new RegExp(TAG_ID_PATTERNS.ga4);
632
650
  const metaIdPattern = new RegExp(TAG_ID_PATTERNS.meta);
633
651
  const adsIdPattern = new RegExp(TAG_ID_PATTERNS.google_ads);
@@ -638,6 +656,16 @@ function onMetaEndpoint(url) {
638
656
  return ((host === "facebook.com" || host.endsWith(".facebook.com")) &&
639
657
  (url.pathname === "/tr" || url.pathname === "/tr/"));
640
658
  }
659
+ function isMetaConfiguration(url) {
660
+ try {
661
+ const parsed = new URL(url);
662
+ return (parsed.hostname === "connect.facebook.net" &&
663
+ parsed.pathname.startsWith("/signals/config/"));
664
+ }
665
+ catch {
666
+ return false;
667
+ }
668
+ }
641
669
  function metaMatch(id, event) {
642
670
  return id !== null && metaIdPattern.test(id)
643
671
  ? {
@@ -700,6 +728,9 @@ function createTagSightingPort() {
700
728
  let observer;
701
729
  let bodyObserver;
702
730
  let watchedFrom;
731
+ let metaFrom = Number.POSITIVE_INFINITY;
732
+ let startedAt = 0;
733
+ let buffered = 0;
703
734
  let matches = [];
704
735
  function remember(match, at) {
705
736
  if (match === null)
@@ -713,7 +744,19 @@ function createTagSightingPort() {
713
744
  }
714
745
  function record(entries) {
715
746
  for (const entry of entries) {
716
- remember(matchTagRequest(entry.name), instantOfEntry(entry.startTime).getTime());
747
+ if (entry.startTime < startedAt)
748
+ buffered += 1;
749
+ const at = instantOfEntry(entry.startTime).getTime();
750
+ const match = matchTagRequest(entry.name);
751
+ remember(match, at);
752
+ const meta = match !== null &&
753
+ ("unread" in match ? match.unread : match.sighting.kind) === "meta";
754
+ if (meta) {
755
+ metaFrom = Math.min(metaFrom, at);
756
+ }
757
+ else if (isMetaConfiguration(entry.name)) {
758
+ metaFrom = Math.min(metaFrom, instantOfEntry(entry.startTime + entry.duration).getTime());
759
+ }
717
760
  }
718
761
  }
719
762
  function watchBody() {
@@ -780,6 +823,7 @@ function createTagSightingPort() {
780
823
  return;
781
824
  }
782
825
  const created = new Observer((list) => record(list.getEntries()));
826
+ startedAt = performance.now();
783
827
  created.observe({ type: "resource", buffered: true });
784
828
  observer = created;
785
829
  }
@@ -795,6 +839,8 @@ function createTagSightingPort() {
795
839
  bodyObserver?.disconnect();
796
840
  bodyObserver = undefined;
797
841
  watchedFrom = undefined;
842
+ metaFrom = Number.POSITIVE_INFINITY;
843
+ buffered = 0;
798
844
  matches = [];
799
845
  },
800
846
  observing() {
@@ -820,11 +866,12 @@ function createTagSightingPort() {
820
866
  },
821
867
  unreadAround(at) {
822
868
  const found = within(at);
823
- if (found === null ||
824
- watchedFrom === undefined ||
825
- watchedFrom > at.getTime() - TAG_SIGHTING_BEFORE_MS) {
869
+ if (found === null || watchedFrom === undefined)
870
+ return null;
871
+ const missedNone = watchedFrom <= at.getTime() - TAG_SIGHTING_BEFORE_MS ||
872
+ (watchedFrom <= metaFrom && buffered < RESOURCE_TIMING_BUFFER);
873
+ if (!missedNone)
826
874
  return null;
827
- }
828
875
  return tagSightingKinds.filter((kind) => found.some((match) => "unread" in match && match.unread === kind));
829
876
  },
830
877
  };
@@ -851,6 +898,7 @@ let engine;
851
898
  let verification;
852
899
  let configValid = false;
853
900
  let listenersInstalled = false;
901
+ let pageOpened = false;
854
902
  let early = [];
855
903
  function heldForInit(call) {
856
904
  if (engine !== undefined)
@@ -1001,6 +1049,22 @@ function installListeners() {
1001
1049
  void runtime?.flush(true).finally(reportDiagnostic);
1002
1050
  }
1003
1051
  });
1052
+ window.addEventListener("pageshow", (event) => {
1053
+ if (event.persisted)
1054
+ runtime?.pageRestored();
1055
+ });
1056
+ }
1057
+ function openPage() {
1058
+ if (pageOpened || window.top !== window)
1059
+ return;
1060
+ if (window.document.prerendering === true) {
1061
+ window.document.addEventListener("prerenderingchange", openPage, {
1062
+ once: true,
1063
+ });
1064
+ return;
1065
+ }
1066
+ pageOpened = true;
1067
+ runtime?.open();
1004
1068
  }
1005
1069
  function init(options) {
1006
1070
  verification = verificationMode();
@@ -1043,6 +1107,7 @@ function init(options) {
1043
1107
  ...(options.endpoint === undefined ? {} : { endpoint }),
1044
1108
  });
1045
1109
  installListeners();
1110
+ openPage();
1046
1111
  const held = early;
1047
1112
  early = [];
1048
1113
  for (const call of held)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tracelog/capture-web",
3
- "version": "2.2.0",
3
+ "version": "2.3.1",
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.2.0",
50
- "@tracelog/event-contract": "2.2.0"
49
+ "@tracelog/capture-core": "2.3.1",
50
+ "@tracelog/event-contract": "2.3.1"
51
51
  },
52
52
  "scripts": {
53
53
  "build": "tsc -p tsconfig.build.json && node build.mjs",