@mparticle/web-sdk 3.26.1 → 3.28.0

package/src/buttonTracking/buttonTracker.ts

@@ -16,7 +16,7 @@ import {
     classifyPaymentFrame,
     PaymentFrameFamily,
 } from './checkoutIntent';
-import { findControl, isExcludedPath } from './controls';
+import { findControl, findRoleControl, isExcludedPath } from './controls';
 
 // 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.
@@ -26,13 +26,12 @@ const THROTTLE_MS = 2000;
 const SUBMIT_AFTER_COMMIT_CLICK_MS = 1000;
 // Apple Pay must begin inside the tap's own handler, so the tap is this recent.
 const APPLE_PAY_AFTER_CLICK_MS = 1000;
-const PATH_LIMIT = 12;
+// How far up from the clicked element a control is looked for. Checkout intent
+// keeps findControl's own 12; logging looks further, past deep product cards.
+const PATH_LIMIT = 20;
 // A ceiling, not a dedupe: a held Enter key or browser automation fires a
 // trusted click per repeat, and each one is forwarded to every kit.
 const PAGE_EVENT_LIMIT = 100;
-// A click uploads at once. Taps that follow it this quickly are held and share
-// one upload once they stop.
-const UPLOAD_DEBOUNCE_MS = 100;
 
 interface IBtnState {
     tracker?: ButtonTracker;
@@ -174,10 +173,6 @@ export class ButtonTracker {
     private pageEvents = 0;
     // Clicks read at dispatch and waiting for the next paint.
     private pending: Array<() => void> = [];
-    private uploadTimerId: ReturnType<typeof setTimeout> | null = null;
-    private uploadHeld = false;
-    // Set while the page is left, when the SDK's exit upload sends the queue.
-    private leaving = false;
 
     constructor(mpInstance: IMParticleWebSDKInstance) {
         this.mpInstance = mpInstance;
@@ -321,7 +316,6 @@ export class ButtonTracker {
         this.lastSent = {};
         this.pagePath = null;
         this.pageEvents = 0;
-        this.cancelUpload();
     }
 
     private enqueue(delivery: () => void): void {
@@ -347,14 +341,8 @@ export class ButtonTracker {
             event.type === 'pagehide' ||
             document.visibilityState === 'hidden'
         ) {
-            this.leaving = true;
-            try {
-                this.drain();
-            } finally {
-                this.leaving = false;
-            }
-            // The SDK's exit upload sends the queue, held taps included.
-            this.cancelUpload();
+            // The SDK's exit upload then sends these clicks with the queue.
+            this.drain();
         }
     };
 
@@ -411,12 +399,18 @@ export class ButtonTracker {
                 : [];
             const excluded = isExcludedPath(path);
             const control = excluded ? undefined : findControl(path, true);
-            if (control) {
+            const logged =
+                control ||
+                (excluded
+                    ? undefined
+                    : findControl(path, true, PATH_LIMIT) ||
+                      findRoleControl(path, PATH_LIMIT));
+            if (logged) {
                 // With links alone, only an anchor can be logged.
                 click =
                     logsEvents &&
-                    (this.logButtons || control.matches('a[href]'))
-                        ? describeButtonClick(control, path)
+                    (this.logButtons || logged.matches('a[href]'))
+                        ? describeButtonClick(logged, path)
                         : undefined;
                 if (click) {
                     asLink = this.logLinks && isLinkClick(click);
@@ -428,15 +422,17 @@ export class ButtonTracker {
                         !asLink &&
                         !(
                             click.linkType === 'internal' &&
-                            control.matches('a[href]:not([role="button"])')
+                            logged.matches('a[href]:not([role="button"])')
                         );
                     if (!asLink && !asButton) {
                         click = undefined;
                     }
                 }
                 if (click && click.checked !== undefined) {
-                    box = control as HTMLInputElement;
+                    box = logged as HTMLInputElement;
                 }
+            }
+            if (control) {
                 // Checkout intent is only worked out when the kit can use it.
                 const intent = signalsKit
                     ? classifyIntent(control, pathname)
@@ -538,56 +534,13 @@ export class ButtonTracker {
         this.pageEvents++;
         // Restarts an expired session, as public logEvent() and page views do.
         this.mpInstance._SessionManager.resetSessionTimer();
-        const queued = this.queuedForUpload();
+        // No upload of its own, which a click that opens another page would
+        // cancel: with batching on, the next batch or the exit upload sends it.
         this.mpInstance._Events.logEvent(
             asLink
                 ? buildLinkClickEvent(click, pathname)
                 : buildButtonClickEvent(click, pathname)
         );
-        // Only a click waiting for the batch interval is sent early: a held
-        // one goes out when released, and with batching off it already has.
-        // A checkbox or radio waits for the batch, since choosing an option
-        // doesn't leave the page the way a confirm click can.
-        if (
-            !this.leaving &&
-            click.checked === undefined &&
-            this.queuedForUpload() > queued
-        ) {
-            this.uploadNow();
-        }
-    }
-
-    // Events waiting in the upload queue for the next batch interval.
-    private queuedForUpload(): number {
-        const uploader = this.mpInstance._APIClient.uploader;
-        return uploader ? uploader.eventsQueuedForProcessing.length : 0;
-    }
-
-    // Uploads a click without waiting for the batch interval. A tap inside the
-    // wait after the last one is held, and each restarts the wait, so a burst
-    // after the first click goes out in one request once the taps stop.
-    private uploadNow(): void {
-        if (this.uploadTimerId === null) {
-            this.mpInstance.upload();
-        } else {
-            clearTimeout(this.uploadTimerId);
-            this.uploadHeld = true;
-        }
-        this.uploadTimerId = setTimeout(() => {
-            this.uploadTimerId = null;
-            if (this.uploadHeld) {
-                this.uploadHeld = false;
-                this.mpInstance.upload();
-            }
-        }, UPLOAD_DEBOUNCE_MS);
-    }
-
-    private cancelUpload(): void {
-        if (this.uploadTimerId !== null) {
-            clearTimeout(this.uploadTimerId);
-            this.uploadTimerId = null;
-        }
-        this.uploadHeld = false;
     }
 
     private emit(

package/src/buttonTracking/checkoutIntent.ts

@@ -17,7 +17,25 @@ export type CheckoutIntentKind =
     | 'frame'
     | 'cart';
 
-const checkoutPath = /(?:^|\/)(?:checkouts?|payment|order|kasse|paiement|commander?|pago)(?:\/|$)/i;
+// A checkout segment may name its kind or its version, as /express-checkout, /checkout-v2 and /checkout-external do.
+// Other hyphenated words make it a content slug, such as /help/checkout-faq or /products/self-checkout-kiosk.
+const CHECKOUT_SEGMENT =
+    '(?:(?:express|guest|quick|secure|complete|one-?page|single-?page|mobile)-)?checkouts?' +
+    '(?:-(?:v\\d+|\\d+|flow|external|process|step(?:-\\d+)?))?';
+const checkoutPath = new RegExp(
+    '(?:^|\\/)(?:' + CHECKOUT_SEGMENT + '|payment|order|kasse|paiement|commander?|pago)(?:\\/|$)',
+    'i'
+);
+// A route with a checkout segment itself, not just a payment or order one, which account pages also use.
+const checkoutSegmentPath = new RegExp('(?:^|\\/)' + CHECKOUT_SEGMENT + '(?:\\/|$)', 'i');
+// A confirmation page under a checkout route, such as /checkout/thankyou/<order> or /checkouts/<token>/thank_you, comes
+// after the confirm click. "Complete" and "success" mark one only as the last word of a segment, so /complete-checkout
+// and /checkout/complete-registration stay checkout routes.
+const confirmationPath = /(?:^|[\/_-])(?:thank[-_]?you|thanks|confirmation|confirmed|receipt|received)(?:[\/_-]|$)|(?:^|[\/_-])(?:complete|completed|success)(?:\/|$)/i;
+// A bare "Register" creates an account, rather than placing the order, on a checkout's sign-in or account step or in a
+// form that asks for a password.
+const bareRegister = /^register(?: now)?$/;
+const accountStepPath = /(?:^|\/)(?:register|registration|login|log-in|signin|sign-in|signup|sign-up|account|create-account)(?:\/|$)/i;
 // English look-alikes are whole words; the other languages stay substring
 // matches, since several of them do not separate words with spaces.
 const englishExclusions = new RegExp(
@@ -63,7 +81,7 @@ const linkCommits = new RegExp(
         ')$'
 );
 const routeGatedCommits = new RegExp(
-    '^(?:buy now|purchase|jetzt kaufen|kaufen|commander|(?:passer|valider) (?:la |ma )?commande|finalizar (?:la |mi )?compra|' +
+    '^(?:buy now|purchase|register(?: now)?|complete (?:my |your )?registration|jetzt kaufen|kaufen|commander|(?:passer|valider) (?:la |ma )?commande|finalizar (?:la |mi )?compra|' +
         'comprar ahora|acquista ora|nu kopen|今すぐ購入|購入する|この内容で申し込む)$'
 );
 const steps = new RegExp(
@@ -81,6 +99,9 @@ const steps = new RegExp(
         ].join('|') +
         ')$'
 );
+// "Save and continue" also saves profile, address and card forms, so it is a step only on a checkout segment's route
+// that isn't an account or confirmation page.
+const routeGatedSteps = /^save and continue$/;
 const CART_NOUN = '(?:(?:my|your|the) )?(?:shopping )?(?:cart|bag|basket)';
 // "Add to bag" and "Add 2 to cart": a click that puts something in the cart.
 const addToCartLabels = new RegExp('^add(?: [^ ]+){0,5} to ' + CART_NOUN + '$');
@@ -156,7 +177,9 @@ const EDGE =
 const EDGE_SYMBOLS = new RegExp('^' + EDGE + '|' + EDGE + '$', 'g');
 
 function getIntentRouteClass(pathname: string): 'checkout_path' | 'other' {
-    return checkoutPath.test(pathname) ? 'checkout_path' : 'other';
+    return checkoutPath.test(pathname) && !confirmationPath.test(pathname)
+        ? 'checkout_path'
+        : 'other';
 }
 
 const SEPARATORS = /[-_|·•]/g;
@@ -262,16 +285,40 @@ export interface ICheckoutIntent {
     adds?: true;
 }
 
-// "Buy now" and "Purchase" count only on a checkout route, and never on a plain
-// link, which is navigation.
-function isCommitLabel(text: string, isLink: boolean, pathname: string): boolean {
+// Every field the browser counts as the form's own, form-attribute fields included. Read through the native getter
+// where the browser has one, since a field named "elements" shadows the form's own property.
+function formFields(form: HTMLFormElement): ArrayLike<Element> {
+    const descriptor = Object.getOwnPropertyDescriptor(HTMLFormElement.prototype, 'elements');
+    return descriptor && descriptor.get ? descriptor.get.call(form) : form.elements;
+}
+
+// The form a button or input submits, which its form attribute can name from outside it.
+function createsAccount(control: Element, pathname: string): boolean {
+    const form =
+        control instanceof HTMLButtonElement || control instanceof HTMLInputElement
+            ? control.form
+            : control.closest('form');
+    return (
+        accountStepPath.test(pathname) ||
+        (!!form &&
+            Array.prototype.some.call(
+                formFields(form),
+                (field: Element) => field instanceof HTMLInputElement && field.type === 'password'
+            ))
+    );
+}
+
+// "Buy now", "Purchase" and "Register" count only on a checkout route that isn't a
+// confirmation page, and never on a plain link, which is navigation.
+function isCommitLabel(text: string, isLink: boolean, pathname: string, control: Element): boolean {
     if (isLink) {
         return linkCommits.test(text);
     }
     return (
         commits.test(text) ||
         (routeGatedCommits.test(text) &&
-            getIntentRouteClass(pathname) === 'checkout_path')
+            getIntentRouteClass(pathname) === 'checkout_path' &&
+            !(bareRegister.test(text) && createsAccount(control, pathname)))
     );
 }
 
@@ -311,7 +358,7 @@ export function classifyIntent(
         return cart;
     }
     const isLink = control.matches('a[href]:not([role="button"])');
-    if (cores.some(text => isCommitLabel(text, isLink, pathname))) {
+    if (cores.some(text => isCommitLabel(text, isLink, pathname, control))) {
         return { kind: 'commit', source: 'label' };
     }
     if (
@@ -332,7 +379,14 @@ export function classifyIntent(
         if (isButton && walletBrands.test(text)) {
             return { kind: 'wallet', source: 'brand' };
         }
-        if (steps.test(text)) {
+        if (
+            steps.test(text) ||
+            (isButton &&
+                routeGatedSteps.test(text) &&
+                checkoutSegmentPath.test(pathname) &&
+                !confirmationPath.test(pathname) &&
+                !accountStepPath.test(pathname))
+        ) {
             return { kind: 'checkout_step', source: 'label' };
         }
     }

package/src/buttonTracking/controls.ts

@@ -283,7 +283,8 @@ export function isExcludedPath(path: Array<EventTarget | null>): boolean {
 // found the path not excluded passes `included` so the walk runs once.
 export function findControl(
     path: Array<EventTarget | null>,
-    included = false
+    included = false,
+    limit = 12
 ): Element | undefined {
     if (!included && isExcludedPath(path)) {
         return undefined;
@@ -291,7 +292,7 @@ export function findControl(
     let control: Element | undefined;
     let option: Element | undefined;
     let picked = false;
-    for (const target of path.slice(0, 12)) {
+    for (const target of path.slice(0, limit)) {
         if (control) {
             break;
         }
@@ -321,6 +322,57 @@ export function findControl(
     return control;
 }
 
+// Roles that act as controls without being buttons or links: pickers, tabs,
+// options and links run by script. A role can list fallbacks, so any of its
+// tokens counts.
+const ROLE_CONTROL =
+    '[role~="radio"], [role~="menuitemradio"], [role~="checkbox"], [role~="menuitemcheckbox"], ' +
+    '[role~="switch"], [role~="option"], [role~="tab"], [role~="link"]';
+
+const TYPING_FIELD =
+    'input:not([type="submit"]):not([type="button"]):not([type="image"]):not([type="reset"]):not([type="radio"]):not([type="checkbox"]), ' +
+    'textarea, select, ' +
+    EDITABLE;
+
+// The nearest role control on the click path, for logging the click alone:
+// checkout intent and payment choices only ever read what findControl finds.
+// None when anything disabled sits on the path, so a role control around or
+// inside a disabled control never logs the click it suppressed.
+export function findRoleControl(
+    path: Array<EventTarget | null>,
+    limit: number
+): Element | undefined {
+    const entries = path
+        .slice(0, limit)
+        .filter((target): target is Element => target instanceof Element);
+    if (
+        entries.some(
+            target =>
+                target.matches(':disabled, [aria-disabled="true"]') ||
+                (target.classList.contains('disabled') &&
+                    isWalletNamed(target))
+        )
+    ) {
+        return undefined;
+    }
+    for (const target of entries) {
+        if (target.matches(ROLE_CONTROL)) {
+            // A typing field, or anything in an editable region, takes typing
+            // whatever role it carries.
+            return target.matches(TYPING_FIELD) ||
+                hasComposedAncestor(target, EDITABLE)
+                ? undefined
+                : target;
+        }
+        // A click in a typing field belongs to the field, not to the role
+        // control around it.
+        if (target.matches(TYPING_FIELD)) {
+            return undefined;
+        }
+    }
+    return undefined;
+}
+
 // Text that may hold what a shopper typed or what the page opted out: form
 // fields, editable regions, and anything under data-mp-no-track. `own` is a
 // box the element labels, which holds no typing of its own.

package/src/buttonTracking/labelMasking.ts

@@ -42,3 +42,9 @@ export function maskLabel(raw: string | null | undefined): string | undefined {
         .trim();
     return masked || undefined;
 }
+
+// Masks numbers and amounts in any script as '#', or undefined where the browser
+// can't see every script's digits.
+export function maskNumbers(text: string): string | undefined {
+    return digitPatterns ? text.replace(digitPatterns.number, '#') : undefined;
+}

package/src/pageUrl.ts

@@ -1,13 +1,18 @@
 import { isAllowedQueryParam } from './pageViewTracker';
+import { pagePath, pageUrlPath } from './pathMasking';
 import { getHref, valueof } from './utils';
 
 // The one rule for a URL that leaves the SDK, shared with kits through
-// `mParticle._cleanUrl`. `path` keeps scheme, host and path. `full` adds the
+// `mParticle._cleanUrl`. `path` keeps scheme, host and path, with any path
+// segment that can single out one shopper as `*` (see pageUrlPath). `full` adds the
 // query params an auto page view captures by default and the campaign
-// attribution params, then the fragment.
+// attribution params, then the fragment, a hash route's path masked the same way.
 export const UrlMode = {
     Path: 'path',
     Full: 'full',
+    // A path for a log or an error report, masked with the click path's fuller
+    // rules, since no output reads it as a page.
+    Report: 'report',
 } as const;
 
 export type UrlMode = valueof<typeof UrlMode>;
@@ -79,6 +84,37 @@ export const EXCLUDED_URL_FRAGMENT_PARAMS: string[] = EXCLUDED_URL_QUERY_PARAMS.
 const URL_VALUED_QUERY_PARAMS: string[] = ['ref', 'referrer'];
 
 const USERINFO = /^((?:[a-z][a-z0-9+.-]*:)?\/\/)[^/]*@/i;
+const ORIGIN = /^(?:[a-z][a-z0-9+.-]*:)?\/\/[^/]*/i;
+
+// Only a URL or a path is masked. A bare value, such as `ref=spring2024`, is a
+// code rather than a page, and stays as written.
+const maskPath = (
+    url: string,
+    mask: (pathname: string) => string = pageUrlPath
+): string => {
+    const origin = ORIGIN.exec(url);
+    if (origin) {
+        return origin[0] + mask(url.slice(origin[0].length));
+    }
+    return url.charAt(0) === '/' ? mask(url) : url;
+};
+
+// A hash route keeps its `#` or `#!` and has its path masked as the URL's own.
+// The `&` pairs or flags after the path lose the OAuth/OIDC ones, as a bare
+// fragment's pairs do.
+const maskRoute = (route: string): string => {
+    const prefix = /^#!?/.exec(route)[0];
+    const pairsStart = route.indexOf('&');
+    const pathEnd = pairsStart === -1 ? route.length : pairsStart;
+    const pairs = route
+        .slice(pathEnd)
+        .split('&')
+        .slice(1)
+        .filter(keepsFragmentPair)
+        .map(pair => `&${pair}`)
+        .join('');
+    return prefix + pageUrlPath(route.slice(prefix.length, pathEnd)) + pairs;
+};
 
 const decodeQueryComponent = (component: string): string =>
     decodeURIComponent(component.replace(/\+/g, ' '));
@@ -140,21 +176,31 @@ const keepsFragmentPair = (pair: string): boolean => {
 const cleanFragment = (hash: string): string => {
     const queryStart = hash.indexOf('?');
     const route = queryStart === -1 ? hash : hash.slice(0, queryStart);
+    // `#/…`, `#!…`, or a fragment with a `/` before any `&` or `?`, as
+    // `#orders/12345678` is in routers that drop the leading slash.
+    // A `/` counts only before any `=`, so a bare pair such as
+    // `#access_token=abc/def` is never read as a route.
+    const isHashRoute = /^#!|^#[^?&=]*\//.test(hash);
     const isRoute =
-        /^#[/!]/.test(hash) || (queryStart !== -1 && route.indexOf('=') === -1);
+        isHashRoute || (queryStart !== -1 && route.indexOf('=') === -1);
 
     if (isRoute && queryStart !== -1) {
         const query = cleanQuery(hash.slice(queryStart + 1));
-        return route + (query ? `?${query}` : '');
+        return maskRoute(route) + (query ? `?${query}` : '');
     }
 
+    // A plain anchor such as `#reviews` names a part of the page, not a route.
     if (hash.indexOf('=') === -1) {
-        return hash;
+        return isHashRoute ? maskRoute(hash) : hash;
     }
 
+    // A hash route's path leads its pairs, as in `#/cb&tab=2`.
     const pairs = hash
         .slice(1)
         .split('&')
+        .map((pair, i) =>
+            i === 0 && isHashRoute ? maskRoute(`#${pair}`).slice(1) : pair
+        )
         .filter(keepsFragmentPair)
         .join('&');
     return pairs ? `#${pairs}` : '';
@@ -172,10 +218,13 @@ export const cleanUrl = (href: string, mode: UrlMode): string => {
     const hash = hashStart === -1 ? '' : href.slice(hashStart);
     const beforeHash = hashStart === -1 ? href : href.slice(0, hashStart);
     const queryStart = beforeHash.indexOf('?');
-    const path = (queryStart === -1
-        ? beforeHash
-        : beforeHash.slice(0, queryStart)
-    ).replace(USERINFO, '$1');
+    const path = maskPath(
+        (queryStart === -1
+            ? beforeHash
+            : beforeHash.slice(0, queryStart)
+        ).replace(USERINFO, '$1'),
+        mode === UrlMode.Report ? pagePath : pageUrlPath
+    );
 
     if (mode !== UrlMode.Full) {
         return path;

package/src/pageViewTracker.ts

@@ -2,6 +2,7 @@ import { IMParticleWebSDKInstance } from './mp-instance';
 import { BaseEvent } from './sdkRuntimeModels';
 import { EventType, MessageType } from './types';
 import { Dictionary, getHref, hasOwnProp, queryStringParser } from './utils';
+import { pagePath, pageUrlPath } from './pathMasking';
 import {
     subscribeToRouteChange,
     supportsHistoryTracking,
@@ -318,7 +319,8 @@ export const buildPageViewEvent = ({
         ...paramsToAttributes(params),
         hostname,
         title,
-        path,
+        // Masked here, not in the page snapshot, whose raw path tells one page from the next.
+        path: pageUrlPath(path),
         ...autoPageViewAttribute(isAutoPageView),
     },
     eventType: EventType.Unknown,
@@ -422,7 +424,9 @@ const describePage = (page: IPageSnapshot | null): string => {
     }
 
     const names = page.params.map(({ name }) => name);
-    return names.length ? `${page.path} (params: ${names.join()})` : page.path;
+    // A log line is read by no output, so it takes the click path's fuller rules.
+    const path = pagePath(page.path);
+    return names.length ? `${path} (params: ${names.join()})` : path;
 };
 
 // ---------------------------------------------------------------------------
@@ -657,10 +661,12 @@ export class PageViewTracker {
             isAutoPageView: this.isAutoPageView,
         });
 
+        // A title can name the shopper or an order, so it stays out of the log
+        // line, for the same reason describePage omits param values.
         this.log(
             `[fire] deferred flush -> _Events.logEvent(PageView) (page: ${describePage(
                 page
-            )}, title: ${title})`
+            )})`
         );
 
         this.mpInstance._Events.logEvent(event);