@mparticle/web-sdk 2.57.0 → 2.59.0

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "2.57.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/constants.ts

@@ -139,6 +139,8 @@ const Constants = {
         identityUrl: 'identity.mparticle.com/v1/',
         aliasUrl: 'jssdks.mparticle.com/v1/identity/',
         userAudienceUrl: 'nativesdks.mparticle.com/v1/',
+        loggingUrl: 'apps.rokt-api.com/v1/log',
+        errorUrl: 'apps.rokt-api.com/v1/errors',
     },
     // These are the paths that are used to construct the CNAME urls
     CNAMEUrlPaths: {
@@ -148,6 +150,8 @@ const Constants = {
         configUrl: '/tags/JS/v2/',
         identityUrl: '/identity/v1/',
         aliasUrl: '/webevents/v1/identity/',
+        loggingUrl: '/v1/log',
+        errorUrl: '/v1/errors',
     },
     Base64CookieKeys: {
         csm: 1,

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/identityApiClient.ts

@@ -25,6 +25,7 @@ import {
     IIdentityResponse,
 } from './identity-user-interfaces';
 import { IMParticleWebSDKInstance } from './mp-instance';
+import { ErrorCodes } from './logging/types';
 
 const { HTTPCodes, Messages, IdentityMethods } = Constants;
 
@@ -326,10 +327,13 @@ export default function IdentityAPIClient(
                 const requestCount = mpInstance._Store.identifyRequestCount;
                 mpInstance.captureTiming(`${requestCount}-identityRequestEnd`);
             }
-            
+
             const errorMessage = (err as Error).message || err.toString();
-            Logger.error('Error sending identity request to servers - ' + errorMessage);
-            
+            Logger.error(
+                'Error sending identity request to servers' + ' - ' + errorMessage,
+                ErrorCodes.IDENTITY_REQUEST
+            );
+
             mpInstance.processQueueOnIdentityFailure?.();
             invokeCallback(callback, HTTPCodes.noHttpCoverage, errorMessage);
         }

package/src/logger.ts

@@ -1,4 +1,6 @@
 import { LogLevelType, SDKInitConfig, SDKLoggerApi } from './sdkRuntimeModels';
+import { ReportingLogger } from './logging/reportingLogger';
+import { ErrorCodes } from './logging/types';
 
 export type ILoggerConfig = Pick<SDKInitConfig, 'logLevel' | 'logger'>;
 export type IConsoleLogger = Partial<Pick<SDKLoggerApi, 'error' | 'warning' | 'verbose'>>;
@@ -6,10 +8,14 @@ export type IConsoleLogger = Partial<Pick<SDKLoggerApi, 'error' | 'warning' | 'v
 export class Logger {
     private logLevel: LogLevelType;
     private logger: IConsoleLogger;
+    private reportingLogger: ReportingLogger;
 
-    constructor(config: ILoggerConfig) {
+    constructor(config: ILoggerConfig,
+        reportingLogger?: ReportingLogger,
+    ) {
         this.logLevel = config.logLevel ?? LogLevelType.Warning;
         this.logger = config.logger ?? new ConsoleLogger();
+        this.reportingLogger = reportingLogger;
     }
 
     public verbose(msg: string): void {
@@ -22,21 +28,24 @@ export class Logger {
     }
 
     public warning(msg: string): void {
-        if(this.logLevel === LogLevelType.None) 
+        if(this.logLevel === LogLevelType.None)
             return;
 
-        if (this.logger.warning && 
+        if (this.logger.warning &&
             (this.logLevel === LogLevelType.Verbose || this.logLevel === LogLevelType.Warning)) {
             this.logger.warning(msg);
         }
     }
 
-    public error(msg: string): void {
-        if(this.logLevel === LogLevelType.None) 
+    public error(msg: string, codeForReporting?: ErrorCodes): void {
+        if(this.logLevel === LogLevelType.None)
             return;
 
         if (this.logger.error) {
             this.logger.error(msg);
+            if (codeForReporting) {
+                this.reportingLogger?.error(msg, codeForReporting);
+            }
         }
     }
 

package/src/logging/reportingLogger.ts

@@ -0,0 +1,192 @@
+import { ErrorCodes, LogRequestBody, WSDKErrorSeverity } from "./types";
+import { FetchUploader, IFetchPayload } from "../uploaders";
+import { IStore, SDKConfig } from "../store";
+import { SDKInitConfig } from "../sdkRuntimeModels";
+import Constants from "../constants";
+
+// Header key constants
+const HEADER_ACCEPT = 'Accept' as const;
+const HEADER_CONTENT_TYPE = 'Content-Type' as const;
+const HEADER_ROKT_LAUNCHER_VERSION = 'rokt-launcher-version' as const;
+const HEADER_ROKT_LAUNCHER_INSTANCE_GUID = 'rokt-launcher-instance-guid' as const;
+const HEADER_ROKT_WSDK_VERSION = 'rokt-wsdk-version' as const;
+
+interface IReportingLoggerPayload extends IFetchPayload {
+    headers: IFetchPayload['headers'] & {
+        [HEADER_ROKT_LAUNCHER_INSTANCE_GUID]?: string;
+        [HEADER_ROKT_LAUNCHER_VERSION]: string;
+        [HEADER_ROKT_WSDK_VERSION]: string;
+    };
+    body: string;
+}
+
+export class ReportingLogger {
+    private readonly isEnabled: boolean;
+    private readonly reporter: string = 'mp-wsdk';
+    private readonly rateLimiter: IRateLimiter;
+    private store: IStore | null;
+    private readonly loggingUrl: string;
+    private readonly errorUrl: string;
+    private readonly isLoggingEnabled: boolean;
+
+    constructor(
+        config: SDKConfig | SDKInitConfig | any,
+        private readonly sdkVersion: string,
+        store?: IStore,
+        private readonly launcherInstanceGuid?: string,
+        rateLimiter?: IRateLimiter,
+    ) {
+        this.loggingUrl = `https://${config.loggingUrl || Constants.DefaultBaseUrls.loggingUrl}`;
+        this.errorUrl = `https://${config.errorUrl || Constants.DefaultBaseUrls.errorUrl}`;
+        this.isLoggingEnabled = config.isLoggingEnabled || false;
+        this.store = store ?? null;
+        this.isEnabled = this.isReportingEnabled();
+        this.rateLimiter = rateLimiter ?? new RateLimiter();
+    }
+
+    public setStore(store: IStore): void {
+        this.store = store;
+    }
+
+    public info(msg: string, code?: ErrorCodes) {
+        this.sendLog(WSDKErrorSeverity.INFO, msg, code);
+    }
+
+    public error(msg: string, code?: ErrorCodes, stackTrace?: string) {
+        this.sendError(WSDKErrorSeverity.ERROR, msg, code, stackTrace);
+    }
+
+    public warning(msg: string, code?: ErrorCodes) { 
+        this.sendError(WSDKErrorSeverity.WARNING, msg, code);
+    }
+    
+    private sendToServer(url: string, severity: WSDKErrorSeverity, msg: string, code?: ErrorCodes, stackTrace?: string): void {
+        if (!this.canSendLog(severity))
+            return;
+
+        try {
+            const logRequest = this.buildLogRequest(severity, msg, code, stackTrace);
+            const uploader = new FetchUploader(url);
+            const payload: IReportingLoggerPayload = {
+                method: 'POST',
+                headers: this.getHeaders(),
+                body: JSON.stringify(logRequest),
+            };
+            uploader.upload(payload).catch((error) => {
+                console.error('ReportingLogger: Failed to send log', error);
+            });
+        } catch (error) {
+            console.error('ReportingLogger: Failed to send log', error);
+        }
+    }
+
+    private sendLog(severity: WSDKErrorSeverity, msg: string, code?: ErrorCodes, stackTrace?: string): void {
+        this.sendToServer(this.loggingUrl, severity, msg, code, stackTrace);
+    }
+
+    private sendError(severity: WSDKErrorSeverity, msg: string, code?: ErrorCodes, stackTrace?: string): void {
+        this.sendToServer(this.errorUrl, severity, msg, code, stackTrace);
+    }
+ 
+    private buildLogRequest(severity: WSDKErrorSeverity, msg: string, code?: ErrorCodes, stackTrace?: string): LogRequestBody {
+        return {
+            additionalInformation: {
+                message: msg,
+                version: this.getVersion(),
+            },
+            severity: severity,
+            code: code ?? ErrorCodes.UNKNOWN_ERROR,
+            url: this.getUrl(),
+            deviceInfo: this.getUserAgent(),
+            stackTrace: stackTrace,
+            reporter: this.reporter,
+            // Integration will be set to integrationName once the kit connects via RoktManager.attachKit()
+            integration: this.store?.getIntegrationName() ?? 'mp-wsdk'
+        };
+    }
+
+    private getVersion(): string {
+        return this.store?.getIntegrationName?.() ?? `mParticle_wsdkv_${this.sdkVersion}`;
+    }
+    
+    private isReportingEnabled(): boolean {
+        return this.isDebugModeEnabled() ||
+               (this.isRoktDomainPresent() && this.isFeatureFlagEnabled());
+    }
+
+    private isRoktDomainPresent(): boolean {
+        return typeof window !== 'undefined' && Boolean(window['ROKT_DOMAIN']);
+    }
+
+    private isFeatureFlagEnabled = (): boolean => this.isLoggingEnabled;
+
+    private isDebugModeEnabled(): boolean {
+        return (
+            typeof window !== 'undefined' &&
+            (window.
+                location?.
+                search?.
+                toLowerCase()?.
+                includes('mp_enable_logging=true') ?? false)
+        );
+    }
+
+    private canSendLog(severity: WSDKErrorSeverity): boolean {
+        return this.isEnabled && !this.isRateLimited(severity);
+    }
+
+    private isRateLimited(severity: WSDKErrorSeverity): boolean {
+        return this.rateLimiter.incrementAndCheck(severity);
+    }
+
+    private getUrl(): string | undefined {
+        return typeof window !== 'undefined' ? window.location?.href : undefined;
+    }
+
+    private getUserAgent(): string | undefined {
+        return typeof window !== 'undefined' ? window.navigator?.userAgent : undefined;
+    }
+
+    private getHeaders(): IReportingLoggerPayload['headers'] {
+        const headers: IReportingLoggerPayload['headers'] = {
+            [HEADER_ACCEPT]: 'text/plain;charset=UTF-8',
+            [HEADER_CONTENT_TYPE]: 'application/json',
+            [HEADER_ROKT_LAUNCHER_VERSION]: this.getVersion(),
+            [HEADER_ROKT_WSDK_VERSION]: 'joint',
+        };
+
+        if (this.launcherInstanceGuid) {
+            headers[HEADER_ROKT_LAUNCHER_INSTANCE_GUID] = this.launcherInstanceGuid;
+        }
+
+        const accountId = this.store?.getRoktAccountId?.();
+        if (accountId) {
+            headers['rokt-account-id'] = accountId;
+        }
+
+        return headers;
+    }
+}
+
+export interface IRateLimiter {
+    incrementAndCheck(severity: WSDKErrorSeverity): boolean;
+}
+
+export class RateLimiter implements IRateLimiter {
+    private readonly rateLimits: Map<WSDKErrorSeverity, number> = new Map([
+        [WSDKErrorSeverity.ERROR, 10],
+        [WSDKErrorSeverity.WARNING, 10],
+        [WSDKErrorSeverity.INFO, 10],
+    ]);
+    private logCount: Map<WSDKErrorSeverity, number> = new Map();
+
+    public incrementAndCheck(severity: WSDKErrorSeverity): boolean {
+        const count = this.logCount.get(severity) || 0;
+        const limit = this.rateLimits.get(severity) || 10;
+        
+        const newCount = count + 1;
+        this.logCount.set(severity, newCount);
+        
+        return newCount > limit;
+    }
+}

package/src/logging/types.ts

@@ -0,0 +1,32 @@
+import { valueof } from '../utils';
+
+export const ErrorCodes = {
+    UNKNOWN_ERROR: 'UNKNOWN_ERROR',
+    UNHANDLED_EXCEPTION: 'UNHANDLED_EXCEPTION',
+    IDENTITY_REQUEST: 'IDENTITY_REQUEST',
+} as const;
+
+export type ErrorCodes = valueof<typeof ErrorCodes>;
+
+export type ErrorCode = ErrorCodes | string;
+
+export const WSDKErrorSeverity = {
+    ERROR: 'ERROR',
+    INFO: 'INFO',
+    WARNING: 'WARNING',
+} as const;
+
+export type WSDKErrorSeverity = (typeof WSDKErrorSeverity)[keyof typeof WSDKErrorSeverity];
+
+export type ErrorsRequestBody = {
+    additionalInformation?: Record<string, string>;
+    code: ErrorCode;
+    severity: WSDKErrorSeverity;
+    stackTrace?: string;
+    deviceInfo?: string;
+    integration?: string;
+    reporter?: string;
+    url?: string;
+};
+
+export type LogRequestBody = ErrorsRequestBody;