@mparticle/web-sdk 2.75.1 → 2.77.0

package/dist/types/src/kitBlocking.d.ts

@@ -66,6 +66,7 @@ export default class KitBlocker {
         LaunchReferral?: string;
         ExpandedEventCount: number;
         ActiveTimeOnSite: number;
+        TotalTimeOnSite: number;
         PageUrl?: string;
         IsBackgroundAST?: boolean;
         AlreadySentToForwarders?: boolean;
@@ -111,6 +112,7 @@ export default class KitBlocker {
         LaunchReferral?: string;
         ExpandedEventCount: number;
         ActiveTimeOnSite: number;
+        TotalTimeOnSite: number;
         PageUrl?: string;
         IsBackgroundAST?: boolean;
         AlreadySentToForwarders?: boolean;

package/dist/types/src/mp-instance.d.ts

@@ -20,6 +20,7 @@ import RoktManager from './roktManager';
 import { ICookieConsentManager } from './cookieConsentManager';
 import { ErrorReportingDispatcher } from './reporting/errorReportingDispatcher';
 import { LoggingDispatcher } from './reporting/loggingDispatcher';
+import { PageViewTracker } from './pageViewTracker';
 export interface IErrorLogMessage {
     message?: string;
     name?: string;
@@ -44,6 +45,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     _IdentityAPIClient: typeof IdentityAPIClient;
     _IntegrationCapture: IntegrationCapture;
     _NativeSdkHelpers: INativeSdkHelpers;
+    _PageViewTracker?: PageViewTracker;
     _Persistence: IPersistence;
     _CookieConsentManager: ICookieConsentManager;
     _ErrorReportingDispatcher: ErrorReportingDispatcher;

package/dist/types/src/pageViewTracker.d.ts

@@ -0,0 +1,21 @@
+import { IMParticleWebSDKInstance } from './mp-instance';
+export declare class PageViewTracker {
+    mpInstance: IMParticleWebSDKInstance;
+    private lastPath;
+    private isActive;
+    private originalPushState;
+    private originalReplaceState;
+    private pushStateWrapper;
+    private replaceStateWrapper;
+    private popStateListener;
+    constructor(mpInstance: IMParticleWebSDKInstance);
+    private isSupportedEnvironment;
+    init(): void;
+    private patchHistoryMethods;
+    private addNavigationListeners;
+    private safeHandleNavigation;
+    private getCurrentKey;
+    private handleNavigation;
+    private firePageView;
+    teardown(): void;
+}

package/dist/types/src/sdkRuntimeModels.d.ts

@@ -60,6 +60,7 @@ export interface SDKEvent {
     LaunchReferral?: string;
     ExpandedEventCount: number;
     ActiveTimeOnSite: number;
+    TotalTimeOnSite: number;
     PageUrl?: string;
     IsBackgroundAST?: boolean;
     AlreadySentToForwarders?: boolean;

package/dist/types/src/store.d.ts

@@ -146,6 +146,7 @@ export interface IStore {
     getRoktAccountId?(): string;
     setRoktAccountId?(accountId: string): void;
     getTimeOnSite?(): number | undefined;
+    getTotalTimeOnSite?(): number | undefined;
     getIntegrationName?(): string;
     setIntegrationName?(integrationName: string): void;
     addMpidToSessionHistory?(mpid: MPID, previousMpid?: MPID): void;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "2.75.1",
+    "version": "2.77.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [
@@ -103,7 +103,7 @@
         "@babel/preset-env": "^7.6.0",
         "@babel/preset-typescript": "^7.6.0",
         "@mparticle/data-planning-models": "^0.1.0",
-        "@mparticle/event-models": "^1.3.0",
+        "@mparticle/event-models": "^1.3.1",
         "@rollup/plugin-babel": "6.0.3",
         "@rollup/plugin-commonjs": "25.0.4",
         "@rollup/plugin-json": "^5.0.2",
@@ -159,7 +159,7 @@
         "webpack-cli": "^5.0.2"
     },
     "peerDependencies": {
-        "@mparticle/event-models": "^1.3.0"
+        "@mparticle/event-models": "^1.3.1"
     },
     "dependencies": {
         "@babel/runtime": "^7.23.2"

package/src/batchUploader.ts

@@ -197,6 +197,7 @@ export class BatchUploader {
             SessionStartDate: sessionStartDate?.getTime() || now,
             Debug: SDKConfig.isDevelopmentMode,
             ActiveTimeOnSite: _timeOnSiteTimer?.getTimeInForeground() || 0,
+            TotalTimeOnSite: _Store.getTotalTimeOnSite?.() || 0,
             PageUrl: getHref() || null,
             IsBackgroundAST: true
         } as SDKEvent;

package/src/mockBatchCreator.ts

@@ -91,6 +91,7 @@ export default class _BatchValidator {
                     isDevelopmentMode: false,
                     onCreateBatch: mockFunction,
                 },
+                getTotalTimeOnSite: mockFunction,
             },
             config: null,
             eCommerce: null,

package/src/mp-instance.ts

@@ -57,6 +57,7 @@ import { LoggingDispatcher } from './reporting/loggingDispatcher';
 import { IErrorReportingService, ILoggingService } from './reporting/types';
 import { logDeprecatedMethodUsage } from './reporting/deprecatedMethodLogger';
 import { normalizeRoktLauncherOptions } from './roktLauncherOptions';
+import { PageViewTracker } from './pageViewTracker';
 
 export interface IErrorLogMessage {
     message?: string;
@@ -87,6 +88,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     _IdentityAPIClient: typeof IdentityAPIClient;
     _IntegrationCapture: IntegrationCapture;
     _NativeSdkHelpers: INativeSdkHelpers;
+    _PageViewTracker?: PageViewTracker;
     _Persistence: IPersistence;
     _CookieConsentManager: ICookieConsentManager;
     _ErrorReportingDispatcher: ErrorReportingDispatcher;
@@ -1585,6 +1587,13 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
 
         if (getFeatureFlag(AutoLogPageView)) {
             mpInstance._Events.logPageView();
+
+            if (!mpInstance._PageViewTracker) {
+                mpInstance._PageViewTracker = new PageViewTracker(mpInstance);
+            }
+            mpInstance._PageViewTracker.init();
+        } else if (mpInstance._PageViewTracker) {
+            mpInstance._PageViewTracker.teardown();
         }
 
         processIdentityCallback(

package/src/pageViewTracker.ts

@@ -0,0 +1,267 @@
+import { IMParticleWebSDKInstance } from './mp-instance';
+import { EventType, MessageType } from './types';
+
+type HistoryStateMethod = History['pushState'];
+
+const WRAPPED_MARKER = '__mpApvWrapped__';
+
+type MarkedHistoryMethod = HistoryStateMethod & {
+    [WRAPPED_MARKER]?: boolean;
+};
+
+export class PageViewTracker {
+    mpInstance: IMParticleWebSDKInstance;
+
+    private lastPath: string | null = null;
+    private isActive = false;
+
+    private originalPushState: HistoryStateMethod | null = null;
+    private originalReplaceState: HistoryStateMethod | null = null;
+
+    private pushStateWrapper: HistoryStateMethod | null = null;
+    private replaceStateWrapper: HistoryStateMethod | null = null;
+
+    private popStateListener: (() => void) | null = null;
+
+    constructor(mpInstance: IMParticleWebSDKInstance) {
+        this.mpInstance = mpInstance;
+    }
+
+    private isSupportedEnvironment(): boolean {
+        return (
+            typeof window !== 'undefined' &&
+            typeof window.history !== 'undefined' &&
+            typeof window.history.pushState === 'function' &&
+            typeof window.addEventListener === 'function'
+        );
+    }
+
+    public init(): void {
+        this.mpInstance.Logger.verbose(
+            'mParticle APV: [init] PageViewTracker Init'
+        );
+        if (!this.isSupportedEnvironment()) {
+            this.mpInstance.Logger.verbose(
+                'mParticle APV: [init] unsupported environment (no History API), not starting'
+            );
+            return;
+        }
+
+        if (this.isActive) {
+            this.mpInstance.Logger.verbose(
+                'mParticle APV: [init] starting (teardown-first for idempotency)'
+            );
+            this.teardown();
+        }
+
+        this.isActive = true;
+
+        this.lastPath = this.getCurrentKey();
+
+        this.mpInstance.Logger.verbose(
+            `mParticle APV: [init] seeded lastPath: ${this.lastPath}`
+        );
+
+        this.patchHistoryMethods();
+        this.addNavigationListeners();
+
+        this.mpInstance.Logger.verbose(
+            'mParticle APV: [init] patched pushState/replaceState + listening for popstate'
+        );
+    }
+
+    private patchHistoryMethods(): void {
+        const self = this;
+
+        const installed = window.history.pushState as MarkedHistoryMethod;
+        if (installed[WRAPPED_MARKER]) {
+            this.mpInstance.Logger.verbose(
+                'mParticle APV: [patch] history already wrapped, skipping to avoid double-wrap'
+            );
+            return;
+        }
+
+        const originalPushState = window.history.pushState;
+        const originalReplaceState = window.history.replaceState;
+        this.originalPushState = originalPushState;
+        this.originalReplaceState = originalReplaceState;
+
+        const pushStateWrapper = function(
+            this: History,
+            ...args: Parameters<HistoryStateMethod>
+        ): void {
+            const result = originalPushState.apply(this, args);
+            self.safeHandleNavigation('pushState');
+            return result;
+        };
+
+        const replaceStateWrapper = function(
+            this: History,
+            ...args: Parameters<HistoryStateMethod>
+        ): void {
+            const result = originalReplaceState.apply(this, args);
+            self.safeHandleNavigation('replaceState');
+            return result;
+        };
+
+        Object.defineProperty(pushStateWrapper, WRAPPED_MARKER, {
+            value: true,
+            enumerable: false,
+        });
+        Object.defineProperty(replaceStateWrapper, WRAPPED_MARKER, {
+            value: true,
+            enumerable: false,
+        });
+
+        this.pushStateWrapper = pushStateWrapper;
+        this.replaceStateWrapper = replaceStateWrapper;
+
+        try {
+            window.history.pushState = pushStateWrapper;
+            window.history.replaceState = replaceStateWrapper;
+        } catch (e) {
+            this.mpInstance.Logger.verbose(
+                `mParticle APV: [error] failed to patch history methods (frozen/sealed), rolling back: ${e}`
+            );
+            try {
+                if (window.history.pushState === pushStateWrapper) {
+                    window.history.pushState = originalPushState;
+                }
+                if (window.history.replaceState === replaceStateWrapper) {
+                    window.history.replaceState = originalReplaceState;
+                }
+            } catch (restoreError) {
+                this.mpInstance.Logger.verbose(
+                    `mParticle APV: [error] failed to restore history methods after patch failure: ${restoreError}`
+                );
+            }
+            this.pushStateWrapper = null;
+            this.replaceStateWrapper = null;
+            this.originalPushState = null;
+            this.originalReplaceState = null;
+        }
+    }
+
+    private addNavigationListeners(): void {
+        this.popStateListener = () => this.safeHandleNavigation('popstate');
+        window.addEventListener('popstate', this.popStateListener);
+    }
+
+    private safeHandleNavigation(source: string): void {
+        try {
+            this.handleNavigation(source);
+        } catch (e) {
+            this.mpInstance.Logger.verbose(
+                `mParticle APV: [error] navigation handler threw (${source}), page view skipped: ${e}`
+            );
+        }
+    }
+
+    private getCurrentKey(): string {
+        return window.location.pathname;
+    }
+
+    private handleNavigation(source: string): void {
+        const candidatePath = this.getCurrentKey();
+
+        this.mpInstance.Logger.verbose(
+            `mParticle APV: [detect] navigation signal (source: ${source}, candidatePath: ${candidatePath}, lastPath: ${this.lastPath})`
+        );
+
+        if (candidatePath === this.lastPath) {
+            this.mpInstance.Logger.verbose(
+                `mParticle APV: [dedupe] pathname unchanged, skipping (source: ${source}, path: ${candidatePath})`
+            );
+            return;
+        }
+
+        this.mpInstance.Logger.verbose(
+            `mParticle APV: [accept] pathname changed, scheduling fire (source: ${source}, from: ${this.lastPath}, to: ${candidatePath})`
+        );
+        this.lastPath = candidatePath;
+
+        // Snapshot the path now: it is already settled at this point, and a
+        // same-tick navigation would otherwise overwrite window.location
+        // before the deferred flush reads it. The title is intentionally read
+        // later (in the deferred flush) so the router's post-navigation render
+        // commit has a chance to update document.title first.
+        const capturedPath = candidatePath;
+
+        setTimeout(() => {
+            if (!this.isActive) {
+                this.mpInstance.Logger.verbose(
+                    'mParticle APV: [defer] fire aborted, tracker inactive (torn down before flush)'
+                );
+                return;
+            }
+
+            this.mpInstance._SessionManager.resetSessionTimer();
+            this.firePageView(capturedPath);
+        }, 0);
+    }
+
+    // Mirrors the event shape of the public mParticle.logPageView(), but carries
+    // the captured SPA path rather than reading the live location.
+    private firePageView(path: string): void {
+        const title = window.document.title;
+
+        this.mpInstance.Logger.verbose(
+            `mParticle APV: [fire] deferred flush -> _Events.logEvent(PageView) (path: ${path}, title: ${title})`
+        );
+
+        this.mpInstance._Events.logEvent({
+            messageType: MessageType.PageView,
+            name: 'PageView',
+            data: {
+                hostname: window.location.hostname,
+                title,
+                path,
+            },
+            eventType: EventType.Unknown,
+        });
+    }
+
+    public teardown(): void {
+        if (this.popStateListener) {
+            window.removeEventListener('popstate', this.popStateListener);
+            this.popStateListener = null;
+        }
+        const pushStateStillOurs =
+            this.pushStateWrapper !== null &&
+            window.history.pushState === this.pushStateWrapper;
+        if (this.originalPushState) {
+            if (pushStateStillOurs) {
+                window.history.pushState = this.originalPushState;
+                this.mpInstance.Logger.verbose(
+                    'mParticle APV: [teardown] restored original pushState'
+                );
+            } else {
+                this.mpInstance.Logger.verbose(
+                    'mParticle APV: [teardown] pushState no longer ours; leaving in place, gating callback to no-op'
+                );
+            }
+            this.originalPushState = null;
+            this.pushStateWrapper = null;
+        }
+
+        const replaceStateStillOurs =
+            this.replaceStateWrapper !== null &&
+            window.history.replaceState === this.replaceStateWrapper;
+        if (this.originalReplaceState) {
+            if (replaceStateStillOurs) {
+                window.history.replaceState = this.originalReplaceState;
+                this.mpInstance.Logger.verbose(
+                    'mParticle APV: [teardown] restored original replaceState'
+                );
+            } else {
+                this.mpInstance.Logger.verbose(
+                    'mParticle APV: [teardown] replaceState no longer ours; leaving in place, gating callback to no-op'
+                );
+            }
+            this.originalReplaceState = null;
+            this.replaceStateWrapper = null;
+        }
+
+        this.isActive = false;
+    }
+}

package/src/roktManager.ts

@@ -355,11 +355,13 @@ export default class RoktManager {
             this.setUserAttributes(mappedAttributes);
 
             const timeOnSite = this.store?.getTimeOnSite?.();
+            const totalTimeOnSite = this.store?.getTotalTimeOnSite?.();
 
             const enrichedAttributes: RoktAttributes = {
                 ...mappedAttributes,
                 ...(sandboxValue !== null ? { sandbox: sandboxValue } : {}),
                 ...(timeOnSite ? { active_time_on_site_ms: timeOnSite } : {}),
+                ...(totalTimeOnSite ? { total_time_on_site_ms: totalTimeOnSite } : {}),
             };
 
             // Propagate email from current user identities if not already in attributes

package/src/sdkRuntimeModels.ts

@@ -94,6 +94,7 @@ export interface SDKEvent {
     LaunchReferral?: string;
     ExpandedEventCount: number;
     ActiveTimeOnSite: number;
+    TotalTimeOnSite: number;
     PageUrl?: string;
     IsBackgroundAST?: boolean;
     AlreadySentToForwarders?: boolean;

package/src/sdkToEventsApiConverter.ts

@@ -664,6 +664,7 @@ export function convertBaseEventData(
         location: convertSDKLocation(sdkEvent.Location),
         source_message_id: sdkEvent.SourceMessageId,
         active_time_on_site_ms: sdkEvent.ActiveTimeOnSite,
+        total_time_on_site_ms: sdkEvent.TotalTimeOnSite,
         page_url: sdkEvent.PageUrl,
     };
 

package/src/serverModel.ts

@@ -311,6 +311,7 @@ export default function ServerModel(
                         event.name
                     ),
                     ActiveTimeOnSite: mpInstance._timeOnSiteTimer?.getTimeInForeground(),
+                    TotalTimeOnSite: mpInstance._Store.getTotalTimeOnSite?.(),
                     PageUrl: getHref() || null,
                     SourceMessageId:
                         event.sourceMessageId ||

package/src/store.ts

@@ -233,6 +233,7 @@ export interface IStore {
     getRoktAccountId?(): string;
     setRoktAccountId?(accountId: string): void;
     getTimeOnSite?(): number | undefined;
+    getTotalTimeOnSite?(): number | undefined;
     getIntegrationName?(): string;
     setIntegrationName?(integrationName: string): void;
 
@@ -687,6 +688,11 @@ export default function Store(
     this.getTimeOnSite = () =>
         mpInstance._timeOnSiteTimer?.getTimeInForeground();
 
+    this.getTotalTimeOnSite = () =>
+        this.sessionStartDate
+            ? Date.now() - this.sessionStartDate.getTime()
+            : undefined;
+
     this.addMpidToSessionHistory = (mpid: MPID, previousMPID?: MPID): void => {
         const indexOfMPID = this.currentSessionMPIDs.indexOf(mpid);