@veroxm/sdk 1.8.0 → 1.10.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/dist/tracker.js CHANGED
@@ -36,6 +36,22 @@
36
36
  // when the page is hidden), retried with backoff on network/server errors
37
37
  // with the same eventId and occurredAt (so the server counts them once),
38
38
  // and -- with consent -- kept in storage across page loads until sent.
39
+ //
40
+ // Insights (docs/INSIGHTS-SCOPE.md, I0): every event carries a session id
41
+ // (a new one after 30 minutes without an event, at midnight UTC, or when a
42
+ // page view is a new campaign touch), kept on the device only with consent,
43
+ // like the visitor id. In a browser, each page also sends a page-end report
44
+ // (visible time on it, engaged_ms) when it is hidden or left. With
45
+ // `autocapture: true` it also records clicks on links, buttons and marked
46
+ // elements, rage clicks, form submits (the form's id or name, never what was
47
+ // typed), how far down each page was scrolled and its Core Web Vitals.
48
+ // data-veroxm-ignore on an element (or an ancestor) leaves it out;
49
+ // data-veroxm-mask keeps its text out. Held until consent like everything else.
50
+ //
51
+ // PostHog (Insights I1): when the project sends test exposures to PostHog, a decision carries `posthog` and the
52
+ // tracker sends the exposure to the page's PostHog (window.posthog, or the `posthog` option) -- see posthog.ts.
53
+ import { ClsWindow, MAX_PATH, RageDetector, campaignKey, clickTarget, fraction, hrefFor, isIgnored, labelFor, nextSession, parseSession, scrollBucket, selectorFor, shortText, vitalsReport, } from './autocapture.js';
54
+ import { findPosthog, readHint, sendPosthogExposure } from './posthog.js';
39
55
  const BATCH_SIZE = 20;
40
56
  const MAX_QUEUE = 1000;
41
57
  const MAX_BACKOFF_MS = 5 * 60 * 1000;
