Recommendation Tracking

The Recommendation Tracking extension enables product-level analysis of recommendation widgets in Mapp Intelligence.

It records when recommended products are loaded into a widget, become viewable on screen, and are clicked, and sends additional widget context, such as placement, product position, and algorithm. If a recommended product is clicked and later purchased within seven days, the stored widget context is included in the purchase request. Attribution follows a last-click approach.

These values are passed via predefined E-Commerce parameters.

Full implementation guide

This page documents the Smart Pixel interface of the extension. For the product statuses and what triggers them, setup, parameter requirements, testing and reporting, see the dedicated Recommendation Tracking plugin documentation.

Methods and properties

name

Get the name of the extension.

/**
 * @type {string}
 */
wtSmart.extension.recommendation_tracking.name;

version

Get the version of the extension.

/**
 * @type {string}
 */
wtSmart.extension.recommendation_tracking.version;

config

Set and get the current configuration of the extension.

• viewPercent: Specify what percentage of the height and width of a reco element has to be visible in the user's viewport to recognize the reco as "viewed." Default is 100.

• viewTime: Specify how long a reco element has to stay visible within the user's viewport to recognize the reco as "viewed." Value in milliseconds, default is 1000.

• maxSendProducts

  • session: Maximum number of recommendation tracking events sent per browser session. Once this limit is reached, no additional recommendation events are sent in the same session. Use -1 to track all.

  • page: Maximum number of recommendation tracking events sent per page view. Once this limit is reached, no further recommendation events are sent on the current page view. Use -1 to track all.

• maxCookieSize: Maximum size of the recommendation tracking cookie (in characters).

  When the cookie is full and a new recommendation needs to be stored, the oldest entry is removed and the new one is added.

  Use -1 to disable cookie usage. In this case, recommendation clicks and subsequent purchases are no longer linked for conversion attribution.

Note

viewPercent and viewTime are applied when a recommendation element is registered. Changing them afterwards has no effect on elements that are already registered, and the same values apply on every screen size. Pick values that work for the smallest layout your widget is displayed in: a threshold that is too high means products count as loaded and clicked but never as viewable, while a threshold that is too low counts products the visitor had no real chance to see.

/**
 * @param {{
 *      [viewPercent=100]: number,
 *      [viewTime=1000]: number,
 *      [maxSendProducts]: {
 *          [session=10000]: number,
 *          [page=1000]: number
 *      },
 *      [maxCookieSize=4000]: number
 * }} [config]
 *
 * @returns {object}
 */
wtSmart.extension.recommendation_tracking.config(config);

isActivated

Get the status of whether the extension is enabled.

/**
 * @returns {boolean}
 */
wtSmart.extension.recommendation_tracking.isActivated();

activate

Activate the extension.

wtSmart.extension.recommendation_tracking.activate();

deactivate

Deactivate the extension.

wtSmart.extension.recommendation_tracking.deactivate();

add

After the Recommendation Tracking extension has been integrated and activated, you must explicitly define which elements on your website should be tracked as recommendations.

Loaded events are triggered automatically as soon as elements matching the selector appear in the DOM. This also works for lazy-loaded content and SPA environments, as no separate event is required. Viewable and clicked events follow from the visitor scrolling the product into view and clicking it.

• selector: CSS selector or direct element reference for the recommendation element. All default clickable elements inside it will be tracked (a, area, button, input[type="submit"]).

• shadowRoot: CSS selector of a shadow DOM root, if the selector is located inside a shadow DOM.

• exclude: Array of CSS selectors or elements to exclude from recommendation click tracking (e.g., legal links).

data

Note

The recommendation tracking cookie stores all fields provided in the data object (e.g., id, placement, algorithm, position) for up to seven days so they can be included in the purchase request if the product is bought later.

/**
 * @param {{
 *      selector: string | HTMLElement,
 *      [shadowRoot]: string,
 *      [exclude]: string[] | HTMLElement[],
 *      data: {
 *          id: string,
 *          cost: string | number,
 *          [productId]: string,
 *          [currency]: string,
 *          [placement]: string,
 *          [algorithm]: string,
 *          [occasion]: string,
 *          [position]: string | number
 *      }
 * }} item
 */
wtSmart.extension.recommendation_tracking.add({
    selector: "li.item:nth-of-type(2)",
    shadowRoot: "#product-collection",
    exclude: ["li.item:nth-of-type(2) a:last-child"],
    data: {
        id: 'MP-12',
        cost: 19.95,
        productId: 'MP',
        currency: 'EUR',
        placement: 'pdp',
        algorithm: 'similar items',
        occasion: 'casual',
        position: 3
    }
});

Example

// is recommendation tracking activated
var isActivated = wtSmart.extension.recommendation_tracking.isActivated();

// set recommendation tracking config
wtSmart.extension.recommendation_tracking.config({
    viewPercent: 100,
    viewTime: 1000,
    maxSendProducts: {
        session: 10000,
        page: 1000
    },
    maxCookieSize: 4000
});

// activate recommendation tracking
wtSmart.extension.recommendation_tracking.activate();

// deactivate recommendation tracking
wtSmart.extension.recommendation_tracking.deactivate();

Testing your implementation

Recommendation events can be checked in the Mapp Cloud Debugger. The events, how to trigger them and what to look for are documented in Step 3: Registering Recommendation.