@mparticle/web-sdk 3.17.0 → 3.18.0

package/src/buttonTracking/buttonTracker.ts

@@ -0,0 +1,376 @@
+import { IMParticleWebSDKInstance } from '../mp-instance';
+import { isFunction } from '../utils';
+import { buildButtonClickEvent } from './buttonClickEvent';
+import { describeButtonClick, IButtonClick } from './buttonDescription';
+import {
+    CheckoutIntentKind,
+    classifyIntentControl,
+    classifyIntentFrame,
+} from './checkoutIntent';
+
+// State lives on `window`, like APV, so a re-executed bundle never doubles the
+// listeners. Inspect `window.__mpBtn__` in a console to see if one is live.
+export const WIN_BTN_KEY = '__mpBtn__';
+
+const THROTTLE_MS = 2000;
+const SUBMIT_AFTER_COMMIT_CLICK_MS = 1000;
+const PATH_LIMIT = 12;
+const EVENT_DEDUP_MS = 1000;
+const PAGE_EVENT_LIMIT = 50;
+
+interface IBtnState {
+    tracker?: ButtonTracker;
+}
+
+type WindowWithBtn = Window & {
+    [WIN_BTN_KEY]?: IBtnState;
+};
+
+export interface IButtonTrackerOptions {
+    // The Rokt kit signal only runs when this init configures a Rokt kit.
+    hasRoktKit: boolean;
+}
+
+const btnWindow = (): WindowWithBtn | null =>
+    typeof window === 'undefined' ? null : (window as WindowWithBtn);
+
+export const getActiveButtonTracker = (): ButtonTracker | undefined => {
+    const win = btnWindow();
+    const state = win ? win[WIN_BTN_KEY] : undefined;
+    return state ? state.tracker : undefined;
+};
+
+// Stops whichever tracker is active, including one from an earlier bundle load.
+export const resetButtonTracking = (): void => {
+    const win = btnWindow();
+    if (!win) {
+        return;
+    }
+    const active = getActiveButtonTracker();
+    if (active) {
+        active.teardown();
+    }
+    win[WIN_BTN_KEY] = {};
+};
+
+// Runs once the browser has painted the page's response to the interaction, so
+// describing and logging a click never delays that paint.
+const afterNextPaint = (fn: () => void): void => {
+    if (
+        isFunction(window.requestAnimationFrame) &&
+        document.visibilityState !== 'hidden'
+    ) {
+        requestAnimationFrame(() => {
+            setTimeout(fn, 0);
+        });
+    } else {
+        setTimeout(fn, 0);
+    }
+};
+
+const CAPTURE_PASSIVE: AddEventListenerOptions = {
+    capture: true,
+    passive: true,
+};
+const PASSIVE: AddEventListenerOptions = { passive: true };
+
+// Logs every button click as an mParticle event, and hands checkout intent to the
+// Rokt kit as a frozen {kind, t}. Submits and wallet frame focus feed the kit only.
+export class ButtonTracker {
+    private readonly mpInstance: IMParticleWebSDKInstance;
+    private active = false;
+    private hasRoktKit = false;
+    // Bumped on reset so classification queued before it is dropped.
+    private generation = 0;
+    private lastCommitClick = -Infinity;
+    private lastSent: { [kind: string]: { t: number; pathname: string } } = {};
+    private pagePath: string | null = null;
+    private pageEvents = 0;
+    private lastEvent: { [key: string]: number } = {};
+    // Clicks read at dispatch and waiting for the next paint.
+    private pending: Array<() => void> = [];
+
+    constructor(mpInstance: IMParticleWebSDKInstance) {
+        this.mpInstance = mpInstance;
+    }
+
+    public get isActive(): boolean {
+        return this.active;
+    }
+
+    public init(options: IButtonTrackerOptions): void {
+        const win = btnWindow();
+        if (!win) {
+            return;
+        }
+
+        const previous = getActiveButtonTracker();
+        if (previous) {
+            previous.teardown();
+        }
+        if (this.active) {
+            this.teardown();
+        }
+        this.hasRoktKit = options.hasRoktKit;
+
+        if (!this.eventsEnabled() && this.isKitSuppressed()) {
+            this.log('opted out, not starting');
+            return;
+        }
+
+        win.document.addEventListener('click', this.onEvent, CAPTURE_PASSIVE);
+        win.document.addEventListener('submit', this.onEvent, CAPTURE_PASSIVE);
+        win.addEventListener('blur', this.onEvent, PASSIVE);
+        win.addEventListener('pageshow', this.onPageShow, PASSIVE);
+        win.addEventListener('beforeunload', this.onHide, CAPTURE_PASSIVE);
+        win.addEventListener('pagehide', this.onHide, CAPTURE_PASSIVE);
+        win.document.addEventListener(
+            'visibilitychange',
+            this.onHide,
+            CAPTURE_PASSIVE
+        );
+
+        this.active = true;
+        if (!win[WIN_BTN_KEY]) {
+            win[WIN_BTN_KEY] = {};
+        }
+        win[WIN_BTN_KEY].tracker = this;
+        this.log('listening');
+    }
+
+    public teardown(): void {
+        const win = btnWindow();
+        if (win) {
+            win.document.removeEventListener('click', this.onEvent, true);
+            win.document.removeEventListener('submit', this.onEvent, true);
+            win.removeEventListener('blur', this.onEvent);
+            win.removeEventListener('pageshow', this.onPageShow);
+            win.removeEventListener('beforeunload', this.onHide, true);
+            win.removeEventListener('pagehide', this.onHide, true);
+            win.document.removeEventListener(
+                'visibilitychange',
+                this.onHide,
+                true
+            );
+
+            const state = win[WIN_BTN_KEY];
+            if (state && state.tracker === this) {
+                state.tracker = undefined;
+            }
+        }
+        this.active = false;
+        // Signals not yet handed to a kit go with the tracker.
+        this.clearPending();
+    }
+
+    // Drops queued classification, commit timing and buffered signals, so
+    // nothing captured before an opt-out is delivered after an opt-in.
+    public clearPending(): void {
+        this.reset();
+        const roktManager = this.mpInstance._RoktManager;
+        if (roktManager) {
+            roktManager.discardCheckoutIntents();
+        }
+    }
+
+    private reset(): void {
+        this.generation++;
+        this.pending = [];
+        this.lastCommitClick = -Infinity;
+        this.lastSent = {};
+        this.pagePath = null;
+        this.pageEvents = 0;
+        this.lastEvent = {};
+    }
+
+    private enqueue(delivery: () => void): void {
+        this.pending.push(delivery);
+        if (this.pending.length === 1) {
+            afterNextPaint(this.drain);
+        }
+    }
+
+    private readonly drain = (): void => {
+        const queue = this.pending;
+        this.pending = [];
+        queue.forEach(delivery => delivery());
+    };
+
+    // A click that navigates away can unload the page before the next paint, so
+    // anything waiting is delivered as the page is hidden or left. The capture
+    // listeners run before the SDK's own upload on the same events, including
+    // beforeunload, the first of them.
+    private readonly onHide = (event: Event): void => {
+        if (
+            event.type === 'beforeunload' ||
+            event.type === 'pagehide' ||
+            document.visibilityState === 'hidden'
+        ) {
+            this.drain();
+        }
+    };
+
+    private readonly onPageShow = (event: PageTransitionEvent): void => {
+        // A page restored from the back-forward cache starts fresh.
+        if (event.persisted) {
+            this.reset();
+        }
+    };
+
+    private readonly onEvent = (event: Event): void => {
+        try {
+            this.observe(event);
+        } catch (e) {
+            this.log('[error] event handler threw: ' + e);
+        }
+    };
+
+    private observe(event: Event): void {
+        if (!this.active || !event.isTrusted) {
+            return;
+        }
+        const layer = event.type;
+        const logsEvents = layer === 'click' && this.eventsEnabled();
+        if (!logsEvents && this.isKitSuppressed()) {
+            return;
+        }
+
+        const t = Date.now();
+        const pathname = window.location.pathname;
+
+        // The button is read now, while the click is still being dispatched:
+        // this capture listener runs before the page's own handlers, so a
+        // button that disables or relabels itself is seen as it was clicked.
+        // Logging and the kit hand-off wait for the next paint.
+        let click: IButtonClick | undefined;
+        let kind: CheckoutIntentKind | undefined;
+        let unconfirmedCommit = false;
+        if (layer === 'click') {
+            // The composed path is only populated during dispatch.
+            const path = isFunction(event.composedPath)
+                ? event.composedPath().slice(0, PATH_LIMIT)
+                : [];
+            click = logsEvents ? describeButtonClick(path) : undefined;
+            kind = classifyIntentControl(path, pathname);
+        } else if (layer === 'submit') {
+            const submitter = (event as Event & { submitter?: Element | null })
+                .submitter;
+            // A form submitted without a submitter only counts right after a
+            // commit click, which is known once that click is delivered.
+            kind = submitter
+                ? classifyIntentControl([submitter], pathname)
+                : 'commit';
+            unconfirmedCommit = !submitter;
+        }
+
+        const generation = this.generation;
+        this.enqueue(() => {
+            if (generation !== this.generation) {
+                return;
+            }
+            try {
+                if (layer === 'blur') {
+                    // Read after the blur settles: some browsers have not moved
+                    // focus into the frame yet when the window blurs.
+                    kind = classifyIntentFrame(document.activeElement, window);
+                } else if (
+                    unconfirmedCommit &&
+                    t - this.lastCommitClick > SUBMIT_AFTER_COMMIT_CLICK_MS
+                ) {
+                    kind = undefined;
+                }
+                if (click && logsEvents) {
+                    this.logClick(click, t, pathname);
+                }
+                if (kind) {
+                    this.emit(kind, layer, t, pathname);
+                }
+            } catch (e) {
+                this.log('[error] delivery threw: ' + e);
+            }
+        });
+    }
+
+    // One event per identical button every second, and at most 50 per page.
+    private logClick(click: IButtonClick, t: number, pathname: string): void {
+        if (!this.eventsEnabled()) {
+            return;
+        }
+        if (pathname !== this.pagePath) {
+            this.pagePath = pathname;
+            this.pageEvents = 0;
+            this.lastEvent = {};
+        }
+        if (this.pageEvents >= PAGE_EVENT_LIMIT) {
+            return;
+        }
+        const key = [
+            click.label,
+            click.ariaLabel,
+            click.icon,
+            click.elementId,
+            click.elementName,
+            click.testId,
+            click.element,
+            click.type,
+        ].join('|');
+        const last = this.lastEvent[key];
+        if (last !== undefined && t - last < EVENT_DEDUP_MS) {
+            return;
+        }
+        this.lastEvent[key] = t;
+        this.pageEvents++;
+
+        // Restarts an expired session, as public logEvent() and page views do.
+        this.mpInstance._SessionManager.resetSessionTimer();
+        this.mpInstance._Events.logEvent(
+            buildButtonClickEvent(click, pathname)
+        );
+    }
+
+    private emit(
+        kind: CheckoutIntentKind,
+        layer: string,
+        t: number,
+        pathname: string
+    ): void {
+        if (this.isKitSuppressed()) {
+            return;
+        }
+        if (kind === 'commit' && layer === 'click') {
+            this.lastCommitClick = t;
+        }
+
+        const last = this.lastSent[kind];
+        if (last && last.pathname === pathname && t - last.t < THROTTLE_MS) {
+            return;
+        }
+        this.lastSent[kind] = { t, pathname };
+
+        this.mpInstance._RoktManager.notifyCheckoutIntent(
+            Object.freeze({ kind, t }),
+            pathname
+        );
+    }
+
+    // Events follow the SDK's opt-out like any other event.
+    private eventsEnabled(): boolean {
+        const store = this.mpInstance._Store;
+        return !!store && store.isEnabled;
+    }
+
+    // The Rokt manager owns the kit's privacy gates: flag, opt-out, launcher
+    // options and Global Privacy Control.
+    private isKitSuppressed(): boolean {
+        const roktManager = this.mpInstance._RoktManager;
+        return (
+            !this.hasRoktKit ||
+            !roktManager ||
+            roktManager.isCheckoutIntentSuppressed()
+        );
+    }
+
+    private log(message: string): void {
+        this.mpInstance.Logger.verbose('mParticle button tracking: ' + message);
+    }
+}