@@ -106,6 +122,14 @@ function uuid() {
106
122
  export class VeroxmTracker {
107
123
  constructor(options) {
108
124
  this.memory = new MemoryStorage();
125
+ /** Tests whose exposure went to PostHog on this page load. */
126
+ this.posthogSent = new Set();
127
+ this.session = null;
128
+ this.pageState = null;
129
+ this.pagesSeen = 0;
130
+ this.vitals = {};
131
+ this.scrollCheckedAt = 0;
132
+ this.scrollTimer = null;
109
133
  this.queue = [];
110
134
  this.timer = null;
111
135
  this.sending = null;
@@ -124,9 +148,15 @@ export class VeroxmTracker {
124
148
  visitor: `veroxm:${options.projectId}:visitor`,
125
149
  consent: `veroxm:${options.projectId}:consent`,
126
150
  queue: `veroxm:${options.projectId}:queue`,
151
+ session: `veroxm:${options.projectId}:session`,
127
152
  };
153
+ const browser = typeof document !== 'undefined' && typeof window !== 'undefined';
154
+ this.autocapture = !!options.autocapture && browser;
155
+ this.slotTest = options.slotTest;
156
+ this.posthogOption = options.posthog;
128
157
  this.consentState = this.readConsent();
129
158
  this.visitorId = this.store().get(this.keys.visitor) ?? uuid();
159
+ this.session = parseSession(this.store().get(this.keys.session));
130
160
  // Campaign attribution: in a browser, the page the visitor arrived on (with its utm tags and ad click ids) and the
131
161
  // page that linked to it. Kept in memory for this page load only; a single-page app keeps it as people move around.
132
162
  if (typeof window !== 'undefined' && window.location) {
@@ -142,13 +172,25 @@ export class VeroxmTracker {
142
172
  this.timer = setInterval(() => void this.flush(), interval);
143
173
  this.timer.unref?.();
144
174
  }
145
- if (typeof document !== 'undefined' && typeof window !== 'undefined') {
146
- // The last chance to send before the tab goes away.
175
+ if (browser) {
176
+ // The last chance to send before the tab goes away: the page-end report first, then everything queued.
147
177
  document.addEventListener('visibilitychange', () => {
148
- if (document.visibilityState === 'hidden')
178
+ if (document.visibilityState === 'hidden') {
179
+ this.pausePage();
180
+ this.reportPage();
149
181
  void this.flush({ keepalive: true });
182
+ }
183
+ else if (this.pageState && this.pageState.visibleSince === null) {
184
+ this.pageState.visibleSince = Date.now();
185
+ }
150
186
  });
151
- window.addEventListener('pagehide', () => void this.flush({ keepalive: true }));
187
+ window.addEventListener('pagehide', () => {
188
+ this.pausePage();
189
+ this.reportPage();
190
+ void this.flush({ keepalive: true });
191
+ });
192
+ if (this.autocapture)
193
+ this.startAutocapture();
152
194
  }
153
195
  }
154
196
  /** The anonymous id for this browser/app install. */
@@ -176,7 +218,28 @@ export class VeroxmTracker {
176
218
  auto.referrer = document.referrer;
177
219
  }
178
220
  }
179
- this.enqueue({ type: 'page', properties: { ...auto, ...properties } });
221
+ // A single-page app moving on: the page before it is done.
222
+ if (this.pageState) {
223
+ this.pausePage();
224
+ this.reportPage();
225
+ this.pageState = null;
226
+ }
227
+ // Only the page this load started on can be a campaign touch (later pages of a single-page app keep the referrer).
228
+ const first = this.pagesSeen++ === 0;
229
+ const touch = first && this.landing ? campaignKey(this.landing.url, this.landing.referrer) : '';
230
+ const sessionId = this.enqueue({ type: 'page', properties: { ...auto, ...properties } }, { touch });
231
+ if (typeof window !== 'undefined' && window.location && typeof document !== 'undefined') {
232
+ this.pageState = {
233
+ path: window.location.pathname.slice(0, MAX_PATH),
234
+ startedAt: new Date().toISOString(),
235
+ sessionId,
236
+ // Page speed is measured for the page the browser loaded, not for a single-page app's later views.
237
+ ids: { end: uuid(), scroll: uuid(), vitals: first ? uuid() : null },
238
+ engagedMs: 0,
239
+ visibleSince: document.visibilityState === 'hidden' ? null : Date.now(),
240
+ depth: 0, // measured on scroll and when the page ends (not now: the page may still be loading)
241
+ };
242
+ }
180
243
  }
181
244
  /** Saves the visitor's consent answers (true = granted, false = denied, omitted = unchanged). */
182
245
  async consent(choices) {
@@ -194,14 +257,18 @@ export class VeroxmTracker {
194
257
  this.storage.set(this.keys.consent, JSON.stringify(next));
195
258
  this.storage.set(this.keys.visitor, this.visitorId);
196
259
  setVisitorCookie(this.visitorId);
197
- if (!wasPersisting)
260
+ if (!wasPersisting) {
198
261
  this.saveQueue();
262
+ this.saveSession();
263
+ }
199
264
  }
200
265
  else if (next.analytics === 'denied') {
201
266
  // Denied: forget everything this tracker kept about the visitor.
202
267
  this.queue = [];
268
+ this.session = null;
203
269
  this.storage.remove(this.keys.queue);
204
270
  this.storage.remove(this.keys.visitor);
271
+ this.storage.remove(this.keys.session);
205
272
  setVisitorCookie(null);
206
273
  this.storage.set(this.keys.consent, JSON.stringify(next)); // remember the answer itself
207
274
  }
@@ -241,10 +308,14 @@ export class VeroxmTracker {
241
308
  reset() {
242
309
  this.queue = [];
243
310
  this.visitorId = uuid();
311
+ this.session = null; // a new person: a new session too
312
+ if (this.pageState)
313
+ this.pageState.sessionId = undefined;
244
314
  if (this.canPersist()) {
245
315
  this.storage.set(this.keys.visitor, this.visitorId);
246
316
  setVisitorCookie(this.visitorId);
247
317
  this.storage.remove(this.keys.queue);
318
+ this.storage.remove(this.keys.session);
248
319
  }
249
320
  this.changed();
250
321
  }
@@ -288,6 +359,9 @@ export class VeroxmTracker {
288
359
  qs += `&url=${encodeURIComponent(this.landing.url.slice(0, 2000))}`;
289
360
  if (this.landing?.referrer)
290
361
  qs += `&referrer=${encodeURIComponent(this.landing.referrer.slice(0, 2000))}`;
362
+ // This page sends exposures to PostHog itself, so VeroXM's server doesn't (it would for a signed-in person).
363
+ if (findPosthog(this.posthogOption))
364
+ qs += '&posthog=browser';
291
365
  const request = fetch(`${this.apiBase}/decide?${qs}`, {
292
366
  headers: { Authorization: `Bearer ${this.key}` },
293
367
  ...(controller ? { signal: controller.signal } : {}),
@@ -295,7 +369,9 @@ export class VeroxmTracker {
295
369
  .then(async (res) => {
296
370
  if (!res.ok)
297
371
  throw new Error(`VeroXM /decide failed with ${res.status}`);
298
- return (await res.json());
372
+ const decision = (await res.json());
373
+ this.sendToPosthog(decision);
374
+ return decision;
299
375
  })
300
376
  .catch((err) => {
301
377
  this.decisions.delete(placement); // try again next time
@@ -357,6 +433,13 @@ export class VeroxmTracker {
357
433
  const value = decision.config?.[key];
358
434
  return value === undefined ? fallback : value;
359
435
  }
436
+ /** A test's exposure to the page's PostHog, once per test per page load (see posthog.ts). Consent is checked by getExperience. */
437
+ sendToPosthog(decision) {
438
+ const hint = readHint(decision.posthog);
439
+ if (!hint || !decision.experienceId || !decision.variantId || !this.canSend())
440
+ return;
441
+ sendPosthogExposure(findPosthog(this.posthogOption), { hint, experienceId: decision.experienceId, variantId: decision.variantId, placement: decision.placement }, this.posthogSent);
442
+ }
360
443
  /** Called when consent, identity or the visitor changes -- ask for experiences again. Returns an unsubscribe function. */
361
444
  subscribe(listener) {
362
445
  this.listeners.add(listener);
@@ -407,28 +490,198 @@ export class VeroxmTracker {
407
490
  // 4xx: this batch will never be accepted (bad key, invalid events) -- drop it.
408
491
  this.onError(err);
409
492
  }
410
- this.queue = this.queue.slice(batch.length);
493
+ // By identity, not position: a report re-queued while this batch was in flight (same id, newer values) stays.
494
+ const done = new Set(batch);
495
+ this.queue = this.queue.filter((e) => !done.has(e));
411
496
  this.saveQueue();
412
497
  this.backoffMs = 0;
413
498
  this.retryAt = 0;
414
499
  }
415
500
  }
416
- enqueue(e) {
501
+ /**
502
+ * Queues an event; returns its session id. Reports (page end, scroll, vitals) pass their page's fixed id, time and
503
+ * session: an unsent copy in the queue is replaced, and a re-sent one replaces the stored one (same id and time).
504
+ */
505
+ enqueue(e, opts = {}) {
417
506
  if (this.requireConsent && this.consentState.analytics === 'denied')
418
- return;
419
- this.queue.push({
420
- eventId: uuid(),
507
+ return undefined;
508
+ const now = Date.now();
509
+ const sessionId = opts.eventId ? opts.sessionId ?? this.session?.id : this.sessionFor(now, opts.touch ?? '');
510
+ const event = {
511
+ eventId: opts.eventId ?? uuid(),
421
512
  visitorId: this.visitorId,
513
+ ...(sessionId ? { sessionId } : {}),
422
514
  type: e.type,
423
515
  ...(e.name ? { name: e.name } : {}),
424
516
  ...(e.properties && Object.keys(e.properties).length ? { properties: e.properties } : {}),
425
- occurredAt: new Date().toISOString(),
426
- });
517
+ ...(e.interaction ? { interaction: e.interaction } : {}),
518
+ occurredAt: opts.occurredAt ?? new Date(now).toISOString(),
519
+ };
520
+ const at = opts.eventId ? this.queue.findIndex((q) => q.eventId === opts.eventId) : -1;
521
+ if (at >= 0)
522
+ this.queue[at] = event;
523
+ else
524
+ this.queue.push(event);
427
525
  if (this.queue.length > MAX_QUEUE)
428
526
  this.queue = this.queue.slice(-MAX_QUEUE);
429
527
  this.saveQueue();
430
528
  if (this.queue.length >= BATCH_SIZE)
431
529
  void this.flush();
530
+ return sessionId;
531
+ }
532
+ /** The session an event now belongs to (D4), kept on the device only when allowed. */
533
+ sessionFor(now, touch) {
534
+ this.session = nextSession(this.session, now, touch, uuid);
535
+ this.saveSession();
536
+ return this.session.id;
537
+ }
538
+ saveSession() {
539
+ if (!this.canPersist() || !this.session)
540
+ return;
541
+ try {
542
+ this.storage.set(this.keys.session, JSON.stringify(this.session));
543
+ }
544
+ catch {
545
+ // storage full -- the session lives in memory for this page
546
+ }
547
+ }
548
+ // ------------------------------------------------------------ page end and autocapture (Insights I0)
549
+ /** Stops the page's visible-time clock (the tab was hidden or left). */
550
+ pausePage() {
551
+ const p = this.pageState;
552
+ if (p && p.visibleSince !== null) {
553
+ p.engagedMs += Math.max(0, Date.now() - p.visibleSince);
554
+ p.visibleSince = null;
555
+ }
556
+ }
557
+ /** The page's reports: engaged time, and with autocapture its scroll depth and page speed. Safe to call repeatedly. */
558
+ reportPage() {
559
+ const p = this.pageState;
560
+ if (!p)
561
+ return;
562
+ const report = { occurredAt: p.startedAt, sessionId: p.sessionId };
563
+ const running = p.visibleSince !== null ? Date.now() - p.visibleSince : 0;
564
+ this.enqueue({ type: 'page_end', interaction: { path: p.path, engagedMs: Math.round(p.engagedMs + running) } }, { ...report, eventId: p.ids.end });
565
+ if (!this.autocapture)
566
+ return;
567
+ this.checkScroll(true);
568
+ const viewportW = Math.round(window.innerWidth || 0);
569
+ this.enqueue({ type: 'scroll', interaction: { path: p.path, depth: p.depth, viewportW } }, { ...report, eventId: p.ids.scroll });
570
+ if (p.ids.vitals) {
571
+ if (this.vitals.ttfb === undefined)
572
+ this.vitals.ttfb = navigationTtfb();
573
+ const metrics = vitalsReport(this.vitals);
574
+ if (metrics)
575
+ this.enqueue({ type: 'vitals', interaction: { path: p.path, metrics, viewportW } }, { ...report, eventId: p.ids.vitals });
576
+ }
577
+ }
578
+ /** Updates the page's deepest scroll bucket (at most every 250 ms unless forced). */
579
+ checkScroll(force = false) {
580
+ const p = this.pageState;
581
+ if (!p)
582
+ return;
583
+ const now = Date.now();
584
+ if (!force && now - this.scrollCheckedAt < 250) {
585
+ // Throttled: look once more when the burst is over, so the deepest point isn't missed.
586
+ this.scrollTimer ?? (this.scrollTimer = setTimeout(() => {
587
+ this.scrollTimer = null;
588
+ this.checkScroll(true);
589
+ }, 250));
590
+ return;
591
+ }
592
+ this.scrollCheckedAt = now;
593
+ const doc = document.documentElement;
594
+ const height = Math.max(doc?.scrollHeight ?? 0, document.body?.scrollHeight ?? 0);
595
+ p.depth = Math.max(p.depth, scrollBucket((window.scrollY || 0) + (window.innerHeight || 0), height));
596
+ }
597
+ startAutocapture() {
598
+ const rage = new RageDetector();
599
+ document.addEventListener('click', (e) => {
600
+ const t = e.target instanceof Element ? e.target : null;
601
+ if (!t || isIgnored(t))
602
+ return;
603
+ const target = clickTarget(t);
604
+ const isRage = rage.hit(e.clientX, e.clientY, Date.now());
605
+ if (!target && !isRage)
606
+ return;
607
+ const data = this.clickData((target ?? t), e);
608
+ if (target)
609
+ this.enqueue({ type: 'click', interaction: data });
610
+ if (isRage)
611
+ this.enqueue({ type: 'rage', interaction: data });
612
+ }, { capture: true, passive: true });
613
+ document.addEventListener('submit', (e) => {
614
+ const form = e.target instanceof Element ? e.target : null;
615
+ if (!form || isIgnored(form))
616
+ return;
617
+ // The form's own id or name only -- never a field or what was typed.
618
+ this.enqueue({
619
+ type: 'submit',
620
+ interaction: {
621
+ path: location.pathname.slice(0, MAX_PATH),
622
+ selector: selectorFor(form),
623
+ label: shortText(form.getAttribute('id') || form.getAttribute('name')),
624
+ viewportW: Math.round(window.innerWidth || 0),
625
+ },
626
+ });
627
+ }, { capture: true, passive: true });
628
+ window.addEventListener('scroll', () => this.checkScroll(), { passive: true });
629
+ this.observeVitals();
630
+ }
631
+ clickData(el, e) {
632
+ const rect = el.getBoundingClientRect();
633
+ const doc = document.documentElement;
634
+ const height = Math.max(doc?.scrollHeight ?? 0, document.body?.scrollHeight ?? 0);
635
+ let test = null;
636
+ try {
637
+ test = this.slotTest?.(el) ?? null;
638
+ }
639
+ catch {
640
+ // the hook's problem; the click still counts
641
+ }
642
+ const href = el.tagName === 'A' ? hrefFor(el.getAttribute('href'), location.href) : '';
643
+ return {
644
+ path: location.pathname.slice(0, MAX_PATH),
645
+ selector: selectorFor(el),
646
+ label: labelFor(el),
647
+ ...(href ? { href } : {}),
648
+ x: fraction(e.clientX - rect.left, rect.width),
649
+ y: fraction(e.clientY - rect.top, rect.height),
650
+ pageY: fraction(e.clientY + (window.scrollY || 0), height),
651
+ viewportW: Math.round(window.innerWidth || 0),
652
+ ...(test ? { experienceId: test.experienceId, variantId: test.variantId } : {}),
653
+ };
654
+ }
655
+ /** LCP, INP (approximated by the longest interaction), CLS -- where the browser measures them. */
656
+ observeVitals() {
657
+ if (typeof PerformanceObserver === 'undefined')
658
+ return;
659
+ const supported = PerformanceObserver.supportedEntryTypes ?? [];
660
+ const observe = (type, onEntry, extra = {}) => {
661
+ if (!supported.includes(type))
662
+ return;
663
+ try {
664
+ new PerformanceObserver((list) => list.getEntries().forEach(onEntry)).observe({ type, buffered: true, ...extra });
665
+ }
666
+ catch {
667
+ // an older browser that lists the type but not these options
668
+ }
669
+ };
670
+ const cls = new ClsWindow();
671
+ if (supported.includes('layout-shift'))
672
+ this.vitals.cls = 0;
673
+ observe('largest-contentful-paint', (e) => (this.vitals.lcp = e.startTime));
674
+ observe('layout-shift', (e) => {
675
+ cls.add(e);
676
+ this.vitals.cls = cls.value;
677
+ });
678
+ const interaction = (e) => {
679
+ if (e.interactionId === 0)
680
+ return;
681
+ this.vitals.inp = Math.max(this.vitals.inp ?? 0, e.duration);
682
+ };
683
+ observe('event', interaction, { durationThreshold: 16 });
684
+ observe('first-input', interaction);
432
685
  }
433
686
  async post(path, body, keepalive = false) {
434
687
  const res = await fetch(`${this.apiBase}${path}`, {
@@ -489,6 +742,16 @@ export class VeroxmTracker {
489
742
  }
490
743
  }
491
744
  }
745
+ /** Time to first byte of the page load, where the browser reports it. */
746
+ function navigationTtfb() {
747
+ try {
748
+ const nav = performance.getEntriesByType('navigation')[0];
749
+ return nav && nav.responseStart > 0 ? nav.responseStart : undefined;
750
+ }
751
+ catch {
752
+ return undefined;
753
+ }
754
+ }
492
755
  /** Creates a tracker. One per page/app; see VeroxmTracker for the API. */
493
756
  export function createTracker(options) {
494
757
  return new VeroxmTracker(options);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "1.8.0",
3
+ "version": "1.10.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",