@mparticle/web-sdk 3.16.1 → 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/buttonTracking/checkoutIntent.ts

@@ -0,0 +1,200 @@
+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'
+    | 'checkout_step'
+    | 'frame';
+
+const checkoutPath = /(?:^|\/)(?:checkouts?|payment|order|kasse|paiement|commander?|pago)(?:\/|$)/i;
+const exclusions = new RegExp(
+    [
+        'coupon|promo|newsletter|sign in|add to cart|gift card|pay later|pay in|payment plan|learn more',
+        'gutschein|anmelden|warenkorb|bon cadeau|connexion|panier|cupón|iniciar sesión|carrito',
+        'carrello|codice sconto|accedi|buono regalo|winkelwagen|kortingscode|inloggen|cadeaubon|achteraf betalen',
+        'カート|クーポン|ログイン|会員登録|ギフト|後払い|メルマガ',
+    ].join('|')
+);
+const commits = new RegExp(
+    '^(?:' +
+        [
+            '(?:place|submit|complete|confirm|finali[sz]e)(?!(?: [^ ]+){0,2} (?:another|new|next)(?: |$))(?: [^ ]+){0,2} (?:order|purchase|booking|reservation|payment|checkout)',
+            'pay(?: securely)?(?: now)?|confirm and pay|order and pay|order with obligation to pay',
+            '(?:jetzt )?(?:zahlungs|kosten)pflichtig (?:bestellen|buchen)|(?:jetzt )?bezahlen|kauf abschließen|bestellung abschließen',
+            'commander et payer|payer(?: maintenant)?|(?:confirmer|finaliser) (?:ma |la )?commande',
+            "valider et payer|confirmer et payer|commande avec obligation de paiement|finaliser l'achat",
+            '(?:realizar|confirmar|completar) (?:el |mi |la )?(?:pedido|compra|reserva)|finalizar (?:el |mi )?pedido|pagar(?: ahora)?',
+            'pedido con obligación de pago',
+            "(?:effettua|conferma|concludi|completa) (?:l'|il )?(?:ordine|acquisto)|ordine con obbligo di pagamento",
+            'paga(?: ora| adesso)?|ordina e paga',
+            '(?:nu )?betalen|bestellen en betalen|bestelling plaatsen|plaats bestelling|bestelling afronden',
+            'bestelling met betalingsverplichting',
+            '(?:この内容で|上記の?内容で)?ご?(?:注文|購入|予約|決済|お?支払い?)を?(?:確定|完了)(?:する)?',
+            '(?:この内容で|上記の?内容で)ご?(?:注文|購入|予約)する|ご?注文する|決済する|(?:今すぐ|を)?支払う',
+        ].join('|') +
+        ')$'
+);
+const routeGatedCommits = new RegExp(
+    '^(?:buy now|purchase|jetzt kaufen|kaufen|commander|(?:passer|valider) (?:la |ma )?commande|finalizar (?:la |mi )?compra|' +
+        'comprar ahora|acquista ora|nu kopen|今すぐ購入|購入する|この内容で申し込む)$'
+);
+const steps = new RegExp(
+    '^(?:' +
+        [
+            'checkout|check out|check-out|continue to payment|proceed to checkout',
+            'zur kasse|zur kasse gehen|auschecken|weiter zur zahlung',
+            'passer à la caisse|continuer vers le paiement|procéder au paiement',
+            'ir a caja|continuar al pago|tramitar pedido',
+            "procedi al checkout|procedi all'acquisto|procedi al pagamento|vai alla cassa",
+            'afrekenen|verder naar betalen|doorgaan naar betalen',
+            'レジに進む|ご?(?:購入|注文)手続き(?:へ|に)(?:進む)?|お?支払い(?:へ|に)進む|(?:ご注文内容の)?確認画面へ(?:進む)?',
+        ].join('|') +
+        ')$'
+);
+const wallets = /^(?:apple pay|google pay|paypal|venmo|amazon pay|shop pay|klarna|afterpay|affirm)$/;
+// Exact HTTPS hosts of hosted wallet and payment frames.
+const frameHosts = new Set([
+    'www.paypal.com',
+    'www.sandbox.paypal.com',
+    'pay.google.com',
+    'applepay.cdn-apple.com',
+    'js.stripe.com',
+    'checkoutshopper-live.adyen.com',
+    '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;
+
+function getIntentRouteClass(pathname: string): 'checkout_path' | 'other' {
+    return checkoutPath.test(pathname) ? 'checkout_path' : 'other';
+}
+
+function normalize(text: string | null | undefined): string | undefined {
+    if (!text || text.length > 128) {
+        return undefined;
+    }
+    return text
+        .toLowerCase()
+        .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 labelSources(element: Element): Array<string | null> {
+    if (
+        element.children.length > 4 ||
+        element.querySelector('input, select, textarea, [data-mp-no-track]')
+    ) {
+        return [];
+    }
+    let text: string | null = null;
+    if (element instanceof HTMLInputElement) {
+        const type = element.type;
+        if (type === 'submit' || type === 'button') {
+            text = element.value;
+        } else if (type === 'image') {
+            text = element.getAttribute('alt');
+        }
+    } else {
+        text = element.textContent;
+    }
+    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
+): Exclude<CheckoutIntentKind, 'frame'> | undefined {
+    if (
+        commits.test(text) ||
+        (routeGatedCommits.test(text) &&
+            getIntentRouteClass(pathname) === 'checkout_path')
+    ) {
+        return 'commit';
+    }
+    if (button && wallets.test(text)) {
+        return 'wallet';
+    }
+    if (steps.test(text)) {
+        return 'checkout_step';
+    }
+    return undefined;
+}
+
+export function classifyIntentControl(
+    path: Array<EventTarget | null>,
+    pathname: string
+): CheckoutIntentKind | 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;
+    }
+    let button = false;
+    if (!control.matches('a[href]')) {
+        button = control.matches(CONTROL_SELECTOR) || isWalletElement(control);
+    }
+    if (button && isWalletElement(control)) {
+        return 'wallet';
+    }
+    for (const text of texts) {
+        const kind = classifyLabel(text, button, pathname);
+        if (kind) {
+            return kind;
+        }
+    }
+    return undefined;
+}
+
+// Focus moving into a visible hosted wallet or payment frame.
+export function classifyIntentFrame(
+    target: EventTarget | null,
+    win: Window
+): 'frame' | undefined {
+    if (
+        win.document.visibilityState !== 'visible' ||
+        !(target instanceof HTMLIFrameElement)
+    ) {
+        return undefined;
+    }
+    if (isRoktElement(target)) {
+        return undefined;
+    }
+    try {
+        const url = new URL(target.src);
+        if (url.protocol === 'https:' && frameHosts.has(url.hostname)) {
+            return 'frame';
+        }
+    } catch (e) {
+        // An unparseable frame src is not a wallet frame.
+    }
+    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;
+}