@mparticle/web-sdk 3.24.0 → 3.25.0

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

@@ -4,6 +4,9 @@ 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 = "Auto Button Click";
+export declare const AUTO_LINK_ATTRIBUTE = "is_auto_link_click";
+export declare const LINK_CLICK_EVENT_NAME = "Auto Link Click";
 export declare const buildButtonClickEvent: (click: IButtonClick, pathname: string) => BaseEvent;
+export declare const buildLinkClickEvent: (click: IButtonClick, pathname: string) => BaseEvent;
 export type ButtonClickBlocker = 'data plan' | 'forwarding rule' | 'event name filter' | 'event type filter';
-export declare const getButtonClickBlocker: (forwarder: IKitFilterSettings, kitBlocker?: KitBlocker) => ButtonClickBlocker | undefined;
+export declare const getButtonClickBlocker: (forwarder: IKitFilterSettings, kitBlocker?: KitBlocker, link?: boolean) => ButtonClickBlocker | undefined;

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

@@ -1,5 +1,5 @@
 export type ButtonElementKind = 'button' | 'input' | 'role' | 'wallet' | 'link';
-export type LinkType = 'same_page' | 'outbound' | 'download';
+export type LinkType = 'same_page' | 'internal' | 'outbound' | 'download';
 export type ButtonLabelSource = 'labelledby' | 'aria' | 'text' | 'alt' | 'title' | 'value' | 'none';
 export interface IButtonClick {
     label?: string;
@@ -18,4 +18,11 @@ export interface IButtonClick {
     fileExtension?: string;
     checked?: boolean;
 }
+export declare function isLinkClick(click: IButtonClick): boolean;
 export declare function describeButtonClick(control: Element, path?: Array<EventTarget | null>): IButtonClick | undefined;
+export interface IPaymentChoice {
+    radio: Element;
+    names: string[];
+}
+export declare function describePaymentChoice(control: Element, path?: Array<EventTarget | null>): IPaymentChoice | undefined;
+export declare function isPicked(radio: Element): boolean;

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

@@ -2,6 +2,8 @@ import { IMParticleWebSDKInstance } from '../mp-instance';
 export declare const WIN_BTN_KEY = "__mpBtn__";
 export interface IButtonTrackerOptions {
     hasRoktKit: boolean;
+    logButtons: boolean;
+    logLinks: boolean;
 }
 export declare const getActiveButtonTracker: () => ButtonTracker | undefined;
 export declare const resetButtonTracking: () => void;
@@ -9,6 +11,8 @@ export declare class ButtonTracker {
     private readonly mpInstance;
     private active;
     private hasRoktKit;
+    private logButtons;
+    private logLinks;
     private generation;
     private lastCommitClick;
     private lastClick;
@@ -37,7 +41,9 @@ export declare class ButtonTracker {
     private uploadNow;
     private cancelUpload;
     private emit;
+    private pickPayment;
     private eventsEnabled;
+    private hasTargetingOptOut;
     private isKitSuppressed;
     private log;
 }

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

@@ -1,4 +1,5 @@
 export type CheckoutIntentKind = 'commit' | 'wallet' | 'checkout_step' | 'frame' | 'cart';
+export type PaymentFrameFamily = 'apple_pay' | 'google_pay' | 'amazon_pay' | 'shop_pay' | 'card';
 export type CheckoutIntentSource = 'vendor' | 'label' | 'brand' | 'frame' | 'submit' | 'name' | 'api';
 export interface ICheckoutIntent {
     kind: Exclude<CheckoutIntentKind, 'frame'>;
@@ -6,4 +7,8 @@ export interface ICheckoutIntent {
 }
 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): 'wallet' | 'frame' | undefined;
+export interface IPaymentFrame {
+    kind: 'wallet' | 'frame';
+    family?: PaymentFrameFamily;
+}
+export declare function classifyPaymentFrame(target: EventTarget | null, win: Window): IPaymentFrame | undefined;

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

@@ -3,10 +3,11 @@ export declare function someComposedAncestor(element: Element, test: (node: Elem
 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 nameWords(value: string | null): string;
 export declare function isWalletNamed(element: Element): boolean;
 export declare function isWalletElement(element: Element): boolean;
 export declare function isQuietIntentControl(control: Element, isVendorWallet: boolean, isCart?: boolean): boolean;
 export declare function isWalletNamedControl(element: Element): boolean;
 export declare function isExcludedPath(path: Array<EventTarget | null>): boolean;
 export declare function findControl(path: Array<EventTarget | null>, included?: boolean): Element | undefined;
-export declare function isUnsafeTextSource(element: Element): boolean;
+export declare function isUnsafeTextSource(element: Element, own?: Element): boolean;

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

@@ -163,6 +163,7 @@ declare const Constants: {
         readonly AstBackgroundEvents: "astBackgroundEvents";
         readonly AutoLogPageView: "autoLogPageView";
         readonly AutoButtonTracking: "autoButtonTracking";
+        readonly AutoLinkTracking: "autoLinkTracking";
     };
     readonly DefaultInstance: "default_instance";
     readonly CCPAPurpose: "data_sale_opt_out";

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

@@ -15,6 +15,11 @@ export interface ICookieConsentFlags {
      * Default: false (targeting is allowed)
      */
     noTargeting: boolean;
+    /**
+     * When true, indicates the user has opted out of the sale or sharing of their data.
+     * Default: false (sharing is allowed)
+     */
+    doNotShareOrSell?: boolean;
 }
 export interface ICookieConsentManager {
     /**
@@ -25,6 +30,10 @@ export interface ICookieConsentManager {
      * Functional tracking is allowed when noFunctional is false (default)
      */
     getNoFunctional: () => boolean;
+    /**
+     * Sharing is allowed when doNotShareOrSell is false (default)
+     */
+    getDoNotShareOrSell: () => boolean;
     /**
      * Syncs the $NoTargeting user attribute based on the current noTargeting flag.
      * Sets the attribute when noTargeting is true, removes it when false.
@@ -32,12 +41,12 @@ export interface ICookieConsentManager {
     syncNoTargetingAttribute: (user: IMParticleUser | null) => void;
 }
 /**
- * CookieConsentManager handles storage and access of consent flags (noFunctional, noTargeting)
- * that are passed via launcherOptions during SDK initialization.
+ * CookieConsentManager handles storage and access of consent flags (noFunctional, noTargeting,
+ * doNotShareOrSell) that are passed via launcherOptions during SDK initialization.
  *
  * These flags allow Rokt integration to respect user privacy choices.
  *
- * Default behavior: Both flags default to false, meaning all features are allowed
+ * Default behavior: All flags default to false, meaning all features are allowed
  * unless explicitly opted out by the user.
  */
 export default class CookieConsentManager implements ICookieConsentManager {
@@ -53,5 +62,10 @@ export default class CookieConsentManager implements ICookieConsentManager {
      * Functional tracking is allowed when noFunctional is false (default).
      */
     getNoFunctional(): boolean;
+    /**
+     * Returns true if the user has opted out of the sale or sharing of their data.
+     * Sharing is allowed when doNotShareOrSell is false (default).
+     */
+    getDoNotShareOrSell(): boolean;
     syncNoTargetingAttribute(user: IMParticleUser | null): void;
 }

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

@@ -4,6 +4,7 @@ export interface IRoktLauncherOptions extends Dictionary<any> {
     noDeviceID?: boolean;
     noFunctional?: boolean;
     noTargeting?: boolean;
+    doNotShareOrSell?: boolean;
     sessionId?: string;
     sessionToken?: string;
 }

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

@@ -9,7 +9,7 @@ import { MPID } from "@mparticle/web-sdk";
 import { IErrorReportingService, ILoggingService } from "./reporting/types";
 import { IRoktLauncherOptions } from "./roktLauncherOptions";
 import IntegrationCapture from "./integrationCapture";
-import type { CheckoutIntentKind, CheckoutIntentSource } from "./buttonTracking/checkoutIntent";
+import type { CheckoutIntentKind, CheckoutIntentSource, PaymentFrameFamily } from "./buttonTracking/checkoutIntent";
 export type RoktAttributeValueArray = Array<string | number | boolean>;
 export type RoktAttributeValueType = string | number | boolean | undefined | null;
 export type RoktAttributeValue = RoktAttributeValueType | RoktAttributeValueArray;
@@ -50,6 +50,12 @@ export interface ICheckoutIntentSignal {
     source?: CheckoutIntentSource;
     pathname?: string;
 }
+export interface IPaymentPickSignal {
+    t: number;
+    pathname: string;
+    names?: readonly string[];
+    family?: PaymentFrameFamily;
+}
 export interface IRoktKitSettings {
     accountId?: string;
     placementAttributesMapping?: string;
@@ -68,6 +74,7 @@ export interface IRoktKit {
     terminate?: () => Promise<void>;
     onRouteChange?: () => void;
     onCheckoutIntent?: (signal: ICheckoutIntentSignal) => void;
+    onPaymentPick?: (signal: IPaymentPickSignal) => void;
     launcherOptions?: Dictionary<any>;
     settings?: IRoktKitSettings;
     integrationName?: string;
@@ -129,10 +136,12 @@ export default class RoktManager {
     private watchRouteChanges;
     private notifyRouteChange;
     setAutoButtonClicksForwarded(forwarded: boolean): void;
+    hasTargetingOptOut(): boolean;
     isCheckoutIntentSuppressed(): boolean;
     isCheckoutIntentLive(): boolean;
     notifyCheckoutIntent(signal: ICheckoutIntentSignal, pathname?: string): void;
     discardCheckoutIntents(): void;
+    notifyPaymentPick(signal: IPaymentPickSignal): void;
     private flushCheckoutIntents;
     isAutoLogPageViewEnabled(): boolean;
     /**

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

@@ -82,6 +82,7 @@ export interface IFeatureFlags {
     astBackgroundEvents?: boolean;
     autoLogPageView?: boolean;
     autoButtonTracking?: boolean;
+    autoLinkTracking?: boolean;
 }
 export interface IStore {
     isEnabled: boolean;

package/package.json

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

package/src/buttonTracking/buttonClickEvent.ts

@@ -12,22 +12,25 @@ export const AUTO_BUTTON_ATTRIBUTE = 'is_auto_button_click';
 // Specific enough not to merge with a customer's own 'Button Click' event.
 export const BUTTON_CLICK_EVENT_NAME = 'Auto 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 = (
+// Marks an automatically logged click on a link that leaves the page.
+export const AUTO_LINK_ATTRIBUTE = 'is_auto_link_click';
+
+export const LINK_CLICK_EVENT_NAME = 'Auto Link Click';
+
+// The attributes both click events carry, with the page fields that auto page
+// views carry. No intent: classifying clicks is left to whoever reads the data.
+const clickAttributes = (
     click: IButtonClick,
     pathname: string
-): BaseEvent => {
+): { [key: string]: string | boolean } => {
     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,
     };
-    // Optional fields are left out when the button has no safe value for them.
+    // Optional fields are left out when the control has no safe value for them.
     const optional: { [key: string]: string | undefined } = {
         label: click.label,
         aria_label: click.ariaLabel,
@@ -49,6 +52,16 @@ export const buildButtonClickEvent = (
     if (click.checked !== undefined) {
         data.checked = click.checked;
     }
+    return data;
+};
+
+// One custom event per button click, logged like logLink() with the auto marker.
+export const buildButtonClickEvent = (
+    click: IButtonClick,
+    pathname: string
+): BaseEvent => {
+    const data = clickAttributes(click, pathname);
+    data[AUTO_BUTTON_ATTRIBUTE] = true;
     return {
         messageType: MessageType.PageEvent,
         name: BUTTON_CLICK_EVENT_NAME,
@@ -57,6 +70,34 @@ export const buildButtonClickEvent = (
     };
 };
 
+// One custom event per click on a link that leaves the page. Typed Other, not
+// Navigation, so no kit reads it as a page change. A plain link to another page
+// of the site goes without its text, which can name the shopper ("Hi, Jane");
+// a button or wallet acting as a link keeps its name.
+export const buildLinkClickEvent = (
+    click: IButtonClick,
+    pathname: string
+): BaseEvent => {
+    const data = clickAttributes(
+        click.linkType === 'internal' && click.element === 'link'
+            ? {
+                  ...click,
+                  label: undefined,
+                  labelSource: 'none',
+                  ariaLabel: undefined,
+              }
+            : click,
+        pathname
+    );
+    data[AUTO_LINK_ATTRIBUTE] = true;
+    return {
+        messageType: MessageType.PageEvent,
+        name: LINK_CLICK_EVENT_NAME,
+        data,
+        eventType: EventType.Other,
+    };
+};
+
 // Every attribute buildButtonClickEvent can set apart from the marker and the
 // hostname, which is the same on every click on this page. A spec checks the
 // two stay in step.
@@ -85,14 +126,15 @@ export type ButtonClickBlocker =
     | 'event name filter'
     | 'event type filter';
 
-// Which check keeps some or all auto button clicks from a kit, or undefined
-// when the kit receives every one. A forwarding rule on an attribute whose
-// value differs between clicks lets some through and not others. Each other
-// check goes through isEventForwarded on its own, so together they decide as
-// it does for each click.
+// Which check keeps some or all auto button clicks, or auto link clicks with
+// `link`, from a kit, or undefined when the kit receives every one. A forwarding
+// rule on an attribute whose value differs between clicks lets some through and
+// not others. Each other check goes through isEventForwarded on its own, so
+// together they decide as it does for each click.
 export const getButtonClickBlocker = (
     forwarder: IKitFilterSettings,
-    kitBlocker?: KitBlocker
+    kitBlocker?: KitBlocker,
+    link = false
 ): ButtonClickBlocker | undefined => {
     const rule = forwarder.filteringEventAttributeValue;
     if (
@@ -106,14 +148,15 @@ export const getButtonClickBlocker = (
     ) {
         return 'forwarding rule';
     }
+    const attributes: { [key: string]: string | boolean } = {
+        hostname: window.location.hostname,
+    };
+    attributes[link ? AUTO_LINK_ATTRIBUTE : AUTO_BUTTON_ATTRIBUTE] = true;
     const click = ({
-        EventName: BUTTON_CLICK_EVENT_NAME,
+        EventName: link ? LINK_CLICK_EVENT_NAME : BUTTON_CLICK_EVENT_NAME,
         EventCategory: EventType.Other,
         EventDataType: MessageType.PageEvent,
-        EventAttributes: {
-            [AUTO_BUTTON_ATTRIBUTE]: true,
-            hostname: window.location.hostname,
-        },
+        EventAttributes: attributes,
     } as unknown) as SDKEvent;
     const checks: Array<[ButtonClickBlocker, Partial<IKitFilterSettings>]> = [
         ['data plan', {}],

package/src/buttonTracking/buttonDescription.ts

@@ -3,6 +3,7 @@ import {
     hasComposedAncestor,
     isUnsafeTextSource,
     isWalletElement,
+    nameWords,
     someComposedAncestor,
 } from './controls';
 import { maskLabel, MAX_RAW_LABEL_LENGTH } from './labelMasking';
@@ -11,8 +12,9 @@ import { maskLabel, MAX_RAW_LABEL_LENGTH } from './labelMasking';
 // hand-written identifiers and kind. Never reads form field values.
 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';
+// A same_page link acts as a button. The others leave the page: to another page
+// of the site, another site or a file.
+export type LinkType = 'same_page' | 'internal' | 'outbound' | 'download';
 
 const DOWNLOAD_EXTENSIONS = /\.(pdf|zip|csv|txt|ics|docx?|xlsx?|pptx?|dmg|exe|apk|mp3|mp4)$/i;
 
@@ -392,8 +394,8 @@ interface ILinkDetails {
 }
 
 // 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.
+// a link that leaves the site and the extension of a file it downloads travel.
+// mailto:, tel: and other schemes give undefined.
 function describeLink(link: Element): ILinkDetails | undefined {
     const href = (link.getAttribute('href') || '').trim();
     if (!href || href.charAt(0) === '#') {
@@ -427,7 +429,13 @@ function describeLink(link: Element): ILinkDetails | undefined {
     return link.pathname === window.location.pathname &&
         link.search === window.location.search
         ? { type: 'same_page' }
-        : undefined;
+        : { type: 'internal' };
+}
+
+// Whether a described click is on a link that leaves the page, logged as a link
+// click rather than a button click.
+export function isLinkClick(click: IButtonClick): boolean {
+    return !!click.linkType && click.linkType !== 'same_page';
 }
 
 // Checkboxes and radios, and the roles that act as them. A role can list
@@ -442,6 +450,12 @@ function boxOf(element: Element): Element | null {
     return box && box.matches(CHOICE) ? box : null;
 }
 
+function isRadio(choice: Element | null): boolean {
+    return choice instanceof HTMLInputElement
+        ? choice.type === 'radio'
+        : !!choice && choice.matches(RADIO_ROLE);
+}
+
 // The box a click on this control picks. One the click passed through below
 // the control comes first: querySelector can't reach a slotted box, a box in a
 // shadow root or the box of a label inside the control, and a row can hold
@@ -463,8 +477,9 @@ function choiceOf(
     return boxOf(control) || control.querySelector(CHOICE);
 }
 
-// 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.
+// Describes a clicked control for auto button and link tracking. A link carries its
+// link type, and one to another scheme is skipped. A role="button" anchor carries one
+// only when it leaves the page; otherwise it stays a plain button.
 export function describeButtonClick(
     control: Element,
     path: Array<EventTarget | null> = []
@@ -475,6 +490,11 @@ export function describeButtonClick(
         if (!link) {
             return undefined;
         }
+    } else if (control.matches('a[href]')) {
+        link = describeLink(control);
+        if (link && link.type === 'same_page') {
+            link = undefined;
+        }
     }
     const element = elementKind(control);
     const box =
@@ -492,10 +512,7 @@ export function describeButtonClick(
     // radio's id, test id and the panel it opens name the option picked, so
     // only the name of its input, the question, goes with it. A wrapper's own
     // name, or a role radio's, can name the option instead.
-    const radio =
-        choice instanceof HTMLInputElement
-            ? choice.type === 'radio'
-            : !!choice && choice.matches(RADIO_ROLE);
+    const radio = isRadio(choice);
     const named = !radio
         ? control
         : choice instanceof HTMLInputElement
@@ -531,3 +548,79 @@ export function describeButtonClick(
         checked: box ? box.checked : undefined,
     };
 }
+
+// A question about payment, read from the names its author gave it, so
+// "checkout[payment_gateway]", "paymentMethod" and "tender_type" all count and
+// "payee" does not. A radio's input name is its question; its group or
+// fieldset speaks only for a radio with no name, as a role radio usually is.
+const PAYMENT_QUESTION = /(?:^| )(?:pay|payment\w*|tenders?|gateways?)(?: |$)/;
+const QUESTION_GROUP = '[role="radiogroup"], fieldset';
+
+function isPaymentQuestion(radio: Element): boolean {
+    const name = radio.getAttribute('name');
+    const group = name ? null : radio.closest(QUESTION_GROUP);
+    const question = group
+        ? [
+              group.getAttribute('id'),
+              group.getAttribute('name'),
+              group.getAttribute('aria-label'),
+          ]
+        : [name];
+    return question.some(words => PAYMENT_QUESTION.test(nameWords(words)));
+}
+
+// What names a payment option: the radio's accessible name, the text and
+// image of each label, and its hand-written ids, text masked like a label.
+function optionNames(radio: Element): string[] {
+    const names: Array<string | undefined> = [
+        maskLabel(accessibleName(radio).raw),
+    ];
+    const labels =
+        radio instanceof HTMLInputElement && radio.labels
+            ? Array.from(radio.labels).slice(0, 2)
+            : [];
+    labels.forEach(label => {
+        if (isShown(label) && !isUnsafeTextSource(label, radio)) {
+            names.push(maskLabel(renderedText(label)));
+            names.push(maskLabel(shownImageAlt(label)));
+        }
+    });
+    names.push(
+        stableIdentifier(radio.getAttribute('id')),
+        firstIdentifier(radio, TEST_ID_ATTRIBUTES)
+    );
+    return names.filter(
+        (name, index) => !!name && names.indexOf(name) === index
+    );
+}
+
+// The payment radio a click picks and the names of its option, for the Rokt
+// kit alone to read a payment method from. A radio's option is the shopper's
+// answer, so these names never go into the logged click.
+export interface IPaymentChoice {
+    radio: Element;
+    names: string[];
+}
+
+export function describePaymentChoice(
+    control: Element,
+    path: Array<EventTarget | null> = []
+): IPaymentChoice | undefined {
+    const choice = choiceOf(control, path);
+    if (
+        !isRadio(choice) ||
+        hasComposedAncestor(choice, '[data-mp-no-track]') ||
+        !isPaymentQuestion(choice)
+    ) {
+        return undefined;
+    }
+    const names = optionNames(choice);
+    return names.length ? { radio: choice, names } : undefined;
+}
+
+// Read once the page has handled the click, which may have cancelled it.
+export function isPicked(radio: Element): boolean {
+    return radio instanceof HTMLInputElement
+        ? radio.checked
+        : radio.getAttribute('aria-checked') === 'true';
+}