@mparticle/web-sdk 3.16.1 → 3.18.0

package/src/buttonTracking/labelMasking.ts

@@ -0,0 +1,41 @@
+// Masks a button label before it is logged. Button text can carry personal data,
+// so this is the privacy boundary for every label and aria-label.
+
+// Masking needs \p{Nd} to see every script's digits. Browsers without Unicode
+// property escapes send no labels at all.
+function createDigitPatterns(): { run: RegExp; number: RegExp } | undefined {
+    try {
+        return {
+            run: new RegExp('\\p{Nd}{6,}', 'u'),
+            number: new RegExp('\\p{Nd}+(?:[.,،٫٬]\\p{Nd}+)*', 'gu'),
+        };
+    } catch (e) {
+        return undefined;
+    }
+}
+
+const digitPatterns = createDigitPatterns();
+
+// The label as logged: lower case, at most 64 characters, digits and amounts
+// masked. Dropped when it looks like an email, phone or card number.
+export function maskLabel(raw: string | null | undefined): string | undefined {
+    if (!raw || raw.length > 128 || !digitPatterns) {
+        return undefined;
+    }
+    const text = raw
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+    if (
+        !text ||
+        text.indexOf('@') !== -1 ||
+        digitPatterns.run.test(text.replace(/[\s()\-‐-―]/g, ''))
+    ) {
+        return undefined;
+    }
+    const masked = text
+        .replace(digitPatterns.number, '#')
+        .slice(0, 64)
+        .trim();
+    return masked || undefined;
+}

package/src/constants.ts

@@ -190,6 +190,7 @@ const Constants = {
         CaptureIntegrationSpecificIdsV2: 'captureIntegrationSpecificIds.V2',
         AstBackgroundEvents: 'astBackgroundEvents',
         AutoLogPageView: 'autoLogPageView',
+        AutoButtonTracking: 'autoButtonTracking',
     },
     DefaultInstance: 'default_instance',
     CCPAPurpose: 'data_sale_opt_out',

package/src/internal-types.ts

@@ -34,6 +34,7 @@ export type {
     RoktKitFilterSettings,
     IRoktKitSettings,
     IRoktKit,
+    ICheckoutIntentSignal,
     IRoktOptions,
     IRoktLauncherOptions,
 } from './roktManager';

package/src/mp-instance.ts

@@ -66,6 +66,7 @@ import {
     PageViewTracker,
     resetPageViewTracking,
 } from './pageViewTracker';
