feat: Add time on site (#975)

package.json

@@ -87,7 +87,7 @@
         "@babel/preset-env": "^7.6.0",
         "@babel/preset-typescript": "^7.6.0",
         "@mparticle/data-planning-models": "^0.1.0",
-        "@mparticle/event-models": "^1.1.8",
+        "@mparticle/event-models": "^1.1.9",
         "@rollup/plugin-babel": "6.0.3",
         "@rollup/plugin-commonjs": "25.0.4",
         "@rollup/plugin-json": "^5.0.2",

src/foregroundTimeTracker.ts

@@ -0,0 +1,113 @@
+import { isNumber } from './utils';
+import { LocalStorageVault } from './vault';
+
+export default class ForegroundTimeTracker {
+    private isTrackerActive: boolean = false;
+    private localStorageName: string = '';
+    private timerVault: LocalStorageVault<number>;
+    public startTime: number = 0;
+    public totalTime: number = 0;
+
+    constructor(timerKey: string) {
+        this.localStorageName = `mp-time-${timerKey}`;
+        this.timerVault = new LocalStorageVault<number>(this.localStorageName);
+        this.loadTimeFromStorage();
+        this.addHandlers();
+        if (document.hidden === false) {
+            this.startTracking();
+        }
+    }
+
+    private addHandlers(): void {
+        // when user switches tabs or minimizes the window
+        document.addEventListener('visibilitychange', () =>
+            this.handleVisibilityChange()
+        );
+        // when user switches to another application
+        window.addEventListener('blur', () => this.handleWindowBlur());
+        // when window gains focus
+        window.addEventListener('focus', () => this.handleWindowFocus());
+        // this ensures that timers between tabs are in sync
+        window.addEventListener('storage', event => this.syncAcrossTabs(event));
+        // when user closes tab, refreshes, or navigates to another page via link
+        window.addEventListener('beforeunload', () =>
+            this.updateTimeInPersistence()
+        );
+    }
+
+    private handleVisibilityChange(): void {
+        if (document.hidden) {
+            this.stopTracking();
+        } else {
+            this.startTracking();
+        }
+    }
+
+    private handleWindowBlur(): void {
+        if (this.isTrackerActive) {
+            this.stopTracking();
+        }
+    }
+
+    private handleWindowFocus(): void {
+        if (!this.isTrackerActive) {
+            this.startTracking();
+        }
+    }
+
+    private syncAcrossTabs(event: StorageEvent): void {
+        if (event.key === this.localStorageName && event.newValue !== null) {
+            const newTime = parseFloat(event.newValue) || 0;
+            this.totalTime = newTime;
+        }
+    }
+
+    public updateTimeInPersistence(): void {
+        if (this.isTrackerActive) {
+            this.timerVault.store(Math.round(this.totalTime));
+        }
+    }
+
+    private loadTimeFromStorage(): void {
+        const storedTime = this.timerVault.retrieve();
+        if (isNumber(storedTime) && storedTime !== null) {
+            this.totalTime = storedTime;
+        }
+    }
+
+
+    private startTracking(): void {
+        if (!document.hidden) {
+            this.startTime = Math.floor(performance.now());
+            this.isTrackerActive = true;
+        }
+    }
+
+    private stopTracking(): void {
+        if (this.isTrackerActive) {
+            this.setTotalTime();
+            this.updateTimeInPersistence();
+            this.isTrackerActive = false;
+        }
+    }
+
+    private setTotalTime(): void {
+        if (this.isTrackerActive) {
+            const now = Math.floor(performance.now());
+            this.totalTime += now - this.startTime;
+            this.startTime = now;
+
+        }
+    }
+
+    public getTimeInForeground(): number {
+        this.setTotalTime();
+        this.updateTimeInPersistence();
+        return this.totalTime;
+    }
+
+    public resetTimer(): void {
+        this.totalTime = 0;
+        this.updateTimeInPersistence();
+    }
+}

src/mockBatchCreator.ts

@@ -30,6 +30,9 @@ export default class _BatchValidator {
             },
             _resetForTests: mockFunction,
             _APIClient: null,
+            _timeOnSiteTimer: {
+                getTimeInForeground: mockFunction
+            },
             MPSideloadedKit: null,
             _Consent: null,
             _Events: null,

src/mp-instance.ts

@@ -48,6 +48,7 @@ import { IEvents } from './events.interfaces';
 import { IECommerce } from './ecommerce.interfaces';
 import { INativeSdkHelpers } from './nativeSdkHelpers.interfaces';
 import { IPersistence } from './persistence.interfaces';
+import ForegroundTimer from './foregroundTimeTracker';
 
 export interface IErrorLogMessage {
     message?: string;
@@ -84,6 +85,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     _Store: IStore;
     _instanceName: string;
     _preInit: IPreInit;
+    _timeOnSiteTimer: ForegroundTimer; 
 }
 
 const { Messages, HTTPCodes, FeatureFlags } = Constants;

src/sdkRuntimeModels.ts

@@ -79,7 +79,9 @@ export interface SDKEvent {
     DataPlan?: SDKDataPlan;
     LaunchReferral?: string;
     ExpandedEventCount: number;
+    ActiveTimeOnSite: number;
 }
+
 export interface SDKGeoLocation {
     lat: number | string;
     lng: number | string;

src/sdkToEventsApiConverter.ts

@@ -658,6 +658,7 @@ export function convertBaseEventData(
         custom_attributes: sdkEvent.EventAttributes,
         location: convertSDKLocation(sdkEvent.Location),
         source_message_id: sdkEvent.SourceMessageId,
+        active_time_on_site_ms: sdkEvent.ActiveTimeOnSite
     };
 
     return commonEventData;

src/serverModel.ts

@@ -345,6 +345,7 @@ export default function ServerModel(
                         event.data,
                         event.name
                     ),
+                    ActiveTimeOnSite: mpInstance._timeOnSiteTimer?.getTimeInForeground(),
                     SourceMessageId:
                         event.sourceMessageId ||
                         mpInstance._Helpers.generateUniqueId(),

src/sessionManager.ts

@@ -132,17 +132,20 @@ export default function SessionManager(
             });
 
             mpInstance._Store.nullifySession();
+            mpInstance._timeOnSiteTimer?.resetTimer();
             return;
         }
 
         if (!mpInstance._Helpers.canLog()) {
-            // At this moment, an AbandonedEndSession is defined when on of three things occurs:
+            // At this moment, an AbandonedEndSession is defined when one of three things occurs:
             // - the SDK's store is not enabled because mParticle.setOptOut was called
             // - the devToken is undefined
             // - webviewBridgeEnabled is set to false
             mpInstance.Logger.verbose(
                 Messages.InformationMessages.AbandonEndSession
             );
+            mpInstance._timeOnSiteTimer?.resetTimer();
+
             return;
         }
 
