@mparticle/web-sdk 3.20.0 → 3.22.0

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

@@ -35,6 +35,8 @@ export declare class BatchUploader {
     private exitHandler;
     private visibilityChangeHandler;
     private destroyed;
+    private batchOrder;
+    private nextBatchOrder;
     /**
      * Creates an instance of a BatchUploader
      * @param {IMParticleWebSDKInstance} mpInstance - the mParticle SDK instance

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

@@ -1,5 +1,6 @@
-export type ButtonElementKind = 'button' | 'input' | 'role' | 'wallet';
-export type ButtonLabelSource = 'labelledby' | 'aria' | 'text' | 'alt' | 'title' | 'value' | 'none';
+export type ButtonElementKind = 'button' | 'input' | 'role' | 'wallet' | 'link';
+export type LinkType = 'same_page' | 'outbound' | 'download';
+export type ButtonLabelSource = 'labelledby' | 'aria' | 'text' | 'label' | 'alt' | 'title' | 'value' | 'none';
 export interface IButtonClick {
     label?: string;
     labelSource: ButtonLabelSource;
@@ -12,5 +13,9 @@ export interface IButtonClick {
     form?: string;
     element: ButtonElementKind;
     type: string;
+    linkType?: LinkType;
+    linkDomain?: string;
+    fileExtension?: string;
+    checked?: boolean;
 }
 export declare function describeButtonClick(control: Element): IButtonClick | undefined;

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

@@ -15,6 +15,9 @@ export declare class ButtonTracker {
     private pagePath;
     private pageEvents;
     private pending;
+    private uploadTimerId;
+    private uploadHeld;
+    private leaving;
     constructor(mpInstance: IMParticleWebSDKInstance);
     get isActive(): boolean;
     init(options: IButtonTrackerOptions): void;
@@ -28,6 +31,9 @@ export declare class ButtonTracker {
     private readonly onEvent;
     private observe;
     private logClick;
+    private queuedForUpload;
+    private uploadNow;
+    private cancelUpload;
     private emit;
     private eventsEnabled;
     private isKitSuppressed;

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

@@ -1,3 +1,9 @@
 export type CheckoutIntentKind = 'commit' | 'wallet' | 'checkout_step' | 'frame';
+export type CheckoutIntentSource = 'vendor' | 'label' | 'brand' | 'frame' | 'submit';
+export interface ICheckoutIntent {
+    kind: Exclude<CheckoutIntentKind, 'frame'>;
+    source: CheckoutIntentSource;
+}
+export declare function classifyIntent(control: Element, pathname: string): ICheckoutIntent | undefined;
 export declare function classifyIntentControl(control: Element, pathname: string): Exclude<CheckoutIntentKind, 'frame'> | undefined;
-export declare function classifyIntentFrame(target: EventTarget | null, win: Window): 'frame' | undefined;
+export declare function classifyIntentFrame(target: EventTarget | null, win: Window): 'wallet' | 'frame' | undefined;

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

@@ -1,6 +1,9 @@
 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 vendorButtonKind(control: Element): 'wallet' | 'checkout_step' | 'none' | undefined;
 export declare function isWalletElement(element: Element): boolean;
+export declare function isQuietIntentControl(control: Element, isVendorWallet: boolean): boolean;
 export declare function findControl(path: Array<EventTarget | null>): Element | undefined;
 export declare function isUnsafeTextSource(element: Element): boolean;
+export declare function isUnsafeLabelSource(label: Element): boolean;

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

@@ -8,7 +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";
+import type { CheckoutIntentKind, CheckoutIntentSource } from "./buttonTracking/checkoutIntent";
 export type RoktAttributeValueArray = Array<string | number | boolean>;
 export type RoktAttributeValueType = string | number | boolean | undefined | null;
 export type RoktAttributeValue = RoktAttributeValueType | RoktAttributeValueArray;
@@ -46,6 +46,8 @@ export interface RoktKitFilterSettings {
 export interface ICheckoutIntentSignal {
     kind: CheckoutIntentKind;
     t: number;
+    source?: CheckoutIntentSource;
+    pathname?: string;
 }
 export interface IRoktKitSettings {
     accountId?: string;
@@ -123,6 +125,7 @@ export default class RoktManager {
     private watchRouteChanges;
     private notifyRouteChange;
     isCheckoutIntentSuppressed(): boolean;
+    isCheckoutIntentLive(): boolean;
     notifyCheckoutIntent(signal: ICheckoutIntentSignal, pathname?: string): void;
     discardCheckoutIntents(): void;
     private flushCheckoutIntents;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@mparticle/web-sdk",
-    "version": "3.20.0",
+    "version": "3.22.0",
     "description": "mParticle core SDK for web applications",
     "license": "Apache-2.0",
     "keywords": [

package/src/batchUploader.ts

@@ -52,6 +52,11 @@ export class BatchUploader {
     private exitHandler: (() => void) | null = null;
     private visibilityChangeHandler: (() => void) | null = null;
     private destroyed = false;
+    // The order this page's uploads first picked each batch up in, by request
+    // id. Batches enter uploads in creation order, so this keeps that order for
+    // batches that share a millisecond.
+    private batchOrder = new Map<string, number>();
+    private nextBatchOrder = 0;
 
     /**
      * Creates an instance of a BatchUploader
@@ -444,12 +449,27 @@ export class BatchUploader {
         // Clear out pending batches to avoid any potential duplication
         const batchesToUpload = this.batchesQueuedForProcessing;
         this.batchesQueuedForProcessing = [];
+        batchesToUpload.forEach(batch => {
+            if (!this.batchOrder.has(batch.source_request_id)) {
+                this.batchOrder.set(batch.source_request_id, this.nextBatchOrder++);
+            }
+        });
 
         const batchesThatDidNotUpload = await this.uploadBatches(
             batchesToUpload,
             useBeacon
         );
 
+        // Only a batch that will be retried needs its place kept.
+        const retriedIds = (batchesThatDidNotUpload || []).map(
+            batch => batch.source_request_id
+        );
+        batchesToUpload.forEach(batch => {
+            if (retriedIds.indexOf(batch.source_request_id) === -1) {
+                this.batchOrder.delete(batch.source_request_id);
+            }
+        });
+
         // Batches that do not successfully upload are added back to the process queue
         // in the order they were created so that we can attempt re-transmission in
         // the same sequence. This is to prevent any potential data corruption.
@@ -475,7 +495,19 @@ export class BatchUploader {
     }
 
     private storeBatchesQueuedForProcessing(): void {
-        const batches = this.batchesQueuedForProcessing;
+        // Another upload may have stored its failed batches while this one was
+        // in flight. Merge them in creation order, whichever upload finished
+        // first, so they are not overwritten and quota trimming drops the oldest.
+        const orderOf = (batch: Batch): number =>
+            this.batchOrder.get(batch.source_request_id) ?? -1;
+        const batches = [
+            ...this.batchesQueuedForProcessing,
+            ...(this.batchVault.retrieve() ?? []),
+        ].sort(
+            (a, b) =>
+                orderOf(a) - orderOf(b) ||
+                (a.timestamp_unixtime_ms ?? 0) - (b.timestamp_unixtime_ms ?? 0)
+        );
 
         // Nothing to persist: reset offline storage to an empty state.
         if (isEmpty(batches)) {

package/src/buttonTracking/buttonClickEvent.ts

@@ -33,12 +33,18 @@ export const buildButtonClickEvent = (
         test_id: click.testId,
         controls: click.controls,
         form: click.form,
+        link_type: click.linkType,
+        link_domain: click.linkDomain,
+        file_extension: click.fileExtension,
     };
     for (const key of Object.keys(optional)) {
         if (optional[key]) {
             data[key] = optional[key];
         }
     }
+    if (click.checked !== undefined) {
+        data.checked = click.checked;
+    }
     return {
         messageType: MessageType.PageEvent,
         name: BUTTON_CLICK_EVENT_NAME,

package/src/buttonTracking/buttonDescription.ts

@@ -1,6 +1,7 @@
 import { isFunction } from '../utils';
 import {
     hasComposedAncestor,
+    isUnsafeLabelSource,
     isUnsafeTextSource,
     isWalletElement,
 } from './controls';
@@ -8,12 +9,18 @@ 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 ButtonElementKind = 'button' | 'input' | 'role' | 'wallet' | 'link';
+
+// The link clicks page views can't see: ones that stay on the page, leave the site or download a file.
+export type LinkType = 'same_page' | 'outbound' | 'download';
+
+const DOWNLOAD_EXTENSIONS = /\.(pdf|zip|csv|txt|ics|docx?|xlsx?|pptx?|dmg|exe|apk|mp3|mp4)$/i;
 
 export type ButtonLabelSource =
     | 'labelledby'
     | 'aria'
     | 'text'
+    | 'label'
     | 'alt'
     | 'title'
     | 'value'
@@ -31,6 +38,10 @@ export interface IButtonClick {
     form?: string;
     element: ButtonElementKind;
     type: string;
+    linkType?: LinkType;
+    linkDomain?: string;
+    fileExtension?: string;
+    checked?: boolean;
 }
 
 function elementKind(control: Element): ButtonElementKind {
@@ -38,7 +49,10 @@ function elementKind(control: Element): ButtonElementKind {
         return 'wallet';
     }
     const tag = control.tagName.toLowerCase();
-    return tag === 'button' || tag === 'input' ? tag : 'role';
+    if (tag === 'button' || tag === 'input') {
+        return tag;
+    }
+    return control.matches('a[href]:not([role="button"])') ? 'link' : 'role';
 }
 
 function textOf(element: Element | null): string {
@@ -52,9 +66,10 @@ function nonBlank(value: string | null): string | 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.
+// aria-labelledby, aria-label, own text (or an inner image's alt), title, for
+// inputs their value, and for checkboxes and radios their label's text. 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 } {
@@ -97,6 +112,16 @@ function accessibleName(
                 // What the browser shows on an input without a value.
                 return { raw: type, source: 'value' };
             }
+        } else if (type === 'checkbox' || type === 'radio') {
+            // The label the browser ties to the box, never the box's value.
+            const label = control.labels ? control.labels[0] : undefined;
+            const text =
+                label && !isUnsafeLabelSource(label) && label.textContent
+                    ? label.textContent.trim()
+                    : '';
+            if (text) {
+                return { raw: text, source: 'label' };
+            }
         }
     } else if (readable) {
         const text = textOf(control);
@@ -230,13 +255,62 @@ function controlType(control: Element, element: ButtonElementKind): string {
         : 'button';
 }
 
-// Describes a clicked control for auto button tracking. Links are left to page
-// views, so a link click is not described.
+interface ILinkDetails {
+    type: LinkType;
+    domain?: string;
+    fileExtension?: string;
+}
+
+// Reads the link's own resolved URL parts, never its full href: only the hostname of
+// a link that leaves the site and the extension of a file it downloads travel. Navigation
+// within the site is left to page views, and mailto:, tel: and other schemes are skipped.
+function describeLink(link: Element): ILinkDetails | undefined {
+    const href = (link.getAttribute('href') || '').trim();
+    if (!href || href.charAt(0) === '#') {
+        return { type: 'same_page' };
+    }
+    if (!(link instanceof HTMLAnchorElement)) {
+        return undefined;
+    }
+    const protocol = link.protocol.toLowerCase();
+    if (protocol === 'javascript:') {
+        return { type: 'same_page' };
+    }
+    if (protocol !== 'http:' && protocol !== 'https:') {
+        return undefined;
+    }
+    const domain =
+        link.hostname !== window.location.hostname
+            ? link.hostname.toLowerCase()
+            : undefined;
+    const extension = DOWNLOAD_EXTENSIONS.exec(link.pathname);
+    if (link.hasAttribute('download') || extension) {
+        return {
+            type: 'download',
+            domain,
+            fileExtension: extension ? extension[1].toLowerCase() : undefined,
+        };
+    }
+    if (domain) {
+        return { type: 'outbound', domain };
+    }
+    return link.pathname === window.location.pathname &&
+        link.search === window.location.search
+        ? { type: 'same_page' }
+        : undefined;
+}
+
+// Describes a clicked control for auto button tracking. A link counts only when page
+// views can't see the click, and carries its link type.
 export function describeButtonClick(
     control: Element
 ): IButtonClick | undefined {
+    let link: ILinkDetails | undefined;
     if (control.matches('a[href]:not([role="button"])')) {
-        return undefined;
+        link = describeLink(control);
+        if (!link) {
+            return undefined;
+        }
     }
     const element = elementKind(control);
     const name = accessibleName(control);
@@ -255,5 +329,15 @@ export function describeButtonClick(
         form: formIdentifier(control),
         element,
         type: controlType(control, element),
+        linkType: link ? link.type : undefined,
+        linkDomain: link ? link.domain : undefined,
+        fileExtension: link ? link.fileExtension : undefined,
+        // The box as the click left it: the browser toggles it before the click
+        // reaches listeners, and puts it back if the click is cancelled.
+        checked:
+            control instanceof HTMLInputElement &&
+            (control.type === 'checkbox' || control.type === 'radio')
+                ? control.checked
+                : undefined,
     };
 }

package/src/buttonTracking/buttonTracker.ts

@@ -4,7 +4,8 @@ import { buildButtonClickEvent } from './buttonClickEvent';
 import { describeButtonClick, IButtonClick } from './buttonDescription';
 import {
     CheckoutIntentKind,
-    classifyIntentControl,
+    CheckoutIntentSource,
+    classifyIntent,
     classifyIntentFrame,
 } from './checkoutIntent';
 import { findControl } from './controls';
@@ -19,6 +20,9 @@ const PATH_LIMIT = 12;
 // 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;
@@ -77,7 +81,7 @@ const CAPTURE_PASSIVE: AddEventListenerOptions = {
 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.
+// Rokt kit as a frozen {kind, t, source, pathname}. Submits and wallet frame focus feed the kit only.
 export class ButtonTracker {
     private readonly mpInstance: IMParticleWebSDKInstance;
     private active = false;
@@ -90,6 +94,10 @@ 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;
@@ -181,6 +189,7 @@ export class ButtonTracker {
         this.lastSent = {};
         this.pagePath = null;
         this.pageEvents = 0;
+        this.cancelUpload();
     }
 
     private enqueue(delivery: () => void): void {
@@ -206,7 +215,14 @@ export class ButtonTracker {
             event.type === 'pagehide' ||
             document.visibilityState === 'hidden'
         ) {
-            this.drain();
+            this.leaving = true;
+            try {
+                this.drain();
+            } finally {
+                this.leaving = false;
+            }
+            // The SDK's exit upload sends the queue, held taps included.
+            this.cancelUpload();
         }
     };
 
@@ -244,7 +260,9 @@ export class ButtonTracker {
         // 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 box: HTMLInputElement | undefined;
         let kind: CheckoutIntentKind | undefined;
+        let source: CheckoutIntentSource | undefined;
         let unconfirmedCommit = false;
         if (layer === 'click') {
             // The composed path is only populated during dispatch.
@@ -255,10 +273,15 @@ export class ButtonTracker {
             );
             if (control) {
                 click = logsEvents ? describeButtonClick(control) : undefined;
+                if (click && click.checked !== undefined) {
+                    box = control as HTMLInputElement;
+                }
                 // Checkout intent is only worked out when the kit can use it.
-                kind = signalsKit
-                    ? classifyIntentControl(control, pathname)
+                const intent = signalsKit
+                    ? classifyIntent(control, pathname)
                     : undefined;
+                kind = intent ? intent.kind : undefined;
+                source = intent ? intent.source : undefined;
             }
         } else if (layer === 'submit') {
             const submitter = (event as Event & { submitter?: Element | null })
@@ -268,8 +291,11 @@ export class ButtonTracker {
             // commit click, which is known once that click is delivered.
             if (!submitter) {
                 kind = 'commit';
+                source = 'submit';
             } else if (control) {
-                kind = classifyIntentControl(control, pathname);
+                const intent = classifyIntent(control, pathname);
+                kind = intent ? intent.kind : undefined;
+                source = intent ? intent.source : undefined;
             }
             unconfirmedCommit = !submitter;
         }
@@ -284,6 +310,7 @@ export class ButtonTracker {
                     // Read after the blur settles: some browsers have not moved
                     // focus into the frame yet when the window blurs.
                     kind = classifyIntentFrame(document.activeElement, window);
+                    source = 'frame';
                 } else if (
                     unconfirmedCommit &&
                     t - this.lastCommitClick > SUBMIT_AFTER_COMMIT_CLICK_MS
@@ -291,10 +318,21 @@ export class ButtonTracker {
                     kind = undefined;
                 }
                 if (click && logsEvents) {
+                    // The box as this click left it. The browser toggles it
+                    // before dispatch and puts it back once a cancelled click
+                    // is over, so only a cancelled click changes the reading
+                    // taken at dispatch: a checkbox to the other state, a
+                    // radio to however it was restored.
+                    if (box && event.defaultPrevented) {
+                        click.checked =
+                            box.type === 'checkbox'
+                                ? !click.checked
+                                : box.checked;
+                    }
                     this.logClick(click, pathname);
                 }
                 if (kind) {
-                    this.emit(kind, layer, t, pathname);
+                    this.emit(kind, source, layer, t, pathname);
                 }
             } catch (e) {
                 this.log('[error] delivery threw: ' + e);
@@ -317,13 +355,59 @@ export class ButtonTracker {
         this.pageEvents++;
         // Restarts an expired session, as public logEvent() and page views do.
         this.mpInstance._SessionManager.resetSessionTimer();
+        const queued = this.queuedForUpload();
         this.mpInstance._Events.logEvent(
             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(
         kind: CheckoutIntentKind,
+        source: CheckoutIntentSource | undefined,
         layer: string,
         t: number,
         pathname: string
@@ -342,7 +426,7 @@ export class ButtonTracker {
         this.lastSent[kind] = { t, pathname };
 
         this.mpInstance._RoktManager.notifyCheckoutIntent(
-            Object.freeze({ kind, t }),
+            Object.freeze({ kind, t, source, pathname }),
             pathname
         );
     }