feat: exclude idle time in user engagement duration (#52)

Co-authored-by: xiaoweii <xiaoweii@amazom.com>

Author: zhu-xiaowei

README.md

@@ -176,6 +176,7 @@ ClickstreamAnalytics.init({
    isLogEvents: false,
    authCookie: "your auth cookie",
    sessionTimeoutDuration: 1800000,
+   idleTimeoutDuration: 120000,
    searchKeyWords: ['product', 'class'],
    domainList: ['example1.com', 'example2.com'],
 });
@@ -199,6 +200,7 @@ Here is an explanation of each property:
 - **isLogEvents**: whether to print out event json for debugging, default is false.
 - **authCookie**: your auth cookie for AWS application load balancer auth cookie.
 - **sessionTimeoutDuration**: the duration for session timeout millisecond, default is 1800000
+- **idleTimeoutDuration**: the maximum duration of user inactivity before triggering an idle state, default is 120000 millisecond, Any idle duration exceeding this threshold will be removed in the user_engagement events on the current page.
 - **searchKeyWords**: the customized Keywords for trigger the `_search` event, by default we detect `q`, `s`, `search`, `query` and `keyword` in query parameters.
 - **domainList**: if your website cross multiple domain, you can customize the domain list. The `_outbound` attribute of the `_click` event will be true when a link leads to a website that's not a part of your configured domain.  
 
@@ -218,7 +220,7 @@ ClickstreamAnalytics.updateConfigure({
   isTrackSearchEvents: false,
   isTrackPageLoadEvents: false,
   isTrackAppStartEvents: true,
-  isTrackAppStartEvents: true,
+  isTrackAppEndEvents: true,
 });
 ```
 

src/provider/ClickstreamProvider.ts

@@ -67,6 +67,7 @@ export class ClickstreamProvider implements AnalyticsProvider {
 			pageType: PageType.SPA,
 			isLogEvents: false,
 			sessionTimeoutDuration: 1800000,
+			idleTimeoutDuration: 120000,
 			searchKeyWords: [],
 			domainList: [],
 			globalAttributes: {},

src/tracker/ClickTracker.ts

@@ -13,6 +13,7 @@
 
 import { Logger } from '@aws-amplify/core';
 import { BaseTracker } from './BaseTracker';
+import { PageViewTracker } from './PageViewTracker';
 import { Event } from '../provider';
 
 const logger = new Logger('ClickTracker');
@@ -33,6 +34,7 @@ export class ClickTracker extends BaseTracker {
 	}
 
 	trackDocumentClick(event: MouseEvent) {
+		PageViewTracker.updateIdleDuration();
 		if (!this.context.configuration.isTrackClickEvents) return;
 		const targetElement = event.target as Element;
 		const element = this.findATag(targetElement);

src/tracker/PageViewTracker.ts

@@ -26,8 +26,14 @@ export class PageViewTracker extends BaseTracker {
 	lastEngageTime = 0;
 	lastScreenStartTimestamp = 0;
 	isFirstTime = true;
+	static lastActiveTimestamp = 0;
+	static idleDuration = 0;
+	private static idleTimeoutDuration = 0;
 
 	init() {
+		PageViewTracker.lastActiveTimestamp = new Date().getTime();
+		PageViewTracker.idleTimeoutDuration =
+			this.provider.configuration.idleTimeoutDuration;
 		const configuredSearchKeywords = this.provider.configuration.searchKeyWords;
 		Object.assign(this.searchKeywords, configuredSearchKeywords);
 		this.onPageChange = this.onPageChange.bind(this);
@@ -51,6 +57,7 @@ export class PageViewTracker extends BaseTracker {
 	}
 
 	onPageChange() {
+		PageViewTracker.updateIdleDuration();
 		if (this.context.configuration.isTrackPageViewEvents) {
 			const previousPageUrl = StorageUtil.getPreviousPageUrl();
 			const previousPageTitle = StorageUtil.getPreviousPageTitle();
@@ -114,6 +121,8 @@ export class PageViewTracker extends BaseTracker {
 
 	updateLastScreenStartTimestamp() {
 		this.lastScreenStartTimestamp = new Date().getTime();
+		PageViewTracker.idleDuration = 0;
+		PageViewTracker.lastActiveTimestamp = this.lastScreenStartTimestamp;
 	}
 
 	recordUserEngagement(isImmediate = false) {
@@ -133,7 +142,10 @@ export class PageViewTracker extends BaseTracker {
 	}
 
 	getLastEngageTime() {
-		return new Date().getTime() - this.lastScreenStartTimestamp;
+		const duration = new Date().getTime() - this.lastScreenStartTimestamp;
+		const engageTime = duration - PageViewTracker.idleDuration;
+		PageViewTracker.idleDuration = 0;
+		return engageTime;
 	}
 
 	isMultiPageApp() {
@@ -159,8 +171,17 @@ export class PageViewTracker extends BaseTracker {
 			}
 		}
 	}
+
+	static updateIdleDuration() {
+		const currentTimestamp = new Date().getTime();
+		const idleDuration = currentTimestamp - PageViewTracker.lastActiveTimestamp;
+		if (idleDuration > PageViewTracker.idleTimeoutDuration) {
+			PageViewTracker.idleDuration += idleDuration;
+		}
+		PageViewTracker.lastActiveTimestamp = currentTimestamp;
+	}
 }
 
-enum Constants {
+export enum Constants {
 	minEngagementTime = 1000,
 }

src/tracker/ScrollTracker.ts

@@ -12,6 +12,7 @@
  */
 
 import { BaseTracker } from './BaseTracker';
+import { PageViewTracker } from './PageViewTracker';
 import { Event } from '../provider';
 import { StorageUtil } from '../util/StorageUtil';
 
@@ -20,7 +21,14 @@ export class ScrollTracker extends BaseTracker {
 
 	init() {
 		this.trackScroll = this.trackScroll.bind(this);
-		document.addEventListener('scroll', this.trackScroll);
+		const throttledTrackScroll = this.throttle(this.trackScroll, 100);
+		document.addEventListener('scroll', throttledTrackScroll, {
+			passive: true,
+		});
+		const throttledMouseMove = this.throttle(this.onMouseMove, 100);
+		document.addEventListener('mousemove', throttledMouseMove, {
+			passive: true,
+		});
 		this.isFirstTime = true;
 	}
 
@@ -29,6 +37,7 @@ export class ScrollTracker extends BaseTracker {
 	}
 
 	trackScroll() {
+		PageViewTracker.updateIdleDuration();
 		if (!this.context.configuration.isTrackScrollEvents) return;
 		const scrollY = window.scrollY || document.documentElement.scrollTop;
 		const ninetyPercentHeight = document.body.scrollHeight * 0.9;
@@ -45,4 +54,20 @@ export class ScrollTracker extends BaseTracker {
 			this.isFirstTime = false;
 		}
 	}
+
+	onMouseMove() {
+		PageViewTracker.updateIdleDuration();
+	}
+
+	throttle(func: (...args: any[]) => void, delay: number) {
+		let timeout: ReturnType<typeof setTimeout> | null = null;
+		return function (this: any, ...args: any[]) {
+			if (!timeout) {
+				timeout = setTimeout(() => {
+					func.apply(this, args);
+					timeout = null;
+				}, delay);
+			}
+		};
+	}
 }

src/types/Analytics.ts

@@ -18,6 +18,7 @@ export interface ClickstreamConfiguration extends Configuration {
 	readonly sendEventsInterval?: number;
 	readonly pageType?: PageType;
 	readonly sessionTimeoutDuration?: number;
+	readonly idleTimeoutDuration?: number;
 	readonly searchKeyWords?: string[];
 	readonly domainList?: string[];
 	readonly globalAttributes?: ClickstreamAttribute;

test/tracker/PageViewTracker.test.ts

@@ -317,6 +317,18 @@ describe('PageViewTracker test', () => {
 		expect(recordMethodMock).toBeCalled();
 	});
 
+	test('test get engagement time with idle time', async () => {
+		pageViewTracker.lastScreenStartTimestamp = new Date().getTime();
+		(provider.configuration as any).idleTimeoutDuration = 100;
+		pageViewTracker.setUp();
+		await sleep(110);
+		PageViewTracker.updateIdleDuration();
+		await sleep(100);
+		expect(PageViewTracker.idleDuration > 0).toBeTruthy();
+		const lastEngageTime = pageViewTracker.getLastEngageTime();
+		expect(lastEngageTime < 150).toBeTruthy();
+	});
+
 	function openPageA() {
 		Object.defineProperty(window.document, 'title', {
 			writable: true,

test/tracker/ScrollTracker.test.ts

@@ -17,9 +17,9 @@ import {
 	ClickstreamProvider,
 	EventRecorder,
 } from '../../src/provider';
-import { Session, SessionTracker } from '../../src/tracker';
+import { Session, SessionTracker, PageViewTracker } from '../../src/tracker';
 import { ScrollTracker } from '../../src/tracker/ScrollTracker';
-import { StorageUtil } from "../../src/util/StorageUtil";
+import { StorageUtil } from '../../src/util/StorageUtil';
 
 describe('ScrollTracker test', () => {
 	let provider: ClickstreamProvider;
@@ -28,7 +28,7 @@ describe('ScrollTracker test', () => {
 	let recordMethodMock: any;
 
 	beforeEach(() => {
-		StorageUtil.clearAll()
+		StorageUtil.clearAll();
 		provider = new ClickstreamProvider();
 
 		Object.assign(provider.configuration, {
@@ -63,27 +63,29 @@ describe('ScrollTracker test', () => {
 		expect(scrollTracker.isFirstTime).toBeTruthy();
 	});
 
-	test('test scroll for not reach ninety percent', () => {
+	test('test scroll for not reach ninety percent', async () => {
 		const trackScrollMock = jest.spyOn(scrollTracker, 'trackScroll');
 		scrollTracker.setUp();
 		setScrollHeight(2000);
 		(window as any).innerHeight = 1000;
 		setScrollY(100);
 		window.document.dispatchEvent(new window.Event('scroll'));
+		await sleep(110);
 		expect(recordMethodMock).not.toBeCalled();
 		expect(trackScrollMock).toBeCalled();
 	});
 
-	test('test scroll for reached ninety percent', () => {
+	test('test scroll for reached ninety percent', async () => {
 		const trackScrollMock = jest.spyOn(scrollTracker, 'trackScroll');
 		scrollTracker.setUp();
-		performScrollToBottom();
+		await performScrollToBottom();
+		await sleep(110);
 		expect(recordMethodMock).toBeCalled();
 		expect(trackScrollMock).toBeCalled();
 		expect(scrollTracker.isFirstTime).toBeFalsy();
 	});
 
-	test('test window scroll for reached ninety percent using scrollTop api', () => {
+	test('test window scroll for reached ninety percent using scrollTop api', async () => {
 		const trackScrollMock = jest.spyOn(scrollTracker, 'trackScroll');
 		scrollTracker.setUp();
 		Object.defineProperty(window, 'scrollY', {
@@ -97,46 +99,59 @@ describe('ScrollTracker test', () => {
 			value: 150,
 		});
 		window.document.dispatchEvent(new window.Event('scroll'));
+		await sleep(110);
 		expect(trackScrollMock).toBeCalled();
 		expect(recordMethodMock).toBeCalled();
 	});
 
-	test('test scroll for reached ninety percent and scroll event is disabled', () => {
+	test('test scroll for reached ninety percent and scroll event is disabled', async () => {
 		const trackScrollMock = jest.spyOn(scrollTracker, 'trackScroll');
 		provider.configuration.isTrackScrollEvents = false;
 		scrollTracker.setUp();
-		performScrollToBottom();
+		await performScrollToBottom();
 		expect(trackScrollMock).toBeCalled();
 		expect(recordMethodMock).not.toBeCalled();
 	});
 
-	test('test scroll for reached ninety percent twice', () => {
+	test('test scroll for reached ninety percent twice', async () => {
 		const trackScrollMock = jest.spyOn(scrollTracker, 'trackScroll');
 		scrollTracker.setUp();
-		performScrollToBottom();
+		await performScrollToBottom();
 		window.document.dispatchEvent(new window.Event('scroll'));
+		await sleep(110);
 		expect(recordMethodMock).toBeCalledTimes(1);
 		expect(trackScrollMock).toBeCalledTimes(2);
 		expect(scrollTracker.isFirstTime).toBeFalsy();
 	});
 
-	test('test scroll for enter new page', () => {
+	test('test scroll for enter new page', async () => {
 		const trackScrollMock = jest.spyOn(scrollTracker, 'trackScroll');
 		scrollTracker.setUp();
-		performScrollToBottom();
+		await performScrollToBottom();
 		scrollTracker.enterNewPage();
 		expect(scrollTracker.isFirstTime).toBeTruthy();
 		window.document.dispatchEvent(new window.Event('scroll'));
+		await sleep(110);
 		expect(recordMethodMock).toBeCalledTimes(2);
 		expect(trackScrollMock).toBeCalledTimes(2);
 		expect(scrollTracker.isFirstTime).toBeFalsy();
 	});
 
-	function performScrollToBottom() {
+	test('test mouse move will update the idle duration', async () => {
+		const onMouseMoveMock = jest.spyOn(scrollTracker, 'onMouseMove');
+		scrollTracker.setUp();
+		window.document.dispatchEvent(new window.Event('mousemove'));
+		await sleep(110);
+		expect(onMouseMoveMock).toBeCalled();
+		expect(PageViewTracker.lastActiveTimestamp > 0).toBeTruthy();
+	});
+
+	async function performScrollToBottom() {
 		setScrollHeight(1000);
 		(window as any).innerHeight = 800;
 		setScrollY(150);
 		window.document.dispatchEvent(new window.Event('scroll'));
+		await sleep(110);
 	}
 
 	function setScrollHeight(height: number) {
@@ -152,4 +167,8 @@ describe('ScrollTracker test', () => {
 			value: height,
 		});
 	}
+
+	function sleep(ms: number): Promise<void> {
+		return new Promise(resolve => setTimeout(resolve, ms));
+	}
 });