@mparticle/web-sdk 3.16.1 → 3.17.0

package/src/checkoutIntentClassifier.ts

@@ -0,0 +1,231 @@
+// Classifies a click, submit or frame focus as checkout intent. 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',
+]);
+
+const CONTROL_SELECTOR =
+    'button, input[type="submit"], input[type="button"], input[type="image"], [role="button"]';
+
+export function getIntentRouteClass(
+    pathname: string
+): 'checkout_path' | 'other' {
+    return checkoutPath.test(pathname) ? 'checkout_path' : 'other';
+}
+
+// Rokt's own placements and frames never count as partner checkout controls.
+function isRoktElement(element: Element): boolean {
+    if (element.closest('[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;
+}
+
+function isWalletElement(element: Element): boolean {
+    return element.matches(
+        'apple-pay-button, shop-pay-button, .gpay-button, #AmazonPayButton, [data-amazon-pay-button]'
+    );
+}
+
+function normalize(text: string | null | undefined): string | undefined {
+    if (!text || text.length > 128) {
+        return undefined;
+    }
+    return text
+        .toLowerCase()
+        .replace(/[’‘]/g, "'")
+        .replace(/[0-9０-９$€£¥￥₹円.,，]/g, '')
+        .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 labels(element: Element): string[] {
+    if (
+        element.children.length > 4 ||
+        element.querySelector('input, select, textarea')
+    ) {
+        return [];
+    }
+    let text: string | null = null;
+    if (element.tagName.toLowerCase() === 'input') {
+        const typeAttr = element.getAttribute('type');
+        const type = typeAttr ? typeAttr.toLowerCase() : typeAttr;
+        if (type === 'submit' || type === 'button') {
+            text = (element as HTMLInputElement).value;
+        } else if (type === 'image') {
+            text = element.getAttribute('alt');
+        }
+    } else {
+        text = element.textContent;
+    }
+    return [
+        normalize(element.getAttribute('aria-label')),
+        normalize(text),
+    ].filter((label): label is string => !!label);
+}
+
+function classifyLabel(
+    text: string,
+    button: boolean,
+    pathname: string
+): CheckoutIntentKind | 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;
+}
+
+// Walks at most 12 entries of an event's composed path for the nearest control.
+export function classifyIntentControl(
+    path: Array<EventTarget | null>,
+    pathname: string
+): CheckoutIntentKind | undefined {
+    let control: Element | undefined;
+    for (const target of path.slice(0, 12)) {
+        if (!(target instanceof Element)) {
+            continue;
+        }
+        if (isRoktElement(target)) {
+            return undefined;
+        }
+        if (
+            !control &&
+            (target.matches(CONTROL_SELECTOR + ', a[href]') ||
+                isWalletElement(target))
+        ) {
+            control = target;
+        }
+    }
+    if (!control || isRoktElement(control)) {
+        return 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/checkoutIntentTracker.ts

@@ -0,0 +1,244 @@
+import { IMParticleWebSDKInstance } from './mp-instance';
+import {
+    CheckoutIntentKind,
+    classifyIntentControl,
+    classifyIntentFrame,
+} from './checkoutIntentClassifier';
+
+// State lives on `window`, like APV, so a re-executed bundle never doubles the
+// listeners. Inspect `window.__mpCit__` in a console to see if one is live.
+export const WIN_CIT_KEY = '__mpCit__';
+
+const THROTTLE_MS = 2000;
+const SUBMIT_AFTER_COMMIT_CLICK_MS = 1000;
+const PATH_LIMIT = 12;
+
+interface ICitState {
+    tracker?: CheckoutIntentTracker;
+}
+
+type WindowWithCit = Window & {
+    [WIN_CIT_KEY]?: ICitState;
+};
+
+const citWindow = (): WindowWithCit | null =>
+    typeof window === 'undefined' ? null : (window as WindowWithCit);
+
+export const getActiveCheckoutIntentTracker = ():
+    | CheckoutIntentTracker
+    | undefined => {
+    const win = citWindow();
+    const state = win ? win[WIN_CIT_KEY] : undefined;
+    return state ? state.tracker : undefined;
+};
+
+// Stops whichever tracker is active, including one from an earlier bundle load.
+export const resetCheckoutIntentTracking = (): void => {
+    const win = citWindow();
+    if (!win) {
+        return;
+    }
+    const active = getActiveCheckoutIntentTracker();
+    if (active) {
+        active.teardown();
+    }
+    win[WIN_CIT_KEY] = {};
+};
+
+const CAPTURE_PASSIVE: AddEventListenerOptions = {
+    capture: true,
+    passive: true,
+};
+const PASSIVE: AddEventListenerOptions = { passive: true };
+
+// Listens for checkout clicks, submits and wallet frame focus, and hands a
+// frozen {kind, t} to the Rokt kit. No storage, no network, no event logging.
+export class CheckoutIntentTracker {
+    private readonly mpInstance: IMParticleWebSDKInstance;
+    private active = 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 } } = {};
+
+    constructor(mpInstance: IMParticleWebSDKInstance) {
+        this.mpInstance = mpInstance;
+    }
+
+    public get isActive(): boolean {
+        return this.active;
+    }
+
+    public init(): void {
+        const win = citWindow();
+        if (!win) {
+            return;
+        }
+
+        const previous = getActiveCheckoutIntentTracker();
+        if (previous) {
+            previous.teardown();
+        }
+        if (this.active) {
+            this.teardown();
+        }
+
+        if (this.isSuppressed()) {
+            this.log('privacy settings suppress checkout intent, 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);
+
+        this.active = true;
+        if (!win[WIN_CIT_KEY]) {
+            win[WIN_CIT_KEY] = {};
+        }
+        win[WIN_CIT_KEY].tracker = this;
+        this.log('listening');
+    }
+
+    public teardown(): void {
+        const win = citWindow();
+        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);
+
+            const state = win[WIN_CIT_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.lastCommitClick = -Infinity;
+        this.lastSent = {};
+    }
+
+    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 || this.isSuppressed()) {
+            return;
+        }
+
+        const t = Date.now();
+        const pathname = window.location.pathname;
+        const layer = event.type;
+        // The composed path is only populated during dispatch, so copy it now.
+        const path =
+            layer === 'click' && typeof event.composedPath === 'function'
+                ? event.composedPath().slice(0, PATH_LIMIT)
+                : [];
+        let target: EventTarget | null;
+        if (layer === 'submit') {
+            target = (event as Event & { submitter?: Element | null })
+                .submitter;
+        } else if (layer === 'blur') {
+            // Read after the blur settles: some browsers have not moved focus
+            // into the frame yet when the window blurs.
+            target = null;
+        } else {
+            target = event.target;
+        }
+
+        const generation = this.generation;
+        setTimeout(() => {
+            if (generation !== this.generation) {
+                return;
+            }
+            try {
+                let kind: CheckoutIntentKind | undefined;
+                if (layer === 'blur') {
+                    kind = classifyIntentFrame(document.activeElement, window);
+                } else if (layer === 'submit' && target === null) {
+                    // A form submitted without a submitter only counts right
+                    // after a commit click.
+                    kind =
+                        t - this.lastCommitClick <= SUBMIT_AFTER_COMMIT_CLICK_MS
+                            ? 'commit'
+                            : undefined;
+                } else {
+                    kind = classifyIntentControl(
+                        layer === 'submit' ? [target] : path,
+                        pathname
+                    );
+                }
+                if (kind) {
+                    this.emit(kind, layer, t, pathname);
+                }
+            } catch (e) {
+                this.log('[error] classification threw: ' + e);
+            }
+        }, 0);
+    }
+
+    private emit(
+        kind: CheckoutIntentKind,
+        layer: string,
+        t: number,
+        pathname: string
+    ): void {
+        if (this.isSuppressed()) {
+            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
+        );
+    }
+
+    // The Rokt manager owns the privacy gates: flag, opt-out, launcher options
+    // and Global Privacy Control.
+    private isSuppressed(): boolean {
+        const roktManager = this.mpInstance._RoktManager;
+        return !roktManager || roktManager.isCheckoutIntentSuppressed();
+    }
+
+    private log(message: string): void {
+        this.mpInstance.Logger.verbose('mParticle checkout intent: ' + message);
+    }
+}

package/src/constants.ts

@@ -190,6 +190,7 @@ const Constants = {
         CaptureIntegrationSpecificIdsV2: 'captureIntegrationSpecificIds.V2',
         AstBackgroundEvents: 'astBackgroundEvents',
         AutoLogPageView: 'autoLogPageView',
+        CheckoutIntent: 'checkoutIntent',
     },
     DefaultInstance: 'default_instance',
     CCPAPurpose: 'data_sale_opt_out',

package/src/internal-types.ts

@@ -34,6 +34,7 @@ export type {
     RoktKitFilterSettings,
     IRoktKitSettings,
     IRoktKit,
+    ICheckoutIntentSignal,
     IRoktOptions,
     IRoktLauncherOptions,
 } from './roktManager';

package/src/mp-instance.ts

@@ -66,6 +66,10 @@ import {
     PageViewTracker,
     resetPageViewTracking,
 } from './pageViewTracker';
+import {
+    CheckoutIntentTracker,
+    resetCheckoutIntentTracking,
+} from './checkoutIntentTracker';
 
 export interface IErrorLogMessage {
     message?: string;
@@ -99,6 +103,7 @@ export interface IMParticleWebSDKInstance extends MParticleWebSDK {
     _IntegrationCapture: IntegrationCapture;
     _NativeSdkHelpers: INativeSdkHelpers;
     _PageViewTracker?: PageViewTracker;
+    _CheckoutIntentTracker?: CheckoutIntentTracker;
     _Persistence: IPersistence;
     _CookieConsentManager: ICookieConsentManager;
     _ErrorReportingDispatcher: ErrorReportingDispatcher;
@@ -286,6 +291,10 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
     this.reset = function(instance) {
         try {
             instance._Persistence.resetPersistence();
+            // The Rokt manager keeps its own store reference, so stop checkout
+            // intent here rather than relying on the deleted store.
+            resetCheckoutIntentTracking();
+            instance._CheckoutIntentTracker = undefined;
             if (instance._Store) {
                 delete instance._Store;
             }
@@ -311,6 +320,8 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
 
         resetPageViewTracking();
         instance._PageViewTracker = undefined;
+        resetCheckoutIntentTracking();
+        instance._CheckoutIntentTracker = undefined;
 
         if (!keepPersistence) {
             instance._Persistence.resetPersistence();
@@ -1133,6 +1144,13 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
         self._SessionManager.resetSessionTimer();
         self._Store.isEnabled = !isOptingOut;
 
+        if (isOptingOut) {
+            if (self._CheckoutIntentTracker) {
+                self._CheckoutIntentTracker.clearPending();
+            }
+            self._RoktManager.discardCheckoutIntents();
+        }
+
         self._Events.logOptOut();
         self._Persistence.update();
 
@@ -1347,7 +1365,7 @@ export default function mParticleInstance(this: IMParticleWebSDKInstance, instan
 function completeSDKInitialization(apiKey, config, mpInstance) {
     const kitBlocker = createKitBlocker(config, mpInstance);
     const { getFeatureFlag } = mpInstance._Helpers;
-    const { AutoLogPageView } = Constants.FeatureFlags;
+    const { AutoLogPageView, CheckoutIntent } = Constants.FeatureFlags;
 
     // Destroy previous batch uploader to prevent leaked timers and event listeners
     if (mpInstance._APIClient?.uploader) {
@@ -1367,6 +1385,8 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
     // persistence or Identity directly.
     if (mpInstance._Store.webviewBridgeEnabled) {
         mpInstance._NativeSdkHelpers.initializeSessionAttributes(apiKey);
+        // Checkout intent never runs as a native passthrough.
+        resetCheckoutIntentTracking();
     } else {
         // Main SDK initialization flow
 
@@ -1477,6 +1497,21 @@ function completeSDKInitialization(apiKey, config, mpInstance) {
             mpInstance._PageViewTracker.teardown();
         }
 
+        // Checkout intent only feeds the Rokt kit, so it listens only when the
+        // workspace opts in and this init configures a Rokt kit.
+        if (getFeatureFlag(CheckoutIntent) && roktConfig) {
+            if (!mpInstance._CheckoutIntentTracker) {
+                mpInstance._CheckoutIntentTracker = new CheckoutIntentTracker(
+                    mpInstance
+                );
+            }
+            mpInstance._CheckoutIntentTracker.init();
+        } else {
+            // Also retires a tracker left by an earlier bundle load. Like APV,
+            // this assumes a single active SDK instance.
+            resetCheckoutIntentTracking();
+        }
+
         processIdentityCallback(
             mpInstance,
             currentUser,
@@ -1596,6 +1631,8 @@ function runPreConfigFetchInitialization(mpInstance, apiKey, config) {
     mpInstance._LoggingDispatcher.logger = mpInstance.Logger;
     mpInstance._Store = new Store(config, mpInstance, apiKey);
     window.mParticle.Store = mpInstance._Store;
+    // Checkout intent stops until this init's config decides whether it runs.
+    resetCheckoutIntentTracking();
     mpInstance.Logger.verbose(StartingInitialization);
 
     // Initialize CookieConsentManager with privacy flags from launcherOptions