+import { ButtonTracker, resetButtonTracking } from './buttonTracking/buttonTracker';
 
 export interface IErrorLogMessage {
     message?: string;
@@ -99,6 +100,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     _IntegrationCapture: IntegrationCapture;
     _NativeSdkHelpers: INativeSdkHelpers;
     _PageViewTracker?: PageViewTracker;
+    _ButtonTracker?: ButtonTracker;
     _Persistence: IPersistence;
     _CookieConsentManager: ICookieConsentManager;
     _ErrorReportingDispatcher: ErrorReportingDispatcher;
@@ -286,6 +288,10 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
     this.reset = function(instance) {
         try {
             instance._Persistence.resetPersistence();
+            // The Rokt manager keeps its own store reference, so stop button
+            // tracking here rather than relying on the deleted store.
+            resetButtonTracking();
+            instance._ButtonTracker = undefined;
             if (instance._Store) {
                 delete instance._Store;
             }
@@ -311,6 +317,8 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
 
         resetPageViewTracking();
         instance._PageViewTracker = undefined;
+        resetButtonTracking();
+        instance._ButtonTracker = undefined;
 
         if (!keepPersistence) {
             instance._Persistence.resetPersistence();
@@ -1133,6 +1141,13 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
         self._SessionManager.resetSessionTimer();
         self._Store.isEnabled = !isOptingOut;
 
+        if (isOptingOut) {
+            if (self._ButtonTracker) {
+                self._ButtonTracker.clearPending();
+            }
+            self._RoktManager.discardCheckoutIntents();
+        }
+
         self._Events.logOptOut();
         self._Persistence.update();
 
@@ -1347,7 +1362,7 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
 function completeSDKInitialization(apiKey, config, mpInstance) {
     const kitBlocker = createKitBlocker(config, mpInstance);
     const { getFeatureFlag } = mpInstance._Helpers;
-    const { AutoLogPageView } = Constants.FeatureFlags;
+    const { AutoLogPageView, AutoButtonTracking } = Constants.FeatureFlags;
 
     // Destroy previous batch uploader to prevent leaked timers and event listeners
     if (mpInstance._APIClient?.uploader) {
@@ -1367,6 +1382,8 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
     // persistence or Identity directly.
     if (mpInstance._Store.webviewBridgeEnabled) {
         mpInstance._NativeSdkHelpers.initializeSessionAttributes(apiKey);
+        // Button tracking never runs as a native passthrough.
+        resetButtonTracking();
     } else {
         // Main SDK initialization flow
 
@@ -1477,6 +1494,19 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
             mpInstance._PageViewTracker.teardown();
         }
 
+        // Button clicks are logged for any workspace that opts in. Checkout
+        // intent also goes to the Rokt kit when this init configures one.
+        if (getFeatureFlag(AutoButtonTracking)) {
+            if (!mpInstance._ButtonTracker) {
+                mpInstance._ButtonTracker = new ButtonTracker(mpInstance);
+            }
+            mpInstance._ButtonTracker.init({ hasRoktKit: !!roktConfig });
+        } else {
+            // Also retires a tracker left by an earlier bundle load. Like APV,
+            // this assumes a single active SDK instance.
+            resetButtonTracking();
+        }
+
         processIdentityCallback(
             mpInstance,
             currentUser,
@@ -1596,6 +1626,8 @@ function runPreConfigFetchInitialization(mpInstance, apiKey, config) {
     mpInstance._LoggingDispatcher.logger = mpInstance.Logger;
     mpInstance._Store = new Store(config, mpInstance, apiKey);
     window.mParticle.Store = mpInstance._Store;
+    // Button tracking stops until this init's config decides whether it runs.
+    resetButtonTracking();
     mpInstance.Logger.verbose(StartingInitialization);
 
     // Initialize CookieConsentManager with privacy flags from launcherOptions

package/src/roktManager.ts

@@ -23,8 +23,11 @@ import { PARTNER_MODULE_IDS } from "./cookieSyncManager";
 import IntegrationCapture from "./integrationCapture";
 import Constants from "./constants";
 import { subscribeToRouteChange } from "./routeChangeMonitor";
+import type { CheckoutIntentKind } from "./buttonTracking/checkoutIntent";
 
 const PASSBACK_CONVERSION_TRACKING_ID = 'passbackconversiontrackingid';
+const CHECKOUT_INTENT_BUFFER_LIMIT = 4;
+const CHECKOUT_INTENT_MAX_AGE_MS = 30000;
 
 type AttributeTargetUser = Pick<IMParticleUser, 'getUserIdentities' | 'setUserAttributes'>;
 
@@ -71,6 +74,11 @@ export interface RoktKitFilterSettings {
     filteredUser?: IMParticleUser | null;
 }
 
+export interface ICheckoutIntentSignal {
+    kind: CheckoutIntentKind;
+    t: number;
+}
+
 export interface IRoktKitSettings {
     accountId?: string;
     placementAttributesMapping?: string;
@@ -93,6 +101,8 @@ export interface IRoktKit {
     // Set by the kit only when it wants route changes; nothing subscribes otherwise. The
     // manager also calls it once on attach.
     onRouteChange?: () => void;
+    // Set by the kit only when it wants checkout intent signals.
+    onCheckoutIntent?: (signal: ICheckoutIntentSignal) => void;
     launcherOptions?: Dictionary<any>;
     settings?: IRoktKitSettings;
     integrationName?: string;
@@ -138,6 +148,8 @@ export default class RoktManager {
     private initialized: boolean = false;
     private isShoppableAdsLoaded: boolean = false;
     private stopRouteChangeWatch: (() => void) | null = null;
+    // Checkout intent raised before the kit attached: latest per kind.
+    private pendingCheckoutIntents: Array<{ signal: ICheckoutIntentSignal; pathname: string }> = [];
 
     // Keys this manager's route subscription, so a re-executed bundle's manager replaces
     // it while a second named instance keeps its own.
@@ -232,6 +244,7 @@ export default class RoktManager {
         this.kit = kit;
 
         this.watchRouteChanges();
+        this.flushCheckoutIntents();
 
         if (kit.settings?.accountId) {
             this.store.setRoktAccountId(kit.settings.accountId);
@@ -286,6 +299,69 @@ export default class RoktManager {
         }
     }
 
+    // Checkout intent is off unless the flag is on, and under opt-out, any Rokt
+    // privacy launcher option, or Global Privacy Control.
+    public isCheckoutIntentSuppressed(): boolean {
+        const flags = this.store?.SDKConfig?.flags;
+        if (!flags || flags[Constants.FeatureFlags.AutoButtonTracking] !== true || !this.store.isEnabled) {
+            return true;
+        }
+        const options = this.launcherOptions || {};
+        if (options.noFunctional || options.noTargeting || options.doNotShareOrSell) {
+            return true;
+        }
+        const nav = typeof navigator === 'undefined' ? undefined : (navigator as Navigator & { globalPrivacyControl?: boolean });
+        return !!nav && nav.globalPrivacyControl === true;
+    }
+
+    // Reads `this.kit` at call time; before a kit attaches the signal is buffered
+    // with the path it was raised on.
+    public notifyCheckoutIntent(signal: ICheckoutIntentSignal, pathname: string = window.location.pathname): void {
+        if (this.isCheckoutIntentSuppressed()) {
+            return;
+        }
+
+        const kit = this.kit;
+        if (!kit) {
+            this.pendingCheckoutIntents = this.pendingCheckoutIntents
+                .filter(pending => pending.signal.kind !== signal.kind)
+                .concat({ signal, pathname })
+                .slice(-CHECKOUT_INTENT_BUFFER_LIMIT);
+            return;
+        }
+
+        try {
+            if (isFunction(kit.onCheckoutIntent)) {
+                kit.onCheckoutIntent(signal);
+            }
+        } catch (e) {
+            this.logger?.error(
+                `RoktManager: Error in onCheckoutIntent: ${getErrorMessage(e)}`
+            );
+        }
+    }
+
+    public discardCheckoutIntents(): void {
+        this.pendingCheckoutIntents = [];
+    }
+
+    // Replays recent buffered signals raised on the current page, oldest first.
+    private flushCheckoutIntents(): void {
+        const pending = this.pendingCheckoutIntents;
+        this.pendingCheckoutIntents = [];
+
+        const now = Date.now();
+        const pathname = window.location.pathname;
+        pending
+            .filter(
+                ({ signal, pathname: signalPathname }) =>
+                    now - signal.t < CHECKOUT_INTENT_MAX_AGE_MS &&
+                    signalPathname === pathname
+            )
+            .sort((a, b) => a.signal.t - b.signal.t)
+            .forEach(({ signal }) => this.notifyCheckoutIntent(signal));
+    }
+
     private isAutoLogPageViewEnabled(): boolean {
         return (
             this.store?.SDKConfig?.flags?.[

package/src/store.ts

@@ -153,6 +153,7 @@ export interface IFeatureFlags {
     'captureIntegrationSpecificIds.V2'?: string;
     astBackgroundEvents?: boolean;
     autoLogPageView?: boolean;
+    autoButtonTracking?: boolean;
 }
 
 // Temporary Interface until Store can be refactored as a class
@@ -776,7 +777,8 @@ export function processFlags(config: SDKInitConfig): IFeatureFlags {
         CaptureIntegrationSpecificIds,
         CaptureIntegrationSpecificIdsV2,
         AstBackgroundEvents,
-        AutoLogPageView
+        AutoLogPageView,
+        AutoButtonTracking,
     } = Constants.FeatureFlags;
 
     if (!config.flags) {
@@ -798,6 +800,7 @@ export function processFlags(config: SDKInitConfig): IFeatureFlags {
     flags[CaptureIntegrationSpecificIdsV2] = (config.flags[CaptureIntegrationSpecificIdsV2] || 'none');
     flags[AstBackgroundEvents] = config.flags[AstBackgroundEvents] === 'True';
     flags[AutoLogPageView] = config.flags[AutoLogPageView] === 'True';
+    flags[AutoButtonTracking] = config.flags[AutoButtonTracking] === 'True';
     return flags;
 }