diff --git a/api-docs/docs/browser-tracker/browser-tracker.api.md b/api-docs/docs/browser-tracker/browser-tracker.api.md index c69366c54..4c74daca1 100644 --- a/api-docs/docs/browser-tracker/browser-tracker.api.md +++ b/api-docs/docs/browser-tracker/browser-tracker.api.md @@ -15,10 +15,21 @@ export type ActivityCallbackData = { minYOffset: number; maxXOffset: number; maxYOffset: number; + activityMetrics?: ActivityMetrics; +}; + +// @public +export type ActivityMetrics = { + mouseDistance: number; + scrollDistance: number; + keyPresses: number; + clicks: number; + touches: number; }; // @public export interface ActivityTrackingConfiguration { + activityMetrics?: boolean; heartbeatDelay: number; minimumVisitLength: number; } diff --git a/common/changes/@snowplow/browser-tracker-core/feature-extended-activity-tracking_2026-04-06-13-19.json b/common/changes/@snowplow/browser-tracker-core/feature-extended-activity-tracking_2026-04-06-13-19.json new file mode 100644 index 000000000..384f557c3 --- /dev/null +++ b/common/changes/@snowplow/browser-tracker-core/feature-extended-activity-tracking_2026-04-06-13-19.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "comment": "Add opt-in activity metrics tracking with activity_metrics entity", + "type": "none", + "packageName": "@snowplow/browser-tracker-core" + } + ], + "packageName": "@snowplow/browser-tracker-core" +} \ No newline at end of file diff --git a/common/changes/@snowplow/browser-tracker/feature-extended-activity-tracking_2026-04-06-13-19.json b/common/changes/@snowplow/browser-tracker/feature-extended-activity-tracking_2026-04-06-13-19.json new file mode 100644 index 000000000..dd50bd92a --- /dev/null +++ b/common/changes/@snowplow/browser-tracker/feature-extended-activity-tracking_2026-04-06-13-19.json @@ -0,0 +1,10 @@ +{ + "changes": [ + { + "comment": "Add opt-in activity metrics tracking with activity_metrics entity", + "type": "none", + "packageName": "@snowplow/browser-tracker" + } + ], + "packageName": "@snowplow/browser-tracker" +} \ No newline at end of file diff --git a/libraries/browser-tracker-core/src/tracker/index.ts b/libraries/browser-tracker-core/src/tracker/index.ts index 7d4b8cac4..edd8b5ea8 100755 --- a/libraries/browser-tracker-core/src/tracker/index.ts +++ b/libraries/browser-tracker-core/src/tracker/index.ts @@ -35,6 +35,7 @@ import { PageViewEvent, ActivityCallback, ActivityCallbackData, + ActivityMetrics, TrackerConfiguration, BrowserTracker, ActivityTrackingConfiguration, @@ -65,7 +66,13 @@ import { emptyIdCookie, eventIndexFromIdCookie, } from './id_cookie'; -import { CLIENT_SESSION_SCHEMA, WEB_PAGE_SCHEMA, BROWSER_CONTEXT_SCHEMA, APPLICATION_CONTEXT_SCHEMA } from './schemata'; +import { + CLIENT_SESSION_SCHEMA, + WEB_PAGE_SCHEMA, + BROWSER_CONTEXT_SCHEMA, + APPLICATION_CONTEXT_SCHEMA, + ACTIVITY_METRICS_SCHEMA, +} from './schemata'; import { getBrowserProperties } from '../helpers/browser_props'; import { asyncCookieStorage, syncCookieStorage } from './cookie_storage'; @@ -88,6 +95,8 @@ type ActivityConfig = { configHeartBeatTimer: number; /** The setInterval identifier */ activityInterval?: number; + /** Whether activity metrics tracking is enabled for this configuration */ + activityMetrics?: boolean; }; /** The configurations for the two types of Activity Tracking */ @@ -264,6 +273,14 @@ export function Tracker( maxXOffset: number, minYOffset: number, maxYOffset: number, + // Activity metrics tracking state + activityMetricsState = { + metrics: { mouseDistance: 0, scrollDistance: 0, keyPresses: 0, clicks: 0, touches: 0 } as ActivityMetrics, + lastMouseX: undefined as number | undefined, + lastMouseY: undefined as number | undefined, + lastScrollX: undefined as number | undefined, + lastScrollY: undefined as number | undefined, + }, // Domain hash value domainHash: string, // Domain unique user ID @@ -514,17 +531,66 @@ export function Tracker( * Process all "activity" events. * For performance, this function must have low overhead. */ - function activityHandler() { + function activityHandler(event?: Event) { const now = new Date(); lastActivityTime = now.getTime(); + + if (isActivityMetricsEnabled() && event) { + switch (event.type) { + case 'mousemove': { + const me = event as MouseEvent; + if (activityMetricsState.lastMouseX !== undefined && activityMetricsState.lastMouseY !== undefined) { + const dx = me.clientX - activityMetricsState.lastMouseX; + const dy = me.clientY - activityMetricsState.lastMouseY; + activityMetricsState.metrics.mouseDistance += Math.sqrt(dx * dx + dy * dy); + } + activityMetricsState.lastMouseX = me.clientX; + activityMetricsState.lastMouseY = me.clientY; + break; + } + case 'click': + activityMetricsState.metrics.clicks++; + break; + case 'keydown': + activityMetricsState.metrics.keyPresses++; + break; + case 'touchstart': + activityMetricsState.metrics.touches++; + break; + // scroll handled in scrollHandler + } + } } /* * Process all "scroll" events. */ function scrollHandler() { - updateMaxScrolls(); activityHandler(); + + const offsets = getPageOffsets(); + + const x = offsets[0]; + if (x < minXOffset) { + minXOffset = x; + } else if (x > maxXOffset) { + maxXOffset = x; + } + + const y = offsets[1]; + if (y < minYOffset) { + minYOffset = y; + } else if (y > maxYOffset) { + maxYOffset = y; + } + + if (isActivityMetricsEnabled()) { + if (activityMetricsState.lastScrollX !== undefined && activityMetricsState.lastScrollY !== undefined) { + activityMetricsState.metrics.scrollDistance += Math.abs(x - activityMetricsState.lastScrollX) + Math.abs(y - activityMetricsState.lastScrollY); + } + activityMetricsState.lastScrollX = x; + activityMetricsState.lastScrollY = y; + } } /* @@ -555,24 +621,35 @@ export function Tracker( } /* - * Check the max scroll levels, updating as necessary + * Whether activity metrics tracking is enabled for any active configuration */ - function updateMaxScrolls() { - const offsets = getPageOffsets(); + function isActivityMetricsEnabled(): boolean { + return !!( + activityTrackingConfig.configurations.pagePing?.activityMetrics || + activityTrackingConfig.configurations.callback?.activityMetrics + ); + } - const x = offsets[0]; - if (x < minXOffset) { - minXOffset = x; - } else if (x > maxXOffset) { - maxXOffset = x; - } + /* + * Reset activity metrics accumulators and position trackers + */ + function resetActivityMetricsState() { + activityMetricsState.metrics = { mouseDistance: 0, scrollDistance: 0, keyPresses: 0, clicks: 0, touches: 0 }; + activityMetricsState.lastMouseX = undefined; + activityMetricsState.lastMouseY = undefined; + activityMetricsState.lastScrollX = undefined; + activityMetricsState.lastScrollY = undefined; + } - const y = offsets[1]; - if (y < minYOffset) { - minYOffset = y; - } else if (y > maxYOffset) { - maxYOffset = y; - } + /* + * Return a snapshot of current activity metrics + */ + function getActivityMetrics(): ActivityMetrics { + return { + ...activityMetricsState.metrics, + mouseDistance: Math.round(activityMetricsState.metrics.mouseDistance), + scrollDistance: Math.round(activityMetricsState.metrics.scrollDistance), + }; } /* @@ -1098,6 +1175,7 @@ export function Tracker( // Capture our initial scroll points resetMaxScrolls(); + resetActivityMetricsState(); // Add event handlers; cross-browser compatibility here varies significantly // @see http://quirksmode.org/dom/events @@ -1126,6 +1204,7 @@ export function Tracker( if (activityTrackingConfig.enabled && (resetActivityTrackingOnPageView || installingActivityTracking)) { // Periodic check for activity. lastActivityTime = now.getTime(); + resetActivityMetricsState(); let key: keyof ActivityConfigurations; for (key in activityTrackingConfig.configurations) { @@ -1147,8 +1226,16 @@ export function Tracker( ) { const executePagePing = (cb: ActivityCallback, context: Array) => { refreshUrl(); - cb({ context, pageViewId: getPageViewId(), minXOffset, minYOffset, maxXOffset, maxYOffset }); + let activityMetrics: ActivityMetrics | undefined; + if (isActivityMetricsEnabled()) { + activityMetrics = getActivityMetrics(); + context = context.concat([{ schema: ACTIVITY_METRICS_SCHEMA, data: activityMetrics }]); + } + cb({ context, pageViewId: getPageViewId(), minXOffset, minYOffset, maxXOffset, maxYOffset, activityMetrics }); resetMaxScrolls(); + if (isActivityMetricsEnabled()) { + resetActivityMetricsState(); + } }; const timeout = () => { @@ -1192,6 +1279,7 @@ export function Tracker( configMinimumVisitLength: minimumVisitLength * 1000, configHeartBeatTimer: heartbeatDelay * 1000, callback, + activityMetrics: configuration.activityMetrics, }; } @@ -1232,6 +1320,10 @@ export function Tracker( } activityTrackingConfig.configurations[actionKey] = undefined; + + if (!activityTrackingConfig.configurations.pagePing && !activityTrackingConfig.configurations.callback) { + resetActivityMetricsState(); + } } const apiMethods = { diff --git a/libraries/browser-tracker-core/src/tracker/schemata.ts b/libraries/browser-tracker-core/src/tracker/schemata.ts index 9c2ffd85e..2d6019f42 100644 --- a/libraries/browser-tracker-core/src/tracker/schemata.ts +++ b/libraries/browser-tracker-core/src/tracker/schemata.ts @@ -2,3 +2,4 @@ export const WEB_PAGE_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/web_page/jso export const BROWSER_CONTEXT_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/browser_context/jsonschema/2-0-0'; export const CLIENT_SESSION_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/client_session/jsonschema/1-0-2'; export const APPLICATION_CONTEXT_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/application/jsonschema/1-0-0'; +export const ACTIVITY_METRICS_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/activity_metrics/jsonschema/1-0-0'; diff --git a/libraries/browser-tracker-core/src/tracker/types.ts b/libraries/browser-tracker-core/src/tracker/types.ts index 6ebf47660..24f83030d 100755 --- a/libraries/browser-tracker-core/src/tracker/types.ts +++ b/libraries/browser-tracker-core/src/tracker/types.ts @@ -227,11 +227,30 @@ export type ActivityCallbackData = { maxXOffset: number; /** The maximum Y scroll position for the current page view */ maxYOffset: number; + /** Activity metrics accumulated since the last ping (only when activityMetrics is enabled) */ + activityMetrics?: ActivityMetrics; }; /** The callback for enableActivityTrackingCallback */ export type ActivityCallback = (data: ActivityCallbackData) => void; +/** + * Quantitative activity metrics accumulated between page pings. + * Attached as a context entity when activityMetrics is enabled. + */ +export type ActivityMetrics = { + /** Cumulative Euclidean mouse distance in pixels from mousemove events */ + mouseDistance: number; + /** Cumulative |deltaX|+|deltaY| scroll distance in pixels */ + scrollDistance: number; + /** Count of keydown events */ + keyPresses: number; + /** Count of click events */ + clicks: number; + /** Count of touchstart events */ + touches: number; +}; + /** * The base configuration for activity tracking */ @@ -240,6 +259,8 @@ export interface ActivityTrackingConfiguration { minimumVisitLength: number; /** The interval at which the callback will be fired */ heartbeatDelay: number; + /** Enable activity metrics to attach an activity_metrics entity to each page ping */ + activityMetrics?: boolean; } /** diff --git a/libraries/browser-tracker-core/test/tracker/activity_metrics.test.ts b/libraries/browser-tracker-core/test/tracker/activity_metrics.test.ts new file mode 100644 index 000000000..ccf3beb36 --- /dev/null +++ b/libraries/browser-tracker-core/test/tracker/activity_metrics.test.ts @@ -0,0 +1,335 @@ +import { createTracker } from '../helpers'; +import { Payload } from '@snowplow/tracker-core'; +import { ActivityCallbackData } from '../../src'; + +jest.useFakeTimers(); + +describe('Activity metrics', () => { + const ACTIVITY_METRICS_SCHEMA = 'iglu:com.snowplowanalytics.snowplow/activity_metrics/jsonschema/1-0-0'; + + beforeAll(() => { + jest.spyOn(document, 'title', 'get').mockReturnValue('Test Page'); + }); + + afterEach(() => { + jest.clearAllTimers(); + }); + + afterAll(() => { + jest.restoreAllMocks(); + }); + + function getTrackedPayloads() { + const payloads: Payload[] = []; + const tracker = createTracker({ + plugins: [ + { + afterTrack: (payload) => { + payloads.push(payload); + }, + }, + ], + }); + return { tracker: tracker!, payloads }; + } + + function getPagePings(payloads: Payload[]) { + return payloads.filter((p) => p.e === 'pp'); + } + + function getContextEntities(payload: Payload): Array<{ schema: string; data: unknown }> { + const co = payload.co as string | undefined; + if (!co) return []; + return JSON.parse(co).data ?? []; + } + + /** + * The heartbeat check is `lastActivityTime + configHeartBeatTimer > now`. + * Activity must happen strictly within the heartbeat window (not at its start). + * We advance 1s, dispatch events (so lastActivityTime is now+1s), then advance the rest. + */ + function simulateActivityInWindow(events: Event[], heartbeatMs: number) { + jest.advanceTimersByTime(1000); + events.forEach((e) => document.dispatchEvent(e)); + jest.advanceTimersByTime(heartbeatMs - 1000); + } + + it('accumulates metrics from simulated DOM events', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + }); + tracker.trackPageView(); + + simulateActivityInWindow( + [ + new MouseEvent('mousemove', { clientX: 0, clientY: 0 }), + new MouseEvent('mousemove', { clientX: 3, clientY: 4 }), + new MouseEvent('click'), + new MouseEvent('click'), + new KeyboardEvent('keydown'), + new KeyboardEvent('keydown'), + new KeyboardEvent('keydown'), + new Event('touchstart'), + ], + 10_000 + ); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(1); + + const entities = getContextEntities(pings[0]); + const metricsEntity = entities.find((e) => e.schema === ACTIVITY_METRICS_SCHEMA); + expect(metricsEntity).toBeDefined(); + + const data = metricsEntity!.data as Record; + expect(data.mouseDistance).toBe(5); // sqrt(9+16)=5 + expect(data.clicks).toBe(2); + expect(data.keyPresses).toBe(3); + expect(data.touches).toBe(1); + }); + + it('resets metrics after each ping', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + }); + tracker.trackPageView(); + + // First heartbeat + simulateActivityInWindow([new MouseEvent('click'), new MouseEvent('click')], 10_000); + + // Second heartbeat + simulateActivityInWindow([new MouseEvent('click')], 10_000); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(2); + + const data1 = getContextEntities(pings[0]).find((e) => e.schema === ACTIVITY_METRICS_SCHEMA)!.data as Record< + string, + number + >; + const data2 = getContextEntities(pings[1]).find((e) => e.schema === ACTIVITY_METRICS_SCHEMA)!.data as Record< + string, + number + >; + + expect(data1.clicks).toBe(2); + expect(data2.clicks).toBe(1); + }); + + it('does not attach entity when activityMetrics is not set', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + }); + tracker.trackPageView(); + + simulateActivityInWindow([new MouseEvent('click')], 10_000); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(1); + + const entities = getContextEntities(pings[0]); + const metricsEntity = entities.find((e) => e.schema === ACTIVITY_METRICS_SCHEMA); + expect(metricsEntity).toBeUndefined(); + }); + + it('calculates mouse distance as Euclidean sum', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + }); + tracker.trackPageView(); + + // Move from (0,0) to (3,4) then to (3,14) + simulateActivityInWindow( + [ + new MouseEvent('mousemove', { clientX: 0, clientY: 0 }), + new MouseEvent('mousemove', { clientX: 3, clientY: 4 }), // distance 5 + new MouseEvent('mousemove', { clientX: 3, clientY: 14 }), // distance 10 + ], + 10_000 + ); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(1); + + const data = getContextEntities(pings[0]).find((e) => e.schema === ACTIVITY_METRICS_SCHEMA)!.data as Record< + string, + number + >; + expect(data.mouseDistance).toBe(15); // 5 + 10 + }); + + it('populates activityMetrics in callback data', () => { + let callbackData: ActivityCallbackData | undefined; + const tracker = createTracker({ + plugins: [{ afterTrack: () => {} }], + }); + + tracker!.enableActivityTrackingCallback({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + callback: (data) => { + callbackData = data; + }, + }); + tracker!.trackPageView(); + + simulateActivityInWindow([new MouseEvent('click'), new MouseEvent('click')], 10_000); + + expect(callbackData).toBeDefined(); + expect(callbackData!.activityMetrics).toBeDefined(); + expect(callbackData!.activityMetrics!.clicks).toBe(2); + }); + + it('resets metrics on new trackPageView', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + }); + tracker.trackPageView(); + + // Accumulate some clicks (advance a bit so they register in heartbeat) + jest.advanceTimersByTime(1000); + document.dispatchEvent(new MouseEvent('click')); + document.dispatchEvent(new MouseEvent('click')); + + // New page view resets metrics and restarts intervals + tracker.trackPageView(); + + // Only one new click after the new page view + simulateActivityInWindow([new MouseEvent('click')], 10_000); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(1); + + const data = getContextEntities(pings[0]).find((e) => e.schema === ACTIVITY_METRICS_SCHEMA)!.data as Record< + string, + number + >; + expect(data.clicks).toBe(1); + }); + + it('first mousemove sets position but does not add distance', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + }); + tracker.trackPageView(); + + // Only one mousemove — should set position but not add distance + simulateActivityInWindow([new MouseEvent('mousemove', { clientX: 100, clientY: 200 })], 10_000); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(1); + + const data = getContextEntities(pings[0]).find((e) => e.schema === ACTIVITY_METRICS_SCHEMA)!.data as Record< + string, + number + >; + expect(data.mouseDistance).toBe(0); + }); + + it('updatePageActivity does not fabricate metrics', () => { + const { tracker, payloads } = getTrackedPayloads(); + tracker.enableActivityTracking({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + }); + tracker.trackPageView(); + + // updatePageActivity without a real event — advance partially so heartbeat detects it + jest.advanceTimersByTime(1000); + tracker.updatePageActivity(); + jest.advanceTimersByTime(9000); + + const pings = getPagePings(payloads); + expect(pings.length).toBe(1); + + const data = getContextEntities(pings[0]).find((e) => e.schema === ACTIVITY_METRICS_SCHEMA)!.data as Record< + string, + number + >; + expect(data.mouseDistance).toBe(0); + expect(data.clicks).toBe(0); + expect(data.keyPresses).toBe(0); + expect(data.touches).toBe(0); + expect(data.scrollDistance).toBe(0); + }); + + it('attaches activity_metrics entity to callback context when using activityMetrics', () => { + let callbackData: ActivityCallbackData | undefined; + const tracker = createTracker({ + plugins: [{ afterTrack: () => {} }], + }); + + tracker!.enableActivityTrackingCallback({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + callback: (data) => { + callbackData = data; + }, + }); + tracker!.trackPageView(); + + jest.advanceTimersByTime(1000); + document.dispatchEvent(new MouseEvent('click')); + document.dispatchEvent(new MouseEvent('click')); + jest.advanceTimersByTime(9000); + + expect(callbackData).toBeDefined(); + const metricsEntity = callbackData!.context.find( + (e) => e.schema === ACTIVITY_METRICS_SCHEMA + ); + expect(metricsEntity).toBeDefined(); + expect((metricsEntity!.data as Record).clicks).toBe(2); + }); + + it('does not overcount mouse distance across ping windows', () => { + let callbackData: ActivityCallbackData[] = []; + const tracker = createTracker({ + plugins: [{ afterTrack: () => {} }], + }); + + tracker!.enableActivityTrackingCallback({ + minimumVisitLength: 0, + heartbeatDelay: 10, + activityMetrics: true, + callback: (data) => { + callbackData.push(data); + }, + }); + tracker!.trackPageView(); + + // First window: move from 0 to 10 + jest.advanceTimersByTime(1000); + document.dispatchEvent(new MouseEvent('mousemove', { clientX: 0, clientY: 0 })); + document.dispatchEvent(new MouseEvent('mousemove', { clientX: 10, clientY: 0 })); + jest.advanceTimersByTime(9000); + + // Second window: single move to 20 — after position reset, this sets baseline only + jest.advanceTimersByTime(1000); + document.dispatchEvent(new MouseEvent('mousemove', { clientX: 20, clientY: 0 })); + jest.advanceTimersByTime(9000); + + expect(callbackData.length).toBe(2); + expect(callbackData[0].activityMetrics!.mouseDistance).toBe(10); + expect(callbackData[1].activityMetrics!.mouseDistance).toBe(0); + }); +}); diff --git a/trackers/browser-tracker/src/api.ts b/trackers/browser-tracker/src/api.ts index 4a69c3687..503a24d90 100644 --- a/trackers/browser-tracker/src/api.ts +++ b/trackers/browser-tracker/src/api.ts @@ -34,6 +34,7 @@ import { ActivityTrackingConfigurationCallback, ActivityCallback, ActivityCallbackData, + ActivityMetrics, BrowserPlugin, BrowserPluginConfiguration, BuiltInContexts, @@ -69,6 +70,7 @@ export { ActivityTrackingConfigurationCallback, ActivityCallback, ActivityCallbackData, + ActivityMetrics, BrowserPlugin, BrowserPluginConfiguration, BuiltInContexts,