@mparticle/web-sdk 3.16.1 → 3.18.0

package/dist/types/src/buttonTracking/buttonClickEvent.d.ts

@@ -0,0 +1,5 @@
+import { BaseEvent } from '../sdkRuntimeModels';
+import { IButtonClick } from './buttonDescription';
+export declare const AUTO_BUTTON_ATTRIBUTE = "is_auto_button_click";
+export declare const BUTTON_CLICK_EVENT_NAME = "Button Click";
+export declare const buildButtonClickEvent: (click: IButtonClick, pathname: string) => BaseEvent;

package/dist/types/src/buttonTracking/buttonDescription.d.ts

@@ -0,0 +1,14 @@
+export type ButtonElementKind = 'button' | 'input' | 'role' | 'wallet';
+export type ButtonLabelSource = 'labelledby' | 'aria' | 'text' | 'alt' | 'title' | 'value' | 'none';
+export interface IButtonClick {
+    label?: string;
+    labelSource: ButtonLabelSource;
+    ariaLabel?: string;
+    icon?: string;
+    elementId?: string;
+    elementName?: string;
+    testId?: string;
+    element: ButtonElementKind;
+    type: string;
+}
+export declare function describeButtonClick(path: Array<EventTarget | null>): IButtonClick | undefined;

package/dist/types/src/buttonTracking/buttonTracker.d.ts

@@ -0,0 +1,36 @@
+import { IMParticleWebSDKInstance } from '../mp-instance';
+export declare const WIN_BTN_KEY = "__mpBtn__";
+export interface IButtonTrackerOptions {
+    hasRoktKit: boolean;
+}
+export declare const getActiveButtonTracker: () => ButtonTracker | undefined;
+export declare const resetButtonTracking: () => void;
+export declare class ButtonTracker {
+    private readonly mpInstance;
+    private active;
+    private hasRoktKit;
+    private generation;
+    private lastCommitClick;
+    private lastSent;
+    private pagePath;
+    private pageEvents;
+    private lastEvent;
+    private pending;
+    constructor(mpInstance: IMParticleWebSDKInstance);
+    get isActive(): boolean;
+    init(options: IButtonTrackerOptions): void;
+    teardown(): void;
+    clearPending(): void;
+    private reset;
+    private enqueue;
+    private readonly drain;
+    private readonly onHide;
+    private readonly onPageShow;
+    private readonly onEvent;
+    private observe;
+    private logClick;
+    private emit;
+    private eventsEnabled;
+    private isKitSuppressed;
+    private log;
+}

package/dist/types/src/buttonTracking/checkoutIntent.d.ts

@@ -0,0 +1,3 @@
+export type CheckoutIntentKind = 'commit' | 'wallet' | 'checkout_step' | 'frame';
+export declare function classifyIntentControl(path: Array<EventTarget | null>, pathname: string): CheckoutIntentKind | undefined;
+export declare function classifyIntentFrame(target: EventTarget | null, win: Window): 'frame' | undefined;

package/dist/types/src/buttonTracking/controls.d.ts

@@ -0,0 +1,5 @@
+export declare const CONTROL_SELECTOR = "button, input[type=\"submit\"], input[type=\"button\"], input[type=\"image\"], [role=\"button\"]";
+export declare function hasComposedAncestor(element: Element, selector: string): boolean;
+export declare function isRoktElement(element: Element): boolean;
+export declare function isWalletElement(element: Element): boolean;
+export declare function findControl(path: Array<EventTarget | null>): Element | undefined;

package/dist/types/src/buttonTracking/labelMasking.d.ts

@@ -0,0 +1 @@
+export declare function maskLabel(raw: string | null | undefined): string | undefined;

package/dist/types/src/constants.d.ts

@@ -162,6 +162,7 @@ declare const Constants: {
         readonly CaptureIntegrationSpecificIdsV2: "captureIntegrationSpecificIds.V2";
         readonly AstBackgroundEvents: "astBackgroundEvents";
         readonly AutoLogPageView: "autoLogPageView";
+        readonly AutoButtonTracking: "autoButtonTracking";
     };
     readonly DefaultInstance: "default_instance";
     readonly CCPAPurpose: "data_sale_opt_out";

package/dist/types/src/internal-types.d.ts

@@ -14,7 +14,7 @@
  */
 export * from './public-types';
 export type { KitInterface, } from './forwarders.interfaces';
