@mparticle/web-sdk 2.58.0 → 2.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "2.58.0",
+    "version": "2.59.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [

package/src/apiClient.ts

@@ -10,6 +10,7 @@ import { IMParticleUser, ISDKUserAttributes } from './identity-user-interfaces';
 import { AsyncUploader, FetchUploader, XHRUploader } from './uploaders';
 import { IMParticleWebSDKInstance } from './mp-instance';
 import { appendUserInfo } from './user-utils';
+import { hasExplicitIdentifier } from './identity-utils';
 
 export interface IAPIClient {
     uploader: BatchUploader | null;
@@ -88,6 +89,35 @@ export default function APIClient(
         });
     };
 
+    // When noFunctional is set and there are no identities passed, the SDK will not fully initialize.
+    // In this case, there will be no MPID, but we still want kits to initialize and forward the event to kits.
+    // The original event is queued for the MP server upload path so it can be sent once an MPID is returned.
+    // Returns true if the event was handled by this path (caller should return early).
+    const handleNoFunctionalPreMpidEvent = (event: SDKEvent, mpid: string | undefined): boolean => {
+        const noFunctionalWithoutId =
+            mpInstance._CookieConsentManager?.getNoFunctional() &&
+            !hasExplicitIdentifier(mpInstance._Store);
+
+        if (!noFunctionalWithoutId || mpid || !mpInstance._Store.configurationLoaded || mpInstance._Store.requireDelay) {
+            return false;
+        }
+
+        let forwarderEvent = event;
+        if (kitBlocker?.kitBlockingEnabled) {
+            forwarderEvent = kitBlocker.createBlockedEvent(event);
+        }
+        if (forwarderEvent) {
+            mpInstance._Forwarders.sendEventToForwarders(forwarderEvent);
+            event.AlreadySentToForwarders = true;
+        }
+        mpInstance.Logger.verbose(
+            'noFunctional event forwarded to kits and queued for MP server upload when MPID is available.'
+        );
+        mpInstance._Store.eventQueue.push(event);
+
+        return true;
+    };
+
     this.sendEventToServer = function(event, _options) {
         const defaultOptions = {
             shouldUploadEvent: true,
@@ -112,8 +142,14 @@ export default function APIClient(
             mpInstance._Store.integrationDelayTimeoutStart,
             Date.now()
         );
-        // We queue events if there is no MPID (MPID is null, or === 0), or there are integrations that that require this to stall because integration attributes
-        // need to be set, or if we are still fetching the config (self hosted only), and so require delaying events
+
+        if (handleNoFunctionalPreMpidEvent(event, mpid)) {
+            return;
+        }
+
+        // We queue events if there is no MPID (MPID is null, or === 0), or there are integrations that
+        // require this to stall because integration attributes need to be set, or if we are still
+        // fetching the config (self hosted only), and so require delaying events
         if (
             !mpid ||
             mpInstance._Store.requireDelay ||
@@ -146,8 +182,10 @@ export default function APIClient(
             }
 
             // We need to check event again, because kitblocking
-            // can nullify the event
-            if (event) {
+            // can nullify the event.
+            // Skip if forwarders were already called in the noFunctional pre-MPID path
+            // to prevent double-sending when the event queue is later flushed.
+            if (event && !event.AlreadySentToForwarders) {
                 mpInstance._Forwarders.sendEventToForwarders(event);
             }
         }

package/src/batchUploader.ts

@@ -74,7 +74,10 @@ export class BatchUploader {
         // so that we don't have to check it every time
         this.offlineStorageEnabled = this.isOfflineStorageAvailable();
 
-        if (this.offlineStorageEnabled) {
+        // When noFunctional is true, prevent events/batches storage
+        const noFunctional = mpInstance._CookieConsentManager?.getNoFunctional();
+
+        if (this.offlineStorageEnabled && !noFunctional) {
             this.eventVault = new SessionStorageVault<SDKEvent[]>(
                 `${mpInstance._Store.storageName}-events`,
                 {

package/src/cookieSyncManager.ts

@@ -73,6 +73,12 @@ export default function CookieSyncManager(
             return;
         }
 
+        // When noFunctional is true, persistence is not saved, so we cannot track cookie sync
+        // dates. Skip cookie sync to avoid running it on every page load.
+        if (mpInstance._CookieConsentManager?.getNoFunctional()) {
+            return;
+        }
+
         const persistence = mpInstance._Persistence.getPersistence();
 
         if (isEmpty(persistence)) {

package/src/foregroundTimeTracker.ts

@@ -8,10 +8,12 @@ export default class ForegroundTimeTracker {
     public startTime: number = 0;
     public totalTime: number = 0;
 
-    constructor(timerKey: string) {
+    constructor(timerKey: string, private noFunctional: boolean = false) {
         this.localStorageName = `mprtcl-tos-${timerKey}`;
         this.timerVault = new LocalStorageVault<number>(this.localStorageName);
-        this.loadTimeFromStorage();
+        if (!this.noFunctional) {
+            this.loadTimeFromStorage();
+        }
         this.addHandlers();
         if (document.hidden === false) {
             this.startTracking();
@@ -63,7 +65,7 @@ export default class ForegroundTimeTracker {
     }
 
     public updateTimeInPersistence(): void {
-        if (this.isTrackerActive) {
+        if (this.isTrackerActive && !this.noFunctional) {
             this.timerVault.store(Math.round(this.totalTime));
         }
     }

package/src/identity-utils.ts

@@ -1,5 +1,5 @@
 import Constants, { ONE_DAY_IN_SECONDS, MILLIS_IN_ONE_SEC } from './constants';
-import { Dictionary, parseNumber, isObject, generateHash } from './utils';
+import { Dictionary, parseNumber, isObject, generateHash, isEmpty } from './utils';
 import { BaseVault } from './vault';
 import Types from './types';
 import {
@@ -13,6 +13,7 @@ import {
     IIdentityResponse,
     IMParticleUser,
 } from './identity-user-interfaces';
+import { IStore } from './store';
 
 const { Identify, Modify, Login, Logout } = Constants.IdentityMethods;
 export const CACHE_HEADER = 'x-mp-max-age' as const;
@@ -298,3 +299,25 @@ export const hasIdentityRequestChanged = (
         JSON.stringify(currentUserIdentities) !== JSON.stringify(newIdentities)
     );
 };
+
+/**
+ * Checks if deviceId or other user identifiers (like email) were explicitly provided
+ * by the partner via config.deviceId or config.identifyRequest.userIdentities.
+ * When noFunctional is true, then cookies are blocked, so the partner must explicitly
+ * pass deviceId or other identifiers to prevent new users from being created on each page load.
+ *
+ * @param store - The SDK store (provides SDKConfig.deviceId and SDKConfig.identifyRequest.userIdentities)
+ * @returns true if deviceId or other identifiers were explicitly provided in config, false otherwise
+ */
+export const hasExplicitIdentifier = (store: IStore | undefined | null): boolean => {
+    const userIdentities = store?.SDKConfig?.identifyRequest?.userIdentities;
+    if (
+        userIdentities &&
+        isObject(userIdentities) &&
+        !isEmpty(userIdentities) &&
+        Object.values(userIdentities).some(Boolean)
+    ) {
+        return true;
+    }
+    return !!store?.SDKConfig?.deviceId;
+};

package/src/mp-instance.ts

@@ -37,8 +37,8 @@ import KitBlocker from './kitBlocking';
 import ConfigAPIClient, { IKitConfigs } from './configAPIClient';
 import IdentityAPIClient from './identityApiClient';
 import { isFunction, parseConfig, valueof, generateDeprecationMessage } from './utils';
-import { LocalStorageVault } from './vault';
-import { removeExpiredIdentityCacheDates } from './identity-utils';
+import { DisabledVault, LocalStorageVault } from './vault';
+import { removeExpiredIdentityCacheDates, hasExplicitIdentifier } from './identity-utils';
 import IntegrationCapture from './integrationCapture';
 import { IPreInit, processReadyQueue } from './pre-init-utils';
 import { BaseEvent, MParticleWebSDK, SDKHelpersApi } from './sdkRuntimeModels';
@@ -97,6 +97,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     getLauncherInstanceGuid: () => string;
     captureTiming(metricName: string);
     processQueueOnIdentityFailure?: () => void;
+    processQueueOnNoFunctional?: () => void;
 }
 
 const { Messages, HTTPCodes, FeatureFlags, CaptureIntegrationSpecificIdsV2Modes } = Constants;
@@ -150,13 +151,30 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
         if (self._Store?.isInitialized) {
             return;
         }
-        
+
         if (self._Store?.identityCallFailed && self._RoktManager?.isReady()) {
             self._RoktManager.processMessageQueue();
             self._preInit.readyQueue = processReadyQueue(self._preInit.readyQueue);
         }
     };
 
+    /**
+     * Drains the ready queue for noFunctional sessions with no explicit identity.
+     */
+    this.processQueueOnNoFunctional = function() {
+        if (self._Store?.isInitialized) {
+            return;
+        }
+
+        const noFunctionalWithoutId =
+            self._CookieConsentManager?.getNoFunctional() &&
+            !hasExplicitIdentifier(self._Store);
+
+        if (noFunctionalWithoutId) {
+            self._preInit.readyQueue = processReadyQueue(self._preInit.readyQueue);
+        }
+    };
+
     // required for forwarders once they reference the mparticle instance
     this.IdentityType = IdentityType;
     this.EventType = EventType;
@@ -280,11 +298,16 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
      * @param {Function} f Callback to execute
      */
     this.ready = function(f) {
+        const noFunctionalWithoutId =
+            self._CookieConsentManager?.getNoFunctional() &&
+            !hasExplicitIdentifier(self._Store);
+
         const shouldExecute = isFunction(f) && (
-            self._Store?.isInitialized || 
-            (self._Store?.identityCallFailed && self._RoktManager.isReady())
+            self._Store?.isInitialized ||
+            (self._Store?.identityCallFailed && self._RoktManager.isReady()) ||
+            noFunctionalWithoutId
         );
-        
+
         if (shouldExecute) {
             f();
         } else {
@@ -1135,11 +1158,16 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
      * @param {String or Number} value value for session attribute
      */
     this.setSessionAttribute = function(key, value) {
-        const queued = queueIfNotInitialized(function() {
-            self.setSessionAttribute(key, value);
-        }, self);
+        const skipQueue =
+            self._CookieConsentManager?.getNoFunctional() &&
+            !hasExplicitIdentifier(self._Store);
 
-        if (queued) return;
+        if (!skipQueue) {
+            const queued = queueIfNotInitialized(function() {
+                self.setSessionAttribute(key, value);
+            }, self);
+            if (queued) return;
+        }
 
         // Logs to cookie
         // And logs to in-memory object
@@ -1512,6 +1540,10 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
         );
     }
 
+    // For noFunctional sessions with no identity, drain any pre-init ready callbacks
+    // that were queued before _CookieConsentManager was available to evaluate the condition.
+    mpInstance.processQueueOnNoFunctional?.();
+
     // https://go.mparticle.com/work/SQDSDKS-6040
     if (mpInstance._Store.isFirstRun) {
         mpInstance._Store.isFirstRun = false;
@@ -1584,6 +1616,14 @@ function createKitBlocker(config, mpInstance) {
 }
 
 function createIdentityCache(mpInstance) {
+    // Identity expects mpInstance._Identity.idCache to always exist. DisabledVault
+    // ensures no identity response data is written to localStorage when noFunctional is true
+    if (mpInstance._CookieConsentManager?.getNoFunctional()) {
+        return new DisabledVault(`${mpInstance._Store.storageName}-id-cache`, {
+            logger: mpInstance.Logger,
+        });
+    }
+    
     return new LocalStorageVault(`${mpInstance._Store.storageName}-id-cache`, {
         logger: mpInstance.Logger,
     });
@@ -1664,15 +1704,21 @@ function processIdentityCallback(
 }
 
 function queueIfNotInitialized(func, self) {
-    // Core SDK methods must wait for Store initialization
-    if (!self._Store?.isInitialized) {
-        self._preInit.readyQueue.push(function() {
-            if (self._Store?.isInitialized) {
-                func();
-            }
-        });
-        return true;
+    // When noFunctional is true with no explicit identifier, the SDK will never
+    // receive an MPID. Let these calls through so events can still reach forwarders immediately.
+    // sendEventToServer handles queuing for the MP server upload path separately.
+    const noFunctionalWithoutId =
+        self._CookieConsentManager?.getNoFunctional() &&
+        !hasExplicitIdentifier(self._Store);
+
+    if (self._Store?.isInitialized || noFunctionalWithoutId) {
+        return false;
     }
-    return false;
+    self._preInit.readyQueue.push(function() {
+        if (self._Store?.isInitialized) {
+            func();
+        }
+    });
+    return true;
 }
 

package/src/persistence.js

@@ -230,6 +230,11 @@ export default function _Persistence(mpInstance) {
             return;
         }
 
+        // Block mprtcl-v4 localStorage when noFunctional is true
+        if (mpInstance._CookieConsentManager?.getNoFunctional()) {
+            return;
+        }
+
         var key = mpInstance._Store.storageName,
             localStorageData = self.getLocalStorage() || {},
             currentUser = mpInstance.Identity.getCurrentUser(),
@@ -398,6 +403,11 @@ export default function _Persistence(mpInstance) {
     // https://go.mparticle.com/work/SQDSDKS-5022
     // https://go.mparticle.com/work/SQDSDKS-6021
     this.setCookie = function() {
+        // Block mprtcl-v4 cookies when noFunctional is true
+        if (mpInstance._CookieConsentManager?.getNoFunctional()) {
+            return;
+        }
+
         var mpid,
             currentUser = mpInstance.Identity.getCurrentUser();
         if (currentUser) {
@@ -803,6 +813,11 @@ export default function _Persistence(mpInstance) {
 
     // https://go.mparticle.com/work/SQDSDKS-6021
     this.savePersistence = function(persistence) {
+        // Block mprtcl-v4 persistence when noFunctional is true
+        if (mpInstance._CookieConsentManager?.getNoFunctional()) {
+            return;
+        }
+
         var encodedPersistence = self.encodePersistence(
                 JSON.stringify(persistence)
             ),

package/src/sdkRuntimeModels.ts

@@ -94,6 +94,7 @@ export interface SDKEvent {
     ExpandedEventCount: number;
     ActiveTimeOnSite: number;
     IsBackgroundAST?: boolean;
+    AlreadySentToForwarders?: boolean;
 }
 
 export interface SDKGeoLocation {

package/src/sessionManager.ts

@@ -5,7 +5,7 @@ import Types from './types';
 import { generateDeprecationMessage } from './utils';
 import { IMParticleUser } from './identity-user-interfaces';
 import { IMParticleWebSDKInstance } from './mp-instance';
-import { hasIdentityRequestChanged } from './identity-utils';
+import { hasIdentityRequestChanged, hasExplicitIdentifier } from './identity-utils';
 
 const { Messages } = Constants;
 
@@ -45,7 +45,12 @@ export default function SessionManager(
                 const currentUser = mpInstance.Identity.getCurrentUser();
                 const sdkIdentityRequest = SDKConfig.identifyRequest;
 
+                const shouldSuppressIdentify = 
+                    mpInstance._CookieConsentManager?.getNoFunctional() &&
+                    !hasExplicitIdentifier(mpInstance._Store);
+
                 if (
+                    !shouldSuppressIdentify &&
                     hasIdentityRequestChanged(currentUser, sdkIdentityRequest)
                 ) {
                     mpInstance.Identity.identify(
@@ -102,7 +107,11 @@ export default function SessionManager(
 
             self.setSessionTimer();
 
-            if (!mpInstance._Store.identifyCalled) {
+            const shouldSuppressIdentify = 
+                mpInstance._CookieConsentManager?.getNoFunctional() &&
+                !hasExplicitIdentifier(mpInstance._Store);
+
+            if (!mpInstance._Store.identifyCalled && !shouldSuppressIdentify) {
                 mpInstance.Identity.identify(
                     mpInstance._Store.SDKConfig.identifyRequest,
                     mpInstance._Store.SDKConfig.identityCallback

package/src/store.ts

@@ -732,7 +732,8 @@ export default function Store(
 
         if (workspaceToken) {
             this.SDKConfig.workspaceToken = workspaceToken;
-            mpInstance._timeOnSiteTimer = new ForegroundTimer(workspaceToken);
+            const noFunctional = config?.launcherOptions?.noFunctional === true;
+            mpInstance._timeOnSiteTimer = new ForegroundTimer(workspaceToken, noFunctional);
         } else {
             mpInstance.Logger.warning(
                 'You should have a workspaceToken on your config object for security purposes.'

package/src/vault.ts

@@ -102,4 +102,25 @@ export class SessionStorageVault<StorableItem> extends BaseVault<StorableItem> {
     constructor(storageKey: string, options?: IVaultOptions) {
         super(storageKey, window.sessionStorage, options);
     }
+}
+
+// DisabledVault is used when persistence is disabled by privacy flags.
+export class DisabledVault<StorableItem> extends BaseVault<StorableItem> {
+    constructor(storageKey: string, options?: IVaultOptions) {
+        super(storageKey, window.localStorage, options);
+        this.contents = null;
+        this.storageObject.removeItem(this._storageKey);
+    }
+
+    public store(_item: StorableItem): void {
+        this.contents = null;
+    }
+
+    public retrieve(): StorableItem | null {
+        return this.contents;
+    }
+
+    public purge(): void {
+        this.contents = null;
+    }
 }