feat: support sending events in background (#10)

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

Author: zhu-xiaowei

README.md

@@ -15,7 +15,7 @@ npm install @aws/clickstream-web
 ```
 
 ### Initialize the SDK
-You need to configure the SDK with default information before using it. Copy your configuration code from your clickstream solution control plane, the configuration code should look like as follows. You can also manually add this code snippet and replace the values of appId and endpoint after you registered app to a data pipeline in the Clickstream Analytics solution console.
+Copy your configuration code from your clickstream solution web console, we recommended you add the code to your app's root entry point, for example `index.js/app.tsx` in React or `main.ts` in Vue/Angular, the configuration code should look like as follows. You can also manually add this code snippet and replace the values of appId and endpoint after you registered app to a data pipeline in the Clickstream Analytics solution console.
 
 ```typescript
 import { ClickstreamAnalytics } from '@aws/clickstream-web';
@@ -87,6 +87,20 @@ ClickstreamAnalytics.record({
 });
 ```
 
+#### Send event immediate in batch mode
+
+When you are in batch mode, you can still send an event immediately by setting the `isImmediate` attribute, as in the following code:
+
+```typescript
+import { ClickstreamAnalytics } from '@aws/clickstream-web';
+
+ClickstreamAnalytics.record({
+  name: 'immediateEvent',
+  attributes: { url: 'https://example.com' },
+  isImmediate: true,
+});
+```
+
 #### Other configurations
 In addition to the required `appId` and `endpoint`, you can configure other information to get more customized usage:
 

package-lock.json

@@ -61,6 +61,14 @@ export class BrowserInfo {
 		);
 	}
 
+	static isFirefox(): boolean {
+		return navigator.userAgent.toLowerCase().indexOf('firefox') > -1;
+	}
+
+	static isNetworkOnLine(): boolean {
+		return navigator.onLine;
+	}
+
 	static getCurrentPageUrl(): string {
 		if (!BrowserInfo.isBrowser()) return '';
 		else return window.location.href;

src/browser/BrowserInfo.ts

@@ -20,6 +20,7 @@ export class NetRequest {
 	static readonly BATCH_REQUEST_TIMEOUT = 15000;
 	static readonly REQUEST_RETRY_TIMES = 3;
 	static readonly BATCH_REQUEST_RETRY_TIMES = 1;
+	static readonly KEEP_ALIVE_SIZE_LIMIT = 64 * 1024;
 
 	static async sendRequest(
 		eventsJson: string,
@@ -40,7 +41,8 @@ export class NetRequest {
 		const timeoutId = setTimeout(() => {
 			controller.abort();
 		}, timeout);
-
+		const inputSizeInBytes = new Blob([eventsJson]).size;
+		const isKeepAlive = inputSizeInBytes < NetRequest.KEEP_ALIVE_SIZE_LIMIT;
 		const requestOptions: RequestInit = {
 			method: 'POST',
 			mode: 'cors',
@@ -50,6 +52,7 @@ export class NetRequest {
 				'User-Agent': browserInfo.userAgent,
 			},
 			body: eventsJson,
+			keepalive: isKeepAlive,
 		};
 		requestOptions.signal = controller.signal;
 

src/network/NetRequest.ts

@@ -78,7 +78,7 @@ export class AnalyticsEventBuilder {
 			sdk_version: sdkVersion,
 			items: items,
 			user: userAttributes ?? {},
-			attributes: attributes ?? {},
+			attributes: attributes,
 		};
 		analyticEvent.hashCode = await HashUtil.getHashCode(
 			JSON.stringify(analyticEvent)

src/provider/AnalyticsEventBuilder.ts

@@ -93,7 +93,10 @@ export class ClickstreamProvider implements AnalyticsProvider {
 			'Initialize the SDK successfully, configuration is:\n' +
 				JSON.stringify(this.configuration)
 		);
-		this.eventRecorder.sendFailedEvents();
+		if (this.eventRecorder.getFailedEventsLength() > 0) {
+			this.eventRecorder.haveFailedEvents = true;
+			this.eventRecorder.sendFailedEvents();
+		}
 		return this.configuration;
 	}
 
@@ -121,8 +124,8 @@ export class ClickstreamProvider implements AnalyticsProvider {
 			this.userAttribute,
 			this.sessionTracker.session
 		)
-			.then(event => {
-				this.eventRecorder.record(event);
+			.then(resultEvent => {
+				this.eventRecorder.record(resultEvent, event.isImmediate);
 			})
 			.catch(error => {
 				logger.error(`Create event fail with ${error}`);
@@ -191,4 +194,13 @@ export class ClickstreamProvider implements AnalyticsProvider {
 	flushEvents(eventRecorder: EventRecorder) {
 		eventRecorder.flushEvents();
 	}
+
+	sendEventsInBackground(isWindowClosing: boolean) {
+		if (
+			!(BrowserInfo.isFirefox() && isWindowClosing) &&
+			BrowserInfo.isNetworkOnLine()
+		) {
+			this.eventRecorder.sendEventsInBackground(isWindowClosing);
+		}
+	}
 }

src/provider/ClickstreamProvider.ts

@@ -24,28 +24,29 @@ export class EventRecorder {
 	context: ClickstreamContext;
 	bundleSequenceId: number;
 	isFlushingEvents: boolean;
+	isSendingFailedEvents: boolean;
+	haveFailedEvents: boolean;
 
 	constructor(context: ClickstreamContext) {
 		this.context = context;
 		this.bundleSequenceId = StorageUtil.getBundleSequenceId();
 	}
 
-	record(event: AnalyticsEvent) {
+	record(event: AnalyticsEvent, isImmediate = false) {
 		if (this.context.configuration.isLogEvents) {
 			logger.level = LOG_TYPE.DEBUG;
 			logger.debug(
 				`Logged event ${event.event_type}, event attributes:\n
 				${JSON.stringify(event)}`
 			);
 		}
-		switch (this.context.configuration.sendMode) {
-			case SendMode.Immediate:
+		const currentMode = this.context.configuration.sendMode;
+		if (currentMode === SendMode.Immediate || isImmediate) {
+			this.sendEventImmediate(event);
+		} else {
+			if (!StorageUtil.saveEvent(event)) {
 				this.sendEventImmediate(event);
-				break;
-			case SendMode.Batch:
-				if (!StorageUtil.saveEvent(event)) {
-					this.sendEventImmediate(event);
-				}
+			}
 		}
 	}
 
@@ -58,14 +59,20 @@ export class EventRecorder {
 		).then(result => {
 			if (result) {
 				logger.debug('Event send success');
+				if (this.haveFailedEvents) {
+					this.sendFailedEvents();
+				}
 			} else {
 				StorageUtil.saveFailedEvent(event);
+				this.haveFailedEvents = true;
 			}
 		});
 		this.plusSequenceId();
 	}
 
 	sendFailedEvents() {
+		if (this.isSendingFailedEvents) return;
+		this.isSendingFailedEvents = true;
 		const failedEvents = StorageUtil.getFailedEvents();
 		if (failedEvents.length > 0) {
 			const eventsJson = failedEvents + Event.Constants.SUFFIX;
@@ -77,7 +84,9 @@ export class EventRecorder {
 				if (result) {
 					logger.debug('Failed events send success');
 					StorageUtil.clearFailedEvents();
+					this.haveFailedEvents = false;
 				}
+				this.isSendingFailedEvents = false;
 			});
 			this.plusSequenceId();
 		}
@@ -103,7 +112,7 @@ export class EventRecorder {
 				StorageUtil.clearEvents(eventsJson);
 			}
 			this.isFlushingEvents = false;
-			if (needsFlushTwice) {
+			if (result && needsFlushTwice) {
 				this.flushEvents();
 			}
 		});
@@ -147,4 +156,35 @@ export class EventRecorder {
 		this.bundleSequenceId += 1;
 		StorageUtil.saveBundleSequenceId(this.bundleSequenceId);
 	}
+
+	sendEventsInBackground(isWindowClosing: boolean) {
+		if (
+			this.haveFailedEvents &&
+			this.getFailedEventsLength() < NetRequest.KEEP_ALIVE_SIZE_LIMIT
+		) {
+			this.sendFailedEvents();
+			if (isWindowClosing) {
+				StorageUtil.clearFailedEvents();
+			}
+		}
+		if (this.context.configuration.sendMode === SendMode.Batch) {
+			const eventLength = this.getEventsLength();
+			if (eventLength > 0 && eventLength < NetRequest.KEEP_ALIVE_SIZE_LIMIT) {
+				this.flushEvents();
+				if (isWindowClosing) {
+					StorageUtil.clearAllEvents();
+				}
+			}
+		}
+	}
+
+	getFailedEventsLength(): number {
+		const failedEvents = StorageUtil.getFailedEvents();
+		return new Blob([failedEvents]).size;
+	}
+
+	getEventsLength(): number {
+		const events = StorageUtil.getAllEvents();
+		return new Blob([events]).size;
+	}
 }

src/provider/EventRecorder.ts

@@ -13,6 +13,7 @@
 import { Logger } from '@aws-amplify/core';
 import { BaseTracker } from './BaseTracker';
 import { Session } from './Session';
+import { BrowserInfo } from '../browser';
 import { Event } from '../provider';
 import { StorageUtil } from '../util/StorageUtil';
 
@@ -23,6 +24,7 @@ export class SessionTracker extends BaseTracker {
 	visibilityChange: string;
 	session: Session;
 	startEngageTimestamp: number;
+	isWindowClosing = false;
 
 	init() {
 		this.onVisibilityChange = this.onVisibilityChange.bind(this);
@@ -77,24 +79,28 @@ export class SessionTracker extends BaseTracker {
 	onPageHide() {
 		logger.debug('page hide');
 		this.storeSession();
-		this.recordUserEngagement();
+		this.recordUserEngagement(
+			!(this.isWindowClosing && BrowserInfo.isFirefox())
+		);
+		this.provider.sendEventsInBackground(this.isWindowClosing);
 	}
 
-	recordUserEngagement() {
+	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,
 			});
 		}
 	}
 
 	onBeforeUnload() {
 		logger.debug('onBeforeUnload');
-		this.onPageHide();
+		this.isWindowClosing = true;
 	}
 
 	storeSession() {

src/tracker/SessionTracker.ts

@@ -76,6 +76,7 @@ export interface ClickstreamEvent {
 	name: string;
 	attributes?: ClickstreamAttribute;
 	items?: Item[];
+	isImmediate?: boolean;
 }
 
 export interface AnalyticsEvent {

src/types/Analytics.ts

@@ -204,6 +204,8 @@ export class StorageUtil {
 	}
 
 	static clearEvents(eventsJson: string) {
+		const eventsString = this.getAllEvents();
+		if (eventsString === '') return;
 		const deletedEvents = JSON.parse(eventsJson);
 		const allEvents = JSON.parse(this.getAllEvents() + Event.Constants.SUFFIX);
 		if (allEvents.length > deletedEvents.length) {
@@ -216,6 +218,10 @@ export class StorageUtil {
 		}
 	}
 
+	static clearAllEvents() {
+		localStorage.removeItem(StorageUtil.eventsKey);
+	}
+
 	static saveSession(session: Session) {
 		localStorage.setItem(StorageUtil.sessionKey, JSON.stringify(session));
 	}