-export type { RoktAttributeValue, RoktAttributeValueType, RoktAttributeValueArray, RoktAttributes, IRoktPartnerExtensionData, IRoktSelectPlacementsOptions, IRoktSelection, IRoktLauncher, IRoktMessage, RoktKitFilterSettings, IRoktKitSettings, IRoktKit, IRoktOptions, IRoktLauncherOptions, } from './roktManager';
+export type { RoktAttributeValue, RoktAttributeValueType, RoktAttributeValueArray, RoktAttributes, IRoktPartnerExtensionData, IRoktSelectPlacementsOptions, IRoktSelection, IRoktLauncher, IRoktMessage, RoktKitFilterSettings, IRoktKitSettings, IRoktKit, ICheckoutIntentSignal, IRoktOptions, IRoktLauncherOptions, } from './roktManager';
 export type { ErrorCodes, WSDKErrorSeverity, } from './reporting/types';
 export type { ISDKError, ISDKLogEntry, IErrorReportingService, ILoggingService, } from './reporting/types';
 export type { SDKEvent, SDKProductAction, SDKProductActionType, SDKPromotionAction, SDKGeoLocation, SDKDataPlan, SDKLoggerApi, SDKConfigApi, IMParticleInstanceManager, } from './sdkRuntimeModels';

package/dist/types/src/mp-instance.d.ts

@@ -22,6 +22,7 @@ import { ICookieConsentManager } from './cookieConsentManager';
 import { ErrorReportingDispatcher } from './reporting/errorReportingDispatcher';
 import { LoggingDispatcher } from './reporting/loggingDispatcher';
 import { PageViewTracker } from './pageViewTracker';