package/src/{checkoutIntentClassifier.ts → buttonTracking/checkoutIntent.ts}

@@ -1,5 +1,12 @@
-// Classifies a click, submit or frame focus as checkout intent. Reads only short
-// control labels, never form field values, and stores nothing.
+import {
+    CONTROL_SELECTOR,
+    findControl,
+    isRoktElement,
+    isWalletElement,
+} from './controls';
+
+// Classifies a click, submit or frame focus as checkout intent for the Rokt kit.
+// Reads only short control labels, never form field values, and stores nothing.
 export type CheckoutIntentKind =
     | 'commit'
     | 'wallet'
@@ -63,88 +70,62 @@ const frameHosts = new Set([
     'payments.amazon.com',
     'pay.shopify.com',
 ]);
+// Keep these classes ASCII-only in source bytes to avoid mojibake parse failures
+// when a host page forces non-UTF-8 decoding before JavaScript parse.
+const TYPOGRAPHIC_APOSTROPHES = /[\u2019\u2018]/g;
+const CURRENCY_AND_NUMBER_CHARS =
+    /[0-9\uFF10-\uFF19$\u20AC\u00A3\u00A5\uFFE5\u20B9\u5186.,\uFF0C]/g;
 
-const CONTROL_SELECTOR =
-    'button, input[type="submit"], input[type="button"], input[type="image"], [role="button"]';
-
-export function getIntentRouteClass(
-    pathname: string
-): 'checkout_path' | 'other' {
+function getIntentRouteClass(pathname: string): 'checkout_path' | 'other' {
     return checkoutPath.test(pathname) ? 'checkout_path' : 'other';
 }
 
-// Rokt's own placements and frames never count as partner checkout controls.
-function isRoktElement(element: Element): boolean {
-    if (element.closest('[data-core-type], #rokt-controller-frame')) {
-        return true;
-    }
-    const src = element.getAttribute('src');
-    if (src) {
-        try {
-            if (
-                new URL(src, 'https://example.test').pathname.indexOf(
-                    '/wsdk/'
-                ) !== -1
-            ) {
-                return true;
-            }
-        } catch (e) {
-            // An unparseable src is not a Rokt element.
-        }
-    }
-    return false;
-}
-
-function isWalletElement(element: Element): boolean {
-    return element.matches(
-        'apple-pay-button, shop-pay-button, .gpay-button, #AmazonPayButton, [data-amazon-pay-button]'
-    );
-}
-
 function normalize(text: string | null | undefined): string | undefined {
     if (!text || text.length > 128) {
         return undefined;
     }
     return text
         .toLowerCase()
-        .replace(/[’‘]/g, "'")
-        .replace(/[0-9０-９$€£¥￥₹円.,，]/g, '')
+        .replace(TYPOGRAPHIC_APOSTROPHES, "'")
+        .replace(CURRENCY_AND_NUMBER_CHARS, '')
         .replace(/\s+/g, ' ')
         .trim();
 }
 
 // Labels come from aria-label then visible text. Only submit and button inputs
 // have their value read, so a typed field value is never touched.
-function labels(element: Element): string[] {
+function labelSources(element: Element): Array<string | null> {
     if (
         element.children.length > 4 ||
-        element.querySelector('input, select, textarea')
+        element.querySelector('input, select, textarea, [data-mp-no-track]')
     ) {
         return [];
     }
     let text: string | null = null;
-    if (element.tagName.toLowerCase() === 'input') {
-        const typeAttr = element.getAttribute('type');
-        const type = typeAttr ? typeAttr.toLowerCase() : typeAttr;
+    if (element instanceof HTMLInputElement) {
+        const type = element.type;
         if (type === 'submit' || type === 'button') {
-            text = (element as HTMLInputElement).value;
+            text = element.value;
         } else if (type === 'image') {
             text = element.getAttribute('alt');
         }
     } else {
         text = element.textContent;
     }
-    return [
-        normalize(element.getAttribute('aria-label')),
-        normalize(text),
-    ].filter((label): label is string => !!label);
+    return [element.getAttribute('aria-label'), text];
+}
+
+function labels(element: Element): string[] {
+    return labelSources(element)
+        .map(normalize)
+        .filter((label): label is string => !!label);
 }
 
 function classifyLabel(
     text: string,
     button: boolean,
     pathname: string
-): CheckoutIntentKind | undefined {
+): Exclude<CheckoutIntentKind, 'frame'> | undefined {
     if (
         commits.test(text) ||
         (routeGatedCommits.test(text) &&
@@ -161,30 +142,18 @@ function classifyLabel(
     return undefined;
 }
 
-// Walks at most 12 entries of an event's composed path for the nearest control.
 export function classifyIntentControl(
     path: Array<EventTarget | null>,
     pathname: string
 ): CheckoutIntentKind | undefined {
-    let control: Element | undefined;
-    for (const target of path.slice(0, 12)) {
-        if (!(target instanceof Element)) {
-            continue;
-        }
-        if (isRoktElement(target)) {
-            return undefined;
-        }
-        if (
-            !control &&
-            (target.matches(CONTROL_SELECTOR + ', a[href]') ||
-                isWalletElement(target))
-        ) {
-            control = target;
-        }
-    }
-    if (!control || isRoktElement(control)) {
-        return undefined;
-    }
+    const control = findControl(path);
+    return control ? classifyControl(control, pathname) : undefined;
+}
+
+function classifyControl(
+    control: Element,
+    pathname: string
+): Exclude<CheckoutIntentKind, 'frame'> | undefined {
     const texts = labels(control);
     if (texts.some(text => exclusions.test(text))) {
         return undefined;

package/src/buttonTracking/controls.ts

@@ -0,0 +1,92 @@
+import { isFunction } from '../utils';
+
+// Finds the control a click landed on, for both checkout intent and button
+// descriptions. Rokt's own elements, disabled controls and anything under
+// data-mp-no-track are never returned.
+export const CONTROL_SELECTOR =
+    'button, input[type="submit"], input[type="button"], input[type="image"], [role="button"]';
+
+// closest() over the composed tree: slots, parents, then shadow hosts.
+export function hasComposedAncestor(
+    element: Element,
+    selector: string
+): boolean {
+    let node: Element | null = element;
+    while (node) {
+        if (node.matches(selector)) {
+            return true;
+        }
+        const root = isFunction(node.getRootNode)
+            ? (node.getRootNode() as ShadowRoot)
+            : null;
+        node =
+            (node as Element & { assignedSlot?: Element | null })
+                .assignedSlot ||
+            node.parentElement ||
+            (root && root.host) ||
+            null;
+    }
+    return false;
+}
+
+// Rokt's own placements and frames never count as partner checkout controls.
+export function isRoktElement(element: Element): boolean {
+    if (
+        hasComposedAncestor(element, '[data-core-type], #rokt-controller-frame')
+    ) {
+        return true;
+    }
+    const src = element.getAttribute('src');
+    if (src) {
+        try {
+            if (
+                new URL(src, 'https://example.test').pathname.indexOf(
+                    '/wsdk/'
+                ) !== -1
+            ) {
+                return true;
+            }
+        } catch (e) {
+            // An unparseable src is not a Rokt element.
+        }
+    }
+    return false;
+}
+
+export function isWalletElement(element: Element): boolean {
+    return element.matches(
+        'apple-pay-button, shop-pay-button, .gpay-button, #AmazonPayButton, [data-amazon-pay-button]'
+    );
+}
+
+// Walks at most 12 entries of an event's composed path for the nearest control.
+// Rokt elements, disabled controls and anything under data-mp-no-track are skipped.
+export function findControl(
+    path: Array<EventTarget | null>
+): Element | undefined {
+    let control: Element | undefined;
+    for (const target of path.slice(0, 12)) {
+        if (!(target instanceof Element)) {
+            continue;
+        }
+        if (isRoktElement(target) || target.matches('[data-mp-no-track]')) {
+            return undefined;
+        }
+        if (
+            !control &&
+            (target.matches(CONTROL_SELECTOR + ', a[href]') ||
+                isWalletElement(target))
+        ) {
+            control = target;
+        }
+    }
+    if (
+        !control ||
+        isRoktElement(control) ||
+        hasComposedAncestor(control, '[data-mp-no-track]') ||
+        control.matches(':disabled, [aria-disabled="true"]')
+    ) {
+        return undefined;
+    }
+    return control;
+}

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,7 +190,7 @@ const Constants = {
         CaptureIntegrationSpecificIdsV2: 'captureIntegrationSpecificIds.V2',
         AstBackgroundEvents: 'astBackgroundEvents',
         AutoLogPageView: 'autoLogPageView',
-        CheckoutIntent: 'checkoutIntent',
+        AutoButtonTracking: 'autoButtonTracking',
     },
     DefaultInstance: 'default_instance',
     CCPAPurpose: 'data_sale_opt_out',