@veroxm/sdk 1.9.0 → 1.11.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,26 @@
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
+ // Standard events (increment 8): slotImpression() and formSubmitted() send `$slot_impression` and `$form_submitted`,
52
+ // `track` events with checked properties (standard-events.ts).
53
+ //
54
+ // PostHog (Insights I1): when the project sends test exposures to PostHog, a decision carries `posthog` and the
55
+ // tracker sends the exposure to the page's PostHog (window.posthog, or the `posthog` option) -- see posthog.ts.
56
+ import { ClsWindow, MAX_PATH, RageDetector, campaignKey, clickTarget, fraction, hrefFor, isIgnored, labelFor, nextSession, parseSession, scrollBucket, selectorFor, shortText, vitalsReport, } from './autocapture.js';
57
+ import { findPosthog, readHint, sendPosthogExposure } from './posthog.js';
58
+ import { STANDARD_EVENTS, standardEventProblem } from './standard-events.js';
39
59
  const BATCH_SIZE = 20;
40
60
  const MAX_QUEUE = 1000;
41
61
  const MAX_BACKOFF_MS = 5 * 60 * 1000;
@@ -106,6 +126,16 @@ function uuid() {
106
126
  export class VeroxmTracker {
107
127
  constructor(options) {
108
128
  this.memory = new MemoryStorage();
129
+ /** Tests whose exposure went to PostHog on this page load. */
130
+ this.posthogSent = new Set();
131
+ this.session = null;
132
+ this.pageState = null;
133
+ this.pagesSeen = 0;
134
+ /** Slot impressions sent for this page view (slot:variant). */
135
+ this.impressions = new Set();
136
+ this.vitals = {};
137
+ this.scrollCheckedAt = 0;
138
+ this.scrollTimer = null;
109
139
  this.queue = [];
110
140
  this.timer = null;
111
141
  this.sending = null;
@@ -124,9 +154,15 @@ export class VeroxmTracker {
124
154
  visitor: `veroxm:${options.projectId}:visitor`,
125
155
  consent: `veroxm:${options.projectId}:consent`,
126
156
  queue: `veroxm:${options.projectId}:queue`,
157
+ session: `veroxm:${options.projectId}:session`,
127
158
  };
159
+ const browser = typeof document !== 'undefined' && typeof window !== 'undefined';
160
+ this.autocapture = !!options.autocapture && browser;
161
+ this.slotTest = options.slotTest;
162
+ this.posthogOption = options.posthog;
128
163
  this.consentState = this.readConsent();
129
164
  this.visitorId = this.store().get(this.keys.visitor) ?? uuid();
165
+ this.session = parseSession(this.store().get(this.keys.session));
130
166
  // Campaign attribution: in a browser, the page the visitor arrived on (with its utm tags and ad click ids) and the
131
167
  // page that linked to it. Kept in memory for this page load only; a single-page app keeps it as people move around.
132
168
  if (typeof window !== 'undefined' && window.location) {
@@ -142,13 +178,25 @@ export class VeroxmTracker {
142
178
  this.timer = setInterval(() => void this.flush(), interval);
143
179
  this.timer.unref?.();
144
180
  }
145
- if (typeof document !== 'undefined' && typeof window !== 'undefined') {
146
- // The last chance to send before the tab goes away.
181
+ if (browser) {
182
+ // The last chance to send before the tab goes away: the page-end report first, then everything queued.
147
183
  document.addEventListener('visibilitychange', () => {
148
- if (document.visibilityState === 'hidden')
184
+ if (document.visibilityState === 'hidden') {
185
+ this.pausePage();
186
+ this.reportPage();
149
187
  void this.flush({ keepalive: true });
188
+ }
189
+ else if (this.pageState && this.pageState.visibleSince === null) {
190
+ this.pageState.visibleSince = Date.now();
191
+ }
150
192
  });
151
- window.addEventListener('pagehide', () => void this.flush({ keepalive: true }));
193
+ window.addEventListener('pagehide', () => {
194
+ this.pausePage();
195
+ this.reportPage();
196
+ void this.flush({ keepalive: true });
197
+ });
198
+ if (this.autocapture)
199
+ this.startAutocapture();
152
200
  }
153
201
  }
154
202
  /** The anonymous id for this browser/app install. */
@@ -161,8 +209,43 @@ export class VeroxmTracker {
161
209
  }
162
210
  /** Records an action, e.g. track('demo_requested', { plan: 'enterprise' }). */
163
211
  track(name, properties) {
212
+ // A standard event the API would refuse is dropped here, so it can't get the rest of its batch rejected.
213
+ const problem = standardEventProblem(name, properties);
214
+ if (problem) {
215
+ this.onError(new Error(`VeroXM: ${name} not sent: ${problem}`));
216
+ return;
217
+ }
164
218
  this.enqueue({ type: 'track', name, properties });
165
219
  }
220
+ /**
221
+ * Records that a slot was shown (`$slot_impression`), with the visitor's variant when the slot is under test.
222
+ * Sent once per slot and variant per page view, however often it is called (re-renders don't count again).
223
+ * @since 1.10.0
224
+ */
225
+ slotImpression(slot, test) {
226
+ const key = `${slot}:${test?.variantId ?? ''}`;
227
+ if (this.impressions.has(key))
228
+ return;
229
+ this.impressions.add(key);
230
+ const path = typeof window !== 'undefined' && window.location ? window.location.pathname.slice(0, MAX_PATH) : undefined;
231
+ this.track(STANDARD_EVENTS.slotImpression, {
232
+ slot,
233
+ ...(test ? { experienceId: test.experienceId, variantId: test.variantId } : {}),
234
+ ...(path ? { path } : {}),
235
+ });
236
+ }
237
+ /**
238
+ * Records that a VeroXM form was sent (`$form_submitted`). `embedForm` and `<VeroxmForm>` call this for you when
239
+ * given a tracker. Use `$form_submitted` as an experience's goal to measure form sends.
240
+ * @since 1.10.0
241
+ */
242
+ formSubmitted(form, submission = {}) {
243
+ this.track(STANDARD_EVENTS.formSubmitted, {
244
+ form,
245
+ ...(submission.responseId ? { responseId: submission.responseId } : {}),
246
+ ...(submission.endingId !== undefined ? { endingId: submission.endingId } : {}),
247
+ });
248
+ }
166
249
  /** Records a page or screen view. In a browser, path/url/title/referrer are added automatically. */
167
250
  page(properties) {
168
251
  const auto = {};
@@ -176,7 +259,32 @@ export class VeroxmTracker {
176
259
  auto.referrer = document.referrer;
177
260
  }
178
261
  }
179
- this.enqueue({ type: 'page', properties: { ...auto, ...properties } });
262
+ // A later page view (a single-page app moving on): slots shown on it count again. Impressions recorded before the
263
+ // first page() of a load belong to that first page view.
264
+ if (this.pagesSeen > 0)
265
+ this.impressions.clear();
266
+ // A single-page app moving on: the page before it is done.
267
+ if (this.pageState) {
268
+ this.pausePage();
269
+ this.reportPage();
270
+ this.pageState = null;
271
+ }
272
+ // Only the page this load started on can be a campaign touch (later pages of a single-page app keep the referrer).
273
+ const first = this.pagesSeen++ === 0;
274
+ const touch = first && this.landing ? campaignKey(this.landing.url, this.landing.referrer) : '';
275
+ const sessionId = this.enqueue({ type: 'page', properties: { ...auto, ...properties } }, { touch });
276
+ if (typeof window !== 'undefined' && window.location && typeof document !== 'undefined') {
277
+ this.pageState = {
278
+ path: window.location.pathname.slice(0, MAX_PATH),
279
+ startedAt: new Date().toISOString(),
280
+ sessionId,
281
+ // Page speed is measured for the page the browser loaded, not for a single-page app's later views.
282
+ ids: { end: uuid(), scroll: uuid(), vitals: first ? uuid() : null },
283
+ engagedMs: 0,
284
+ visibleSince: document.visibilityState === 'hidden' ? null : Date.now(),
285
+ depth: 0, // measured on scroll and when the page ends (not now: the page may still be loading)
286
+ };
287
+ }
180
288
  }
181
289
  /** Saves the visitor's consent answers (true = granted, false = denied, omitted = unchanged). */
182
290
  async consent(choices) {
@@ -194,14 +302,18 @@ export class VeroxmTracker {
194
302
  this.storage.set(this.keys.consent, JSON.stringify(next));
195
303
  this.storage.set(this.keys.visitor, this.visitorId);
196
304
  setVisitorCookie(this.visitorId);
197
- if (!wasPersisting)
305
+ if (!wasPersisting) {
198
306
  this.saveQueue();
307
+ this.saveSession();
308
+ }
199
309
  }
200
310
  else if (next.analytics === 'denied') {
201
311
  // Denied: forget everything this tracker kept about the visitor.
202
312
  this.queue = [];
313
+ this.session = null;
203
314
  this.storage.remove(this.keys.queue);
204
315
  this.storage.remove(this.keys.visitor);
316
+ this.storage.remove(this.keys.session);
205
317
  setVisitorCookie(null);
206
318
  this.storage.set(this.keys.consent, JSON.stringify(next)); // remember the answer itself
207
319
  }
@@ -241,10 +353,14 @@ export class VeroxmTracker {
241
353
  reset() {
242
354
  this.queue = [];
243
355
  this.visitorId = uuid();
356
+ this.session = null; // a new person: a new session too
357
+ if (this.pageState)
358
+ this.pageState.sessionId = undefined;
244
359
  if (this.canPersist()) {
245
360
  this.storage.set(this.keys.visitor, this.visitorId);
246
361
  setVisitorCookie(this.visitorId);
247
362
  this.storage.remove(this.keys.queue);
363
+ this.storage.remove(this.keys.session);
248
364
  }
249
365
  this.changed();
250
366
  }
@@ -288,6 +404,9 @@ export class VeroxmTracker {
288
404
  qs += `&url=${encodeURIComponent(this.landing.url.slice(0, 2000))}`;
289
405
  if (this.landing?.referrer)
290
406
  qs += `&referrer=${encodeURIComponent(this.landing.referrer.slice(0, 2000))}`;
407
+ // This page sends exposures to PostHog itself, so VeroXM's server doesn't (it would for a signed-in person).
408
+ if (findPosthog(this.posthogOption))
409
+ qs += '&posthog=browser';
291
410
  const request = fetch(`${this.apiBase}/decide?${qs}`, {
292
411
  headers: { Authorization: `Bearer ${this.key}` },
293
412
  ...(controller ? { signal: controller.signal } : {}),
@@ -295,7 +414,9 @@ export class VeroxmTracker {
295
414
  .then(async (res) => {
296
415
  if (!res.ok)
297
416
  throw new Error(`VeroXM /decide failed with ${res.status}`);
298
- return (await res.json());
417
+ const decision = (await res.json());
418
+ this.sendToPosthog(decision);
419
+ return decision;
299
420
  })
300
421
  .catch((err) => {
301
422
  this.decisions.delete(placement); // try again next time
@@ -357,6 +478,13 @@ export class VeroxmTracker {
357
478
  const value = decision.config?.[key];
358
479
  return value === undefined ? fallback : value;
359
480
  }
481
+ /** A test's exposure to the page's PostHog, once per test per page load (see posthog.ts). Consent is checked by getExperience. */
482
+ sendToPosthog(decision) {
483
+ const hint = readHint(decision.posthog);
484
+ if (!hint || !decision.experienceId || !decision.variantId || !this.canSend())
485
+ return;
486
+ sendPosthogExposure(findPosthog(this.posthogOption), { hint, experienceId: decision.experienceId, variantId: decision.variantId, placement: decision.placement }, this.posthogSent);
487
+ }
360
488
  /** Called when consent, identity or the visitor changes -- ask for experiences again. Returns an unsubscribe function. */
361
489
  subscribe(listener) {
362
490
  this.listeners.add(listener);
@@ -407,28 +535,198 @@ export class VeroxmTracker {
407
535
  // 4xx: this batch will never be accepted (bad key, invalid events) -- drop it.
408
536
  this.onError(err);
409
537
  }
410
- this.queue = this.queue.slice(batch.length);
538
+ // By identity, not position: a report re-queued while this batch was in flight (same id, newer values) stays.
539
+ const done = new Set(batch);
540
+ this.queue = this.queue.filter((e) => !done.has(e));
411
541
  this.saveQueue();
412
542
  this.backoffMs = 0;
413
543
  this.retryAt = 0;
414
544
  }
415
545
  }
416
- enqueue(e) {
546
+ /**
547
+ * Queues an event; returns its session id. Reports (page end, scroll, vitals) pass their page's fixed id, time and
548
+ * session: an unsent copy in the queue is replaced, and a re-sent one replaces the stored one (same id and time).
549
+ */
550
+ enqueue(e, opts = {}) {
417
551
  if (this.requireConsent && this.consentState.analytics === 'denied')
418
- return;
419
- this.queue.push({
420
- eventId: uuid(),
552
+ return undefined;
553
+ const now = Date.now();
554
+ const sessionId = opts.eventId ? opts.sessionId ?? this.session?.id : this.sessionFor(now, opts.touch ?? '');
555
+ const event = {
556
+ eventId: opts.eventId ?? uuid(),
421
557
  visitorId: this.visitorId,
558
+ ...(sessionId ? { sessionId } : {}),
422
559
  type: e.type,
423
560
  ...(e.name ? { name: e.name } : {}),
424
561
  ...(e.properties && Object.keys(e.properties).length ? { properties: e.properties } : {}),
425
- occurredAt: new Date().toISOString(),
426
- });
562
+ ...(e.interaction ? { interaction: e.interaction } : {}),
563
+ occurredAt: opts.occurredAt ?? new Date(now).toISOString(),
564
+ };
565
+ const at = opts.eventId ? this.queue.findIndex((q) => q.eventId === opts.eventId) : -1;
566
+ if (at >= 0)
567
+ this.queue[at] = event;
568
+ else
569
+ this.queue.push(event);
427
570
  if (this.queue.length > MAX_QUEUE)
428
571
  this.queue = this.queue.slice(-MAX_QUEUE);
429
572
  this.saveQueue();
430
573
  if (this.queue.length >= BATCH_SIZE)
431
574
  void this.flush();
575
+ return sessionId;
576
+ }
577
+ /** The session an event now belongs to (D4), kept on the device only when allowed. */
578
+ sessionFor(now, touch) {
579
+ this.session = nextSession(this.session, now, touch, uuid);
580
+ this.saveSession();
581
+ return this.session.id;
582
+ }
583
+ saveSession() {
584
+ if (!this.canPersist() || !this.session)
585
+ return;
586
+ try {
587
+ this.storage.set(this.keys.session, JSON.stringify(this.session));
588
+ }
589
+ catch {
590
+ // storage full -- the session lives in memory for this page
591
+ }
592
+ }
593
+ // ------------------------------------------------------------ page end and autocapture (Insights I0)
594
+ /** Stops the page's visible-time clock (the tab was hidden or left). */
595
+ pausePage() {
596
+ const p = this.pageState;
597
+ if (p && p.visibleSince !== null) {
598
+ p.engagedMs += Math.max(0, Date.now() - p.visibleSince);
599
+ p.visibleSince = null;
600
+ }
601
+ }
602
+ /** The page's reports: engaged time, and with autocapture its scroll depth and page speed. Safe to call repeatedly. */
603
+ reportPage() {
604
+ const p = this.pageState;
605
+ if (!p)
606
+ return;
607
+ const report = { occurredAt: p.startedAt, sessionId: p.sessionId };
608
+ const running = p.visibleSince !== null ? Date.now() - p.visibleSince : 0;
609
+ this.enqueue({ type: 'page_end', interaction: { path: p.path, engagedMs: Math.round(p.engagedMs + running) } }, { ...report, eventId: p.ids.end });
610
+ if (!this.autocapture)
611
+ return;
612
+ this.checkScroll(true);
613
+ const viewportW = Math.round(window.innerWidth || 0);
614
+ this.enqueue({ type: 'scroll', interaction: { path: p.path, depth: p.depth, viewportW } }, { ...report, eventId: p.ids.scroll });
615
+ if (p.ids.vitals) {
616
+ if (this.vitals.ttfb === undefined)
617
+ this.vitals.ttfb = navigationTtfb();
618
+ const metrics = vitalsReport(this.vitals);
619
+ if (metrics)
620
+ this.enqueue({ type: 'vitals', interaction: { path: p.path, metrics, viewportW } }, { ...report, eventId: p.ids.vitals });
621
+ }
622
+ }
623
+ /** Updates the page's deepest scroll bucket (at most every 250 ms unless forced). */
624
+ checkScroll(force = false) {
625
+ const p = this.pageState;
626
+ if (!p)
627
+ return;
628
+ const now = Date.now();
629
+ if (!force && now - this.scrollCheckedAt < 250) {
630
+ // Throttled: look once more when the burst is over, so the deepest point isn't missed.
631
+ this.scrollTimer ?? (this.scrollTimer = setTimeout(() => {
632
+ this.scrollTimer = null;
633
+ this.checkScroll(true);
634
+ }, 250));
635
+ return;
636
+ }
637
+ this.scrollCheckedAt = now;
638
+ const doc = document.documentElement;
639
+ const height = Math.max(doc?.scrollHeight ?? 0, document.body?.scrollHeight ?? 0);
640
+ p.depth = Math.max(p.depth, scrollBucket((window.scrollY || 0) + (window.innerHeight || 0), height));
641
+ }
642
+ startAutocapture() {
643
+ const rage = new RageDetector();
644
+ document.addEventListener('click', (e) => {
645
+ const t = e.target instanceof Element ? e.target : null;
646
+ if (!t || isIgnored(t))
647
+ return;
648
+ const target = clickTarget(t);
649
+ const isRage = rage.hit(e.clientX, e.clientY, Date.now());
650
+ if (!target && !isRage)
651
+ return;
652
+ const data = this.clickData((target ?? t), e);
653
+ if (target)
654
+ this.enqueue({ type: 'click', interaction: data });
655
+ if (isRage)
656
+ this.enqueue({ type: 'rage', interaction: data });
657
+ }, { capture: true, passive: true });
658
+ document.addEventListener('submit', (e) => {
659
+ const form = e.target instanceof Element ? e.target : null;
660
+ if (!form || isIgnored(form))
661
+ return;
662
+ // The form's own id or name only -- never a field or what was typed.
663
+ this.enqueue({
664
+ type: 'submit',
665
+ interaction: {
666
+ path: location.pathname.slice(0, MAX_PATH),
667
+ selector: selectorFor(form),
668
+ label: shortText(form.getAttribute('id') || form.getAttribute('name')),
669
+ viewportW: Math.round(window.innerWidth || 0),
670
+ },
671
+ });
672
+ }, { capture: true, passive: true });
673
+ window.addEventListener('scroll', () => this.checkScroll(), { passive: true });
674
+ this.observeVitals();
675
+ }
676
+ clickData(el, e) {
677
+ const rect = el.getBoundingClientRect();
678
+ const doc = document.documentElement;
679
+ const height = Math.max(doc?.scrollHeight ?? 0, document.body?.scrollHeight ?? 0);
680
+ let test = null;
681
+ try {
682
+ test = this.slotTest?.(el) ?? null;
683
+ }
684
+ catch {
685
+ // the hook's problem; the click still counts
686
+ }
687
+ const href = el.tagName === 'A' ? hrefFor(el.getAttribute('href'), location.href) : '';
688
+ return {
689
+ path: location.pathname.slice(0, MAX_PATH),
690
+ selector: selectorFor(el),
691
+ label: labelFor(el),
692
+ ...(href ? { href } : {}),
693
+ x: fraction(e.clientX - rect.left, rect.width),
694
+ y: fraction(e.clientY - rect.top, rect.height),
695
+ pageY: fraction(e.clientY + (window.scrollY || 0), height),
696
+ viewportW: Math.round(window.innerWidth || 0),
697
+ ...(test ? { experienceId: test.experienceId, variantId: test.variantId } : {}),
698
+ };
699
+ }
700
+ /** LCP, INP (approximated by the longest interaction), CLS -- where the browser measures them. */
701
+ observeVitals() {
702
+ if (typeof PerformanceObserver === 'undefined')
703
+ return;
704
+ const supported = PerformanceObserver.supportedEntryTypes ?? [];
705
+ const observe = (type, onEntry, extra = {}) => {
706
+ if (!supported.includes(type))
707
+ return;
708
+ try {
709
+ new PerformanceObserver((list) => list.getEntries().forEach(onEntry)).observe({ type, buffered: true, ...extra });
710
+ }
711
+ catch {
712
+ // an older browser that lists the type but not these options
713
+ }
714
+ };
715
+ const cls = new ClsWindow();
716
+ if (supported.includes('layout-shift'))
717
+ this.vitals.cls = 0;
718
+ observe('largest-contentful-paint', (e) => (this.vitals.lcp = e.startTime));
719
+ observe('layout-shift', (e) => {
720
+ cls.add(e);
721
+ this.vitals.cls = cls.value;
722
+ });
723
+ const interaction = (e) => {
724
+ if (e.interactionId === 0)
725
+ return;
726
+ this.vitals.inp = Math.max(this.vitals.inp ?? 0, e.duration);
727
+ };
728
+ observe('event', interaction, { durationThreshold: 16 });
729
+ observe('first-input', interaction);
432
730
  }
433
731
  async post(path, body, keepalive = false) {
434
732
  const res = await fetch(`${this.apiBase}${path}`, {
@@ -489,6 +787,16 @@ export class VeroxmTracker {
489
787
  }
490
788
  }
491
789
  }
790
+ /** Time to first byte of the page load, where the browser reports it. */
791
+ function navigationTtfb() {
792
+ try {
793
+ const nav = performance.getEntriesByType('navigation')[0];
794
+ return nav && nav.responseStart > 0 ? nav.responseStart : undefined;
795
+ }
796
+ catch {
797
+ return undefined;
798
+ }
799
+ }
492
800
  /** Creates a tracker. One per page/app; see VeroxmTracker for the API. */
493
801
  export function createTracker(options) {
494
802
  return new VeroxmTracker(options);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@veroxm/sdk",
3
- "version": "1.9.0",
3
+ "version": "1.11.0",
4
4
  "description": "VeroXM client for JavaScript and TypeScript: content, media, experiences, events and the visitor tracker.",
5
5
  "keywords": [
6
6
  "veroxm",