@mparticle/web-sdk 3.26.0 → 3.27.0

package/src/buttonTracking/checkoutIntent.ts

@@ -17,7 +17,17 @@ 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 checkoutPath = /(?:^|\/)(?:(?:(?:express|guest|quick|secure|complete|one-?page|single-?page|mobile)-)?checkouts?(?:-(?:v\d+|\d+|flow|external|process|step(?:-\d+)?))?|payment|order|kasse|paiement|commander?|pago)(?:\/|$)/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 +73,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(
@@ -156,7 +166,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 +274,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 +347,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 (

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;
 };
 
 // ---------------------------------------------------------------------------

package/src/pathMasking.ts

@@ -0,0 +1,199 @@
+// Masks the parts of a page path that can single out one shopper: pagePath for
+// the path a click logs, pageUrlPath for the page URL and page views every event
+// carries.
+
+// A token of letters and digits mixed, six or more long, as session ids,
+// hex and UUID parts and invite codes are: `A1B2C3D4E5F6`, `550e8400`.
+const MIXED_TOKEN = /^(?=[^0-9]*[0-9])(?=[^A-Za-z]*[A-Za-z])[A-Za-z0-9]{6,}$/;
+// Letters alone, eight or more long, switching case three times or more, as a
+// random code does (`xKpQzRtV`) and a camel-case route word rarely does.
+const CASE_SWITCHING_TOKEN = /^(?=[A-Za-z]{8,}$)(?:[^a-z]*[a-z]+[A-Z]){3}/;
+// Route words whose next segment names one person or carries a one-time code,
+// as in `/profile/jane-smith` or `/reset/abcdefgh`.
+const PERSONAL_ROUTE = /^(?:u|user|users|profile|profiles|member|members|people|reset|reset-password|password|verify|verification|confirm|activate|invite|invitation|token|unsubscribe|magic-link)$/i;
+
+// Route words whose next segment is one shopper's order: any with `order` or
+// `orders` as a whole word part, as in `view-order`, `order-received` or `order_id`.
+const ORDER_ROUTE = /(?:^|[-_])orders?(?:[-_]|$)/i;
+// Product words that name a way to buy, not an order: `pre-order`, `on-order`,
+// `back-order`, `made-to-order`, as the whole route word only, so
+// `return-to-order` and `pre-order-status` stay routes.
+const PRODUCT_ORDER_WORD = /^(?:(?:pre|on|back)[-_]|made[-_]to[-_])orders?$/i;
+// A `;` that starts a matrix parameter, plain or encoded any number of times.
+const MATRIX_SEPARATOR = /;|%(?:25)*3B/i;
+// A valid escape left after decoding stopped, as when a literal `%` before it
+// can't be decoded again. What it hides is unknown, so it counts as sensitive.
+export const LEFTOVER_ESCAPE = /%[0-9A-F]{2}/i;
+
+export function hidesNextSegment(route: string): boolean {
+    return (
+        PERSONAL_ROUTE.test(route) ||
+        (ORDER_ROUTE.test(route) && !PRODUCT_ORDER_WORD.test(route))
+    );
+}
+
+// How many times a value is decoded at most, so one encoded twice or more reads
+// as its plain text.
+const MAX_DECODES = 5;
+
+// Decodes until the text stops changing. Undefined when the first decode fails;
+// a later failure keeps what decoded so far, as a literal `%` would.
+export function decodeFully(text: string): string | undefined {
+    let current = text;
+    for (let i = 0; i < MAX_DECODES; i++) {
+        let next: string;
+        try {
+            next = decodeURIComponent(current);
+        } catch (e) {
+            return i === 0 ? undefined : current;
+        }
+        if (next === current) {
+            return current;
+        }
+        current = next;
+    }
+    return current;
+}
+
+// The route word in a raw path segment: its last part behind an encoded slash,
+// read before any matrix parameter such as `;jsessionid=`, its `;` encoded once,
+// twice or not at all, so a parameter's own value never hides it. Undefined when
+// it can't be decoded, or is still encoded after MAX_DECODES.
+function routeWord(segment: string): string | undefined {
+    let text = segment;
+    for (let i = 0; i < MAX_DECODES; i++) {
+        const route = text.split(MATRIX_SEPARATOR)[0];
+        let next: string;
+        try {
+            next = decodeURIComponent(route);
+        } catch (e) {
+            return i === 0 ? undefined : route.split('/').pop();
+        }
+        if (next === route) {
+            return route.split('/').pop();
+        }
+        text = next;
+    }
+    return undefined;
+}
+
+// The last segment before index i that isn't empty, so `/orders//12345678`
+// still reads the order route.
+export function routeSegment(segments: string[], i: number): string {
+    let routeIndex = i - 1;
+    while (routeIndex > 0 && segments[routeIndex] === '') {
+        routeIndex--;
+    }
+    return segments[routeIndex];
+}
+
+// A piece with a lowercase letter right before an uppercase one, as a random
+// code has and a Title-Case word doesn't.
+const INNER_CASE_SWITCH = /[a-z][A-Z]/;
+
+const isToken = (text: string): boolean =>
+    MIXED_TOKEN.test(text) || CASE_SWITCHING_TOKEN.test(text);
+
+const mixesLettersAndDigits = (piece: string): boolean =>
+    /[0-9]/.test(piece) && /[A-Za-z]/.test(piece);
+
+// `+` sits inside base64 tokens, so it never splits one. A token that `-` or `_`
+// cuts into short pieces is still one when the pieces read as one joined and
+// either a piece switches case inside it or two or more pieces mix letters and
+// digits, as `a1b2-c3d4-e5f6` does. Title-Case-Words and plain slugs such as
+// `iphone-15-pro` do neither.
+export function isTokenSegment(segment: string): boolean {
+    const text = segment.replace(/\+/g, '');
+    const pieces = text.split(/[-_.~]/);
+    const joined = pieces.join('');
+    return (
+        pieces.some(isToken) ||
+        (pieces.some(piece => INNER_CASE_SWITCH.test(piece)) &&
+            isToken(joined)) ||
+        (pieces.filter(mixesLettersAndDigits).length >= 2 &&
+            MIXED_TOKEN.test(joined))
+    );
+}
+
+// The path a click logs. A segment that can single out one shopper
+// goes as `*`: one holding an @, `;` or `=`, a token, or the one after a route
+// that names a person, carries a code or opens an order. Kept segments stay
+// exactly as the page has them, plain numbers included, since on a product page
+// they name the product.
+export function pagePath(pathname: string): string {
+    const segments = pathname.split('/');
+    return segments
+        .map((segment, i) => {
+            const text = decodeFully(segment);
+            const route = i > 0 ? routeWord(routeSegment(segments, i)) : '';
+            // A route word that can't be decoded may be any route, so the
+            // segment after it is hidden too.
+            const hiddenByRoute =
+                i > 0 &&
+                !!text &&
+                (route === undefined || hidesNextSegment(route));
+            // An encoded slash hides several segments in one, so it goes whole.
+            return text === undefined ||
+                /[@;=/]/.test(text) ||
+                LEFTOVER_ESCAPE.test(text) ||
+                isTokenSegment(text) ||
+                hiddenByRoute
+                ? '*'
+                : segment;
+        })
+        .join('/');
+}
+
+// A token long enough that no page or product name looks like it: 16 or more
+// letters and digits mixed, as checkout tokens are, 16 or more letters
+// switching case like a random code, or a UUID.
+const LONG_MIXED_TOKEN = /^(?=[^0-9]*[0-9])(?=[^A-Za-z]*[A-Za-z])[A-Za-z0-9]{16,}$/;
+const LONG_CASE_SWITCHING_TOKEN = /^(?=[A-Za-z]{16,}$)(?:[^a-z]*[a-z]+[A-Z]){3}/;
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+// A token that `-` or `_` cuts into shorter pieces counts when two or more
+// pieces mix letters and digits, as `a1b2c3d4-e5f6g7h8` does and a product slug
+// such as `acmephone-15-pro-max-256gb` doesn't.
+function isLongToken(segment: string): boolean {
+    const pieces = segment.replace(/\+/g, '').split(/[-_.~]/);
+    return (
+        UUID.test(segment) ||
+        pieces.some(
+            piece =>
+                LONG_MIXED_TOKEN.test(piece) ||
+                LONG_CASE_SWITCHING_TOKEN.test(piece)
+        ) ||
+        (pieces.filter(mixesLettersAndDigits).length >= 2 &&
+            LONG_MIXED_TOKEN.test(pieces.join('')))
+    );
+}
+
+// The path every event carries, in its page URL and page views, where a
+// wrong `*` costs every output the page it names. Only what reliably singles
+// out one shopper goes as `*`: a segment holding an @, `;` or `=`, one that
+// can't be decoded or still holds an escape, a long token, and the one after a
+// route that names a person or opens an order when it holds a digit or a token.
+// Product codes and pages such as `/profile/edit` or `/orders/history` stay.
+export function pageUrlPath(pathname: string): string {
+    const segments = pathname.split('/');
+    return segments
+        .map((segment, i) => {
+            const text = decodeFully(segment);
+            const route = i > 0 ? routeWord(routeSegment(segments, i)) : '';
+            const holdsId =
+                !!text && (/[0-9]/.test(text) || isTokenSegment(text));
+            // A route word that can't be decoded may be any route.
+            const hiddenByRoute =
+                i > 0 &&
+                !!text &&
+                (route === undefined || (hidesNextSegment(route) && holdsId));
+            return text === undefined ||
+                /[@;=/]/.test(text) ||
+                LEFTOVER_ESCAPE.test(text) ||
+                isLongToken(text) ||
+                hiddenByRoute
+                ? '*'
+                : segment;
+        })
+        .join('/');
+}