fix: change user engagement event and engagement time calculate rule (#13)

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

Author: zhu-xiaowei

README.md

@@ -113,6 +113,7 @@ ClickstreamAnalytics.configure({
    sendMode: EventMode.Batch,
    sendEventsInterval: 5000,
    isTrackPageViewEvents: true,
+   isTrackUserEngagementEvents: true,
    isTrackClickEvents: true,
    isTrackSearchEvents: true,
    isTrackScrollEvents: true,
@@ -132,6 +133,7 @@ Here is an explanation of each property:
 - **sendMode**: EventMode.Immediate, EventMode.Batch, default is Immediate mode.
 - **sendEventsInterval**: event sending interval millisecond, works only bath send mode, the default value is `5000`
 - **isTrackPageViewEvents**: whether auto record page view events in browser, default is `true`
+- **isTrackUserEngagementEvents**: whether auto record user engagement events in browser, default is `true`
 - **isTrackClickEvents**: whether auto record link click events in browser, default is `true`
 - **isTrackSearchEvents**: whether auto record search result page events in browser, default is `true`
 - **isTrackScrollEvents**: whether auto record page scroll events in browser, default is `true`
@@ -152,6 +154,7 @@ ClickstreamAnalytics.updateConfigure({
   isLogEvents: true,
   authCookie: 'your auth cookie',
   isTrackPageViewEvents: false,
+  isTrackUserEngagementEvents: false,
   isTrackClickEvents: false,
   isTrackScrollEvents: false,
   isTrackSearchEvents: false,

src/provider/AnalyticsEventBuilder.ts

@@ -24,18 +24,17 @@ import {
 	Item,
 	UserAttribute,
 } from '../types';
-import { HashUtil } from '../util/HashUtil';
 import { StorageUtil } from '../util/StorageUtil';
 
 const sdkVersion = config.sdkVersion;
 
 export class AnalyticsEventBuilder {
-	static async createEvent(
+	static createEvent(
 		context: ClickstreamContext,
 		event: ClickstreamEvent,
 		userAttributes: UserAttribute,
 		session?: Session
-	): Promise<AnalyticsEvent> {
+	): AnalyticsEvent {
 		const { browserInfo, configuration } = context;
 		const attributes = this.getEventAttributesWithCheck(event.attributes);
 		if (session !== undefined) {
@@ -56,8 +55,7 @@ export class AnalyticsEventBuilder {
 			browserInfo.latestReferrerHost;
 
 		const items = this.getEventItemsWithCheck(event.items, attributes);
-
-		const analyticEvent = {
+		return {
 			hashCode: '',
 			event_type: event.name,
 			event_id: uuidV4(),
@@ -80,10 +78,6 @@ export class AnalyticsEventBuilder {
 			user: userAttributes ?? {},
 			attributes: attributes,
 		};
-		analyticEvent.hashCode = await HashUtil.getHashCode(
-			JSON.stringify(analyticEvent)
-		);
-		return analyticEvent;
 	}
 
 	static getEventAttributesWithCheck(

src/provider/ClickstreamProvider.ts

@@ -22,6 +22,7 @@ import { PageViewTracker, SessionTracker } from '../tracker';
 import { ClickTracker } from '../tracker/ClickTracker';
 import { ScrollTracker } from '../tracker/ScrollTracker';
 import {
+	AnalyticsEvent,
 	AnalyticsProvider,
 	ClickstreamAttribute,
 	ClickstreamConfiguration,
@@ -31,6 +32,7 @@ import {
 	SendMode,
 	UserAttribute,
 } from '../types';
+import { HashUtil } from '../util/HashUtil';
 import { StorageUtil } from '../util/StorageUtil';
 
 const logger = new Logger('ClickstreamProvider');
@@ -52,6 +54,7 @@ export class ClickstreamProvider implements AnalyticsProvider {
 			sendMode: SendMode.Immediate,
 			sendEventsInterval: 5000,
 			isTrackPageViewEvents: true,
+			isTrackUserEngagementEvents: true,
 			isTrackClickEvents: true,
 			isTrackSearchEvents: true,
 			isTrackScrollEvents: true,
@@ -118,17 +121,27 @@ export class ClickstreamProvider implements AnalyticsProvider {
 			logger.error(result.error_message);
 			return;
 		}
-		AnalyticsEventBuilder.createEvent(
+		const resultEvent = this.createEvent(event);
+		this.recordEvent(resultEvent, event.isImmediate);
+	}
+
+	createEvent(event: ClickstreamEvent) {
+		return AnalyticsEventBuilder.createEvent(
 			this.context,
 			event,
 			this.userAttribute,
 			this.sessionTracker.session
-		)
-			.then(resultEvent => {
-				this.eventRecorder.record(resultEvent, event.isImmediate);
+		);
+	}
+
+	recordEvent(event: AnalyticsEvent, isImmediate = false) {
+		HashUtil.getHashCode(JSON.stringify(event))
+			.then(hashCode => {
+				event.hashCode = hashCode;
+				this.eventRecorder.record(event, isImmediate);
 			})
 			.catch(error => {
-				logger.error(`Create event fail with ${error}`);
+				logger.error(`Create hash code failed with ${error}`);
 			});
 	}
 

src/provider/Event.ts

@@ -53,6 +53,7 @@ export class Event {
 		PAGE_REFERRER_TITLE: '_page_referrer_title',
 		LATEST_REFERRER: '_latest_referrer',
 		LATEST_REFERRER_HOST: '_latest_referrer_host',
+		PREVIOUS_TIMESTAMP: '_previous_timestamp',
 		ENTRANCES: '_entrances',
 		SESSION_ID: '_session_id',
 		SESSION_DURATION: '_session_duration',

src/tracker/PageViewTracker.ts

@@ -26,26 +26,28 @@ export class PageViewTracker extends BaseTracker {
 	context: ClickstreamContext;
 	isEntrances = false;
 	searchKeywords = Event.Constants.KEYWORDS;
+	lastEngageTime = 0;
+	lastScreenStartTimestamp = 0;
 
 	init() {
 		const configuredSearchKeywords = this.provider.configuration.searchKeyWords;
 		Object.assign(this.searchKeywords, configuredSearchKeywords);
-		this.trackPageView = this.trackPageView.bind(this);
+		this.onPageChange = this.onPageChange.bind(this);
 		if (this.context.configuration.pageType === PageType.SPA) {
 			this.trackPageViewForSPA();
 		} else {
-			this.trackPageView();
+			this.onPageChange();
 		}
 	}
 
 	trackPageViewForSPA() {
-		MethodEmbed.add(history, 'pushState', this.trackPageView);
-		MethodEmbed.add(history, 'replaceState', this.trackPageView);
-		window.addEventListener('popstate', this.trackPageView);
-		this.trackPageView();
+		MethodEmbed.add(history, 'pushState', this.onPageChange);
+		MethodEmbed.add(history, 'replaceState', this.onPageChange);
+		window.addEventListener('popstate', this.onPageChange);
+		this.onPageChange();
 	}
 
-	trackPageView() {
+	onPageChange() {
 		if (!window.sessionStorage) {
 			logger.warn('unsupported web environment for sessionStorage');
 			return;
@@ -55,41 +57,81 @@ export class PageViewTracker extends BaseTracker {
 			const previousPageTitle = StorageUtil.getPreviousPageTitle();
 			const currentPageUrl = BrowserInfo.getCurrentPageUrl();
 			const currentPageTitle = BrowserInfo.getCurrentPageTitle();
-			const previousPageStartTime = StorageUtil.getPreviousPageStartTime();
-			let engagementTime = 0;
-			this.isEntrances =
-				this.provider.sessionTracker.session.isNewSession() &&
-				previousPageUrl === '';
-			const currentPageStartTime = new Date().getTime();
-			if (previousPageStartTime > 0) {
-				engagementTime = currentPageStartTime - previousPageStartTime;
-			}
-			if (previousPageUrl !== currentPageUrl) {
+			if (
+				previousPageUrl !== currentPageUrl ||
+				previousPageTitle !== currentPageTitle
+			) {
 				this.provider.scrollTracker?.enterNewPage();
-				const eventAttributes = {
-					[Event.ReservedAttribute.PAGE_REFERRER]: previousPageUrl,
-					[Event.ReservedAttribute.PAGE_REFERRER_TITLE]: previousPageTitle,
-					[Event.ReservedAttribute.ENTRANCES]: this.isEntrances ? 1 : 0,
-				};
-				if (!this.isEntrances) {
-					eventAttributes[Event.ReservedAttribute.ENGAGEMENT_TIMESTAMP] =
-						engagementTime;
-				}
-				this.provider.record({
-					name: Event.PresetEvent.PAGE_VIEW,
-					attributes: eventAttributes,
-				});
+				this.recordUserEngagement();
+				this.trackPageView(previousPageUrl, previousPageTitle);
+				this.trackSearchEvents();
+
 				StorageUtil.savePreviousPageUrl(currentPageUrl);
 				StorageUtil.savePreviousPageTitle(currentPageTitle);
-				StorageUtil.savePreviousPageStartTime(currentPageStartTime);
-				if (this.context.configuration.isTrackSearchEvents) {
-					this.trackSearchEvents();
-				}
 			}
 		}
 	}
 
+	trackPageView(previousPageUrl: string, previousPageTitle: string) {
+		const previousPageStartTime = StorageUtil.getPreviousPageStartTime();
+		const analyticsEvent = this.provider.createEvent({
+			name: Event.PresetEvent.PAGE_VIEW,
+		});
+		const currentPageStartTime = analyticsEvent.timestamp;
+
+		const eventAttributes = {
+			[Event.ReservedAttribute.PAGE_REFERRER]: previousPageUrl,
+			[Event.ReservedAttribute.PAGE_REFERRER_TITLE]: previousPageTitle,
+			[Event.ReservedAttribute.ENTRANCES]: this.isEntrances ? 1 : 0,
+		};
+		if (previousPageStartTime > 0) {
+			eventAttributes[Event.ReservedAttribute.PREVIOUS_TIMESTAMP] =
+				previousPageStartTime;
+		}
+		if (this.lastEngageTime > 0) {
+			eventAttributes[Event.ReservedAttribute.ENGAGEMENT_TIMESTAMP] =
+				this.lastEngageTime;
+		}
+		Object.assign(analyticsEvent.attributes, eventAttributes);
+		this.provider.recordEvent(analyticsEvent);
+
+		this.isEntrances = false;
+
+		StorageUtil.savePreviousPageStartTime(currentPageStartTime);
+		this.lastScreenStartTimestamp = currentPageStartTime;
+	}
+
+	setIsEntrances() {
+		this.isEntrances = true;
+	}
+
+	updateLastScreenStartTimestamp() {
+		this.lastScreenStartTimestamp = new Date().getTime();
+	}
+
+	recordUserEngagement(isImmediate = false) {
+		if (this.lastScreenStartTimestamp === 0) return;
+		this.lastEngageTime = this.getLastEngageTime();
+		if (
+			this.provider.configuration.isTrackUserEngagementEvents &&
+			this.lastEngageTime > Constants.minEngagementTime
+		) {
+			this.provider.record({
+				name: Event.PresetEvent.USER_ENGAGEMENT,
+				attributes: {
+					[Event.ReservedAttribute.ENGAGEMENT_TIMESTAMP]: this.lastEngageTime,
+				},
+				isImmediate: isImmediate,
+			});
+		}
+	}
+
+	getLastEngageTime() {
+		return new Date().getTime() - this.lastScreenStartTimestamp;
+	}
+
 	trackSearchEvents() {
+		if (!this.context.configuration.isTrackSearchEvents) return;
 		const searchStr = window.location.search;
 		if (!searchStr || searchStr.length === 0) return;
 		const urlParams = new URLSearchParams(searchStr);
@@ -108,3 +150,7 @@ export class PageViewTracker extends BaseTracker {
 		}
 	}
 }
+
+enum Constants {
+	minEngagementTime = 1000,
+}

src/tracker/SessionTracker.ts

@@ -23,7 +23,6 @@ export class SessionTracker extends BaseTracker {
 	hiddenStr: string;
 	visibilityChange: string;
 	session: Session;
-	startEngageTimestamp: number;
 	isWindowClosing = false;
 
 	init() {
@@ -63,9 +62,11 @@ export class SessionTracker extends BaseTracker {
 
 	onPageAppear(isFirstTime = false) {
 		logger.debug('page appear');
-		this.updateEngageTimestamp();
+		const pageViewTracker = this.provider.pageViewTracker;
+		pageViewTracker.updateLastScreenStartTimestamp();
 		this.session = Session.getCurrentSession(this.context);
 		if (this.session.isNewSession()) {
+			pageViewTracker.setIsEntrances();
 			this.provider.record({ name: Event.PresetEvent.SESSION_START });
 		}
 		this.provider.record({
@@ -86,16 +87,7 @@ export class SessionTracker extends BaseTracker {
 	}
 
 	recordUserEngagement(isImmediate = false) {
-		const engagementTime = new Date().getTime() - this.startEngageTimestamp;
-		if (engagementTime > Constants.minEngagementTime) {
-			this.provider.record({
-				name: Event.PresetEvent.USER_ENGAGEMENT,
-				attributes: {
-					[Event.ReservedAttribute.ENGAGEMENT_TIMESTAMP]: engagementTime,
-				},
-				isImmediate: isImmediate,
-			});
-		}
+		this.provider.pageViewTracker.recordUserEngagement(isImmediate);
 	}
 
 	onBeforeUnload() {
@@ -108,10 +100,6 @@ export class SessionTracker extends BaseTracker {
 		StorageUtil.saveSession(this.session);
 	}
 
-	updateEngageTimestamp() {
-		this.startEngageTimestamp = new Date().getTime();
-	}
-
 	checkEnv(): boolean {
 		if (!document || !document.addEventListener) {
 			logger.debug('not in the supported web environment');
@@ -133,7 +121,3 @@ export class SessionTracker extends BaseTracker {
 		return true;
 	}
 }
-
-enum Constants {
-	minEngagementTime = 1000,
-}

src/types/Analytics.ts

@@ -26,6 +26,7 @@ export interface Configuration {
 	isLogEvents?: boolean;
 	authCookie?: string;
 	isTrackPageViewEvents?: boolean;
+	isTrackUserEngagementEvents?: boolean;
 	isTrackClickEvents?: boolean;
 	isTrackScrollEvents?: boolean;
 	isTrackSearchEvents?: boolean;

src/util/StorageUtil.ts

@@ -259,7 +259,7 @@ export class StorageUtil {
 	}
 
 	static getPreviousPageStartTime(): number {
-		const startTime = sessionStorage.getItem(
+		const startTime = localStorage.getItem(
 			StorageUtil.previousPageStartTimeKey
 		);
 		if (startTime === null) {
@@ -270,7 +270,7 @@ export class StorageUtil {
 	}
 
 	static savePreviousPageStartTime(timestamp: number) {
-		sessionStorage.setItem(
+		localStorage.setItem(
 			StorageUtil.previousPageStartTimeKey,
 			timestamp.toString()
 		);