+import { ButtonTracker } from './buttonTracking/buttonTracker';
 export interface IErrorLogMessage {
     message?: string;
     name?: string;
@@ -47,6 +48,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     _IntegrationCapture: IntegrationCapture;
     _NativeSdkHelpers: INativeSdkHelpers;
     _PageViewTracker?: PageViewTracker;
+    _ButtonTracker?: ButtonTracker;
     _Persistence: IPersistence;
     _CookieConsentManager: ICookieConsentManager;
     _ErrorReportingDispatcher: ErrorReportingDispatcher;

package/dist/types/src/roktManager.d.ts

@@ -8,6 +8,7 @@ import { IStore, LocalSessionAttributes } from "./store";
 import { IErrorReportingService, ILoggingService } from "./reporting/types";
 import { IRoktLauncherOptions } from "./roktLauncherOptions";
 import IntegrationCapture from "./integrationCapture";
+import type { CheckoutIntentKind } from "./buttonTracking/checkoutIntent";
 export type RoktAttributeValueArray = Array<string | number | boolean>;
 export type RoktAttributeValueType = string | number | boolean | undefined | null;
 export type RoktAttributeValue = RoktAttributeValueType | RoktAttributeValueArray;
@@ -42,6 +43,10 @@ export interface RoktKitFilterSettings {
     filterUserAttributes?: (userAttributes: Dictionary<string>, filterList: number[]) => Dictionary<string>;
     filteredUser?: IMParticleUser | null;
 }
+export interface ICheckoutIntentSignal {
+    kind: CheckoutIntentKind;
+    t: number;
+}
 export interface IRoktKitSettings {
     accountId?: string;
     placementAttributesMapping?: string;
@@ -59,6 +64,7 @@ export interface IRoktKit {
     onShoppableAdsReady(callback: () => void): void;
     terminate?: () => Promise<void>;
     onRouteChange?: () => void;
+    onCheckoutIntent?: (signal: ICheckoutIntentSignal) => void;
     launcherOptions?: Dictionary<any>;
     settings?: IRoktKitSettings;
     integrationName?: string;
@@ -91,6 +97,7 @@ export default class RoktManager {
     private initialized;
     private isShoppableAdsLoaded;
     private stopRouteChangeWatch;
+    private pendingCheckoutIntents;
     constructor(instanceName?: string);
     /**
      * Sets a callback to be invoked when RoktManager becomes ready
@@ -115,6 +122,10 @@ export default class RoktManager {
     attachKit(kit: IRoktKit): void;
     private watchRouteChanges;
     private notifyRouteChange;
+    isCheckoutIntentSuppressed(): boolean;
+    notifyCheckoutIntent(signal: ICheckoutIntentSignal, pathname?: string): void;
+    discardCheckoutIntents(): void;
+    private flushCheckoutIntents;
     private isAutoLogPageViewEnabled;
     /**
      * Renders ads based on the options provided

package/dist/types/src/store.d.ts

@@ -79,6 +79,7 @@ export interface IFeatureFlags {
     'captureIntegrationSpecificIds.V2'?: string;
     astBackgroundEvents?: boolean;
     autoLogPageView?: boolean;
+    autoButtonTracking?: boolean;
 }
 export interface IStore {
     isEnabled: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "3.16.1",
+    "version": "3.18.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [
@@ -32,11 +32,11 @@
     },
     "repository": "https://github.com/mParticle/mparticle-web-sdk",
     "scripts": {
-        "build": "cross-env ENVIRONMENT=prod BUILDALL=true rollup --config rollup.config.js && npm run build:types",
+        "build": "cross-env ENVIRONMENT=prod BUILDALL=true rollup --config rollup.config.js && npm run check:ascii:dist && npm run build:types",
         "build:types": "rm -rf dist/types && (tsc -p tsconfig.types.json || true) && test -f dist/types/src/public-types.d.ts && test -f dist/types/src/internal-types.d.ts",
         "build:cbt": "rollup --config test/cross-browser-testing/rollup.CBT.config.js",
         "build:dev": "cross-env ENVIRONMENT=dev BUILD=iife rollup --config rollup.config.js",
-        "build:iife": "cross-env ENVIRONMENT=prod BUILD=iife rollup --config rollup.config.js",
+        "build:iife": "cross-env ENVIRONMENT=prod BUILD=iife rollup --config rollup.config.js && npm run check:ascii:dist -- dist/mparticle.js",
         "build:npm": "cross-env ENVIRONMENT=prod BUILD=cjs rollup --config rollup.config.js",
         "build:esm": "cross-env ENVIRONMENT=prod BUILD=esm rollup --config rollup.config.js",
         "build:stub": "cross-env ENVIRONMENT=prod BUILD=stub rollup --config rollup.config.js",
@@ -93,6 +93,7 @@
         "gzip": "gzip -c dist/mparticle.min.js > dist/mparticle.min.js.gz",
         "bundle": "npm run uglify && npm run gzip",
         "report:bundled": "ls -l dist/mparticle.min.js.gz | awk '{print $5}'",
+        "check:ascii:dist": "node scripts/check-ascii-dist.js",
         "report:bundled:human": "ls -lh dist/mparticle.min.js.gz | awk '{print $5}'"
     },
     "pre-commit": [

package/src/buttonTracking/buttonClickEvent.ts

@@ -0,0 +1,49 @@
+import { BaseEvent } from '../sdkRuntimeModels';
+import { EventType, MessageType } from '../types';
+import { IButtonClick } from './buttonDescription';
+
+// Marks an automatically logged button click, like `is_auto_page_view`.
+export const AUTO_BUTTON_ATTRIBUTE = 'is_auto_button_click';
+
+export const BUTTON_CLICK_EVENT_NAME = 'Button Click';
+
+// One custom event per click, logged like logLink() with the auto marker and the
+// page fields that auto page views carry. No intent: classifying clicks is left
+// to whoever reads the data.
+export const buildButtonClickEvent = (
+    click: IButtonClick,
+    pathname: string
+): BaseEvent => {
+    const data: { [key: string]: string | boolean } = {
+        label_source: click.labelSource,
+        element: click.element,
+        type: click.type,
+        path: pathname,
+        hostname: window.location.hostname,
+        [AUTO_BUTTON_ATTRIBUTE]: true,
+    };
+    if (click.label) {
+        data.label = click.label;
+    }
+    if (click.ariaLabel) {
+        data.aria_label = click.ariaLabel;
+    }
+    if (click.icon) {
+        data.icon = click.icon;
+    }
+    if (click.elementId) {
+        data.element_id = click.elementId;
+    }
+    if (click.elementName) {
+        data.element_name = click.elementName;
+    }
+    if (click.testId) {
+        data.test_id = click.testId;
+    }
+    return {
+        messageType: MessageType.PageEvent,
+        name: BUTTON_CLICK_EVENT_NAME,
+        data,
+        eventType: EventType.Other,
+    };
+};

package/src/buttonTracking/buttonDescription.ts

@@ -0,0 +1,244 @@
+import { isFunction } from '../utils';
+import { findControl, hasComposedAncestor, isWalletElement } from './controls';
+import { maskLabel } from './labelMasking';
+
+// Describes a clicked button for auto button tracking: its masked name, icon,
+// hand-written identifiers and kind. Never reads form field values.
+export type ButtonElementKind = 'button' | 'input' | 'role' | 'wallet';
+
+export type ButtonLabelSource =
+    | 'labelledby'
+    | 'aria'
+    | 'text'
+    | 'alt'
+    | 'title'
+    | 'value'
+    | 'none';
+
+export interface IButtonClick {
+    label?: string;
+    labelSource: ButtonLabelSource;
+    ariaLabel?: string;
+    icon?: string;
+    elementId?: string;
+    elementName?: string;
+    testId?: string;
+    element: ButtonElementKind;
+    type: string;
+}
+
+function elementKind(control: Element): ButtonElementKind {
+    if (isWalletElement(control)) {
+        return 'wallet';
+    }
+    const tag = control.tagName.toLowerCase();
+    return tag === 'button' || tag === 'input' ? tag : 'role';
+}
+
+const EDITABLE = '[contenteditable]:not([contenteditable="false"])';
+
+// 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.
+function isUnsafeTextSource(element: Element): boolean {
+    return (
+        element.matches(
+            'input, select, textarea, option, optgroup, datalist, ' + EDITABLE
+        ) ||
+        !!element.querySelector(
+            'input, select, textarea, [data-mp-no-track], ' + EDITABLE
+        ) ||
+        hasComposedAncestor(
+            element,
+            'select, datalist, textarea, [data-mp-no-track], ' + EDITABLE
+        )
+    );
+}
+
+function textOf(element: Element | null): string {
+    return element && !isUnsafeTextSource(element) && element.textContent
+        ? element.textContent.trim()
+        : '';
+}
+
+function nonBlank(value: string | null): string | undefined {
+    return value && value.trim() ? value : undefined;
+}
+
+// The button's name as a screen reader would read it, simplified: the first of
+// aria-labelledby, aria-label, own text (or an inner image's alt), title, and for
+// inputs their value. The text sources are skipped for controls that hold form
+// fields or more than four children, so a typed value is never read.
+function accessibleName(
+    control: Element
+): { raw?: string; source: ButtonLabelSource } {
+    const labelledBy = control.getAttribute('aria-labelledby');
+    if (labelledBy) {
+        const root = (isFunction(control.getRootNode)
+            ? control.getRootNode()
+            : document) as Document | ShadowRoot;
+        const text = labelledBy
+            .split(/\s+/)
+            .map(id =>
+                textOf(root.getElementById ? root.getElementById(id) : null)
+            )
+            .filter(part => !!part)
+            .join(' ');
+        if (text) {
+            return { raw: text, source: 'labelledby' };
+        }
+    }
+    const aria = nonBlank(control.getAttribute('aria-label'));
+    if (aria) {
+        return { raw: aria, source: 'aria' };
+    }
+    const readable =
+        control.children.length <= 4 && !isUnsafeTextSource(control);
+    if (control instanceof HTMLInputElement) {
+        // The browser's normalised type: an unknown value reads as 'text'.
+        const type = control.type;
+        if (type === 'image') {
+            const alt = nonBlank(control.getAttribute('alt'));
+            if (alt) {
+                return { raw: alt, source: 'alt' };
+            }
+        } else if (type === 'submit' || type === 'button' || type === 'reset') {
+            const value = nonBlank(control.value);
+            if (value) {
+                return { raw: value, source: 'value' };
+            }
+            if (type !== 'button') {
+                // What the browser shows on an input without a value.
+                return { raw: type, source: 'value' };
+            }
+        }
+    } else if (readable) {
+        const text = textOf(control);
+        if (text) {
+            return { raw: text, source: 'text' };
+        }
+        const image = control.querySelector('img[alt]');
+        const alt = image ? nonBlank(image.getAttribute('alt')) : undefined;
+        if (alt) {
+            return { raw: alt, source: 'alt' };
+        }
+    }
+    const title = nonBlank(control.getAttribute('title'));
+    if (title) {
+        return { raw: title, source: 'title' };
+    }
+    return { source: 'none' };
+}
+
+const ICON_CLASS = /^(?:fa|fas|far|fal|icon|bi|glyphicon|ti|mdi|ri|la|lucide|ion|feather|ph)-([a-z][a-z-]{1,31})$/;
+// Size, style and animation classes that share the icon prefixes.
+const ICON_MODIFIER = /^(?:solid|regular|light|thin|duotone|brands|sharp|fw|lg|xs|sm|xl|spin|pulse|border|inverse|stack|flip(?:-[a-z]+)?|rotate(?:-[a-z]+)?|pull-[a-z]+)$/;
+
+function iconToken(candidate: string | null): string | undefined {
+    if (!candidate) {
+        return undefined;
+    }
+    const token = candidate.toLowerCase().replace(/^icon-/, '');
+    return /^[a-z][a-z-]{1,31}$/.test(token) ? token : undefined;
+}
+
+// An icon name from an SVG sprite reference or an icon-font class, for buttons
+// whose only content is an icon. Letters and hyphens only.
+function iconHint(control: Element): string | undefined {
+    const allowed = (element: Element) =>
+        !hasComposedAncestor(element, '[data-mp-no-track]');
+    const use = Array.from(control.querySelectorAll('use')).filter(allowed)[0];
+    if (use) {
+        const href =
+            use.getAttribute('href') || use.getAttribute('xlink:href') || '';
+        const hash = href.indexOf('#');
+        const sprite = iconToken(hash === -1 ? null : href.slice(hash + 1));
+        if (sprite) {
+            return sprite;
+        }
+    }
+    const candidates = [control]
+        .concat(Array.from(control.querySelectorAll('i, span, svg')))
+        .filter(allowed)
+        .slice(0, 5);
+    for (const element of candidates) {
+        const classes = (element.getAttribute('class') || '').split(/\s+/);
+        for (const name of classes) {
+            const match = ICON_CLASS.exec(name.toLowerCase());
+            if (match && !ICON_MODIFIER.test(match[1])) {
+                return match[1];
+            }
+        }
+    }
+    return undefined;
+}
+
+// Words of letters, each optionally ending in up to three digits, joined by
+// hyphens or underscores: `add-to-cart`, `btnCheckout`, `step_2`. Generated ids
+// (`ember1234`, `a8f3e2c1`, `radix-:r1:`) and long numbers don't match.
+const HAND_WRITTEN_ID = /^[A-Za-z]+[0-9]{0,3}(?:[-_](?:[A-Za-z]+[0-9]{0,3}|[0-9]{1,3}))*$/;
+
+// A developer-written identifier, or nothing.
+function stableIdentifier(value: string | null): string | undefined {
+    if (!value) {
+        return undefined;
+    }
+    const id = value.trim();
+    // At most three digits in all, so numbers split into groups don't pass.
+    const digits = id.replace(/[^0-9]/g, '').length;
+    return id.length <= 64 && digits <= 3 && HAND_WRITTEN_ID.test(id)
+        ? id
+        : undefined;
+}
+
+const TEST_ID_ATTRIBUTES = [
+    'data-testid',
+    'data-test-id',
+    'data-test',
+    'data-qa',
+    'data-cy',
+];
+
+function testIdentifier(control: Element): string | undefined {
+    for (const attribute of TEST_ID_ATTRIBUTES) {
+        const id = stableIdentifier(control.getAttribute(attribute));
+        if (id) {
+            return id;
+        }
+    }
+    return undefined;
+}
+
+// The browser's normalised type: a button defaults to 'submit' and an unknown
+// input type reads as 'text'. Wallet and role buttons are just 'button'.
+function controlType(control: Element, element: ButtonElementKind): string {
+    return element === 'button' || element === 'input'
+        ? (control as HTMLButtonElement | HTMLInputElement).type
+        : 'button';
+}
+
+// Describes a clicked button for auto button tracking. Links are left to page
+// views, so a link click is not described.
+export function describeButtonClick(
+    path: Array<EventTarget | null>
+): IButtonClick | undefined {
+    const control = findControl(path);
+    if (!control || control.matches('a[href]:not([role="button"])')) {
+        return undefined;
+    }
+    const element = elementKind(control);
+    const name = accessibleName(control);
+    const label = maskLabel(name.raw);
+    return {
+        label,
+        labelSource: label ? name.source : 'none',
+        // Kept on its own as well: it often says more than the visible text,
+        // such as which item a remove button removes.
+        ariaLabel: maskLabel(control.getAttribute('aria-label')),
+        icon: iconHint(control),
+        elementId: stableIdentifier(control.getAttribute('id')),
+        elementName: stableIdentifier(control.getAttribute('name')),
+        testId: testIdentifier(control),
+        element,
+        type: controlType(control, element),
+    };
+}