@@ -155,6 +158,8 @@ export default function SessionManager(
             mpInstance.Logger.verbose(
                 Messages.InformationMessages.NoSessionToEnd
             );
+            mpInstance._timeOnSiteTimer?.resetTimer();
+
             return;
         }
 
@@ -180,6 +185,8 @@ export default function SessionManager(
                 mpInstance._Store.nullifySession();
             }
         }
+
+        mpInstance._timeOnSiteTimer?.resetTimer();
     };
 
     this.setSessionTimer = function(): void {

src/store.ts

@@ -38,6 +38,7 @@ import {
 } from './persistence.interfaces';
 import { CookieSyncDates, IPixelConfiguration } from './cookieSyncManager';
 import { IMParticleWebSDKInstance } from './mp-instance';
+import ForegroundTimer from './foregroundTimeTracker';
 
 // This represents the runtime configuration of the SDK AFTER
 // initialization has been complete and all settings and
@@ -680,6 +681,7 @@ export default function Store(
 
         if (workspaceToken) {
             this.SDKConfig.workspaceToken = workspaceToken;
+            mpInstance._timeOnSiteTimer = new ForegroundTimer(workspaceToken);
         } else {
             mpInstance.Logger.warning(
                 'You should have a workspaceToken on your config object for security purposes.'

test/fixtures/events.ts

@@ -20,6 +20,7 @@ export const event0: SDKEvent = {
     Debug: false,
     DeviceId: 'test-device',
     Timestamp: 0,
+    ActiveTimeOnSite: 10
 };
 
 export const event1: SDKEvent = {
@@ -42,6 +43,7 @@ export const event1: SDKEvent = {
     Debug: false,
     DeviceId: 'test-device',
     Timestamp: 0,
+    ActiveTimeOnSite: 20
 };
 
 export const event2: SDKEvent = {
@@ -64,6 +66,7 @@ export const event2: SDKEvent = {
     Debug: false,
     DeviceId: 'test-device',
     Timestamp: 0,
+    ActiveTimeOnSite: 30
 };
 
 export const event3: SDKEvent = {
@@ -86,4 +89,5 @@ export const event3: SDKEvent = {
     Debug: false,
     DeviceId: 'test-device',
     Timestamp: 0,
+    ActiveTimeOnSite: 40
 };