---
title: "Step 3: Registering Recommendation"
slug: "step-3-initializing-the-recommendation-elements"
description: "Register recommended product elements with add(): selector timing, required data fields, one call per product and how to test your implementation."
tags: ["Recommendation Tracking", "Widget Context", "Product Attribution"]
updated: 2026-10-07T10:35:38Z
published: 2026-10-07T10:35:38Z
canonical: "docs.mapp.com/step-3-initializing-the-recommendation-elements"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mapp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Step 3: Registering Recommendation

After activating the Recommendation Tracking extension, you must register the elements on your website that you want to track as recommendations. This is required for all integration methods.

When a recommended product is loaded into a widget, becomes viewable on screen, or is clicked, the extension sends product details along with widget context (placement, algorithm, product position). The three product statuses and what triggers them are described in [Recommendation Tracking](/v1/docs/recommendation-tracking-plugin-intelligence).

If the clicked product is purchased within seven days, the stored widget context is included in the purchase request. Attribution follows a last-click approach.

---

## Register recommendation

Use `add()` to register a recommended product element and the data you want to send for it. Call `add()` once for every product element.

```javascript
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: "MP12",
    cost: 19.95,
    currency: "EUR",
    placement: "pdp",
    algorithm: "similar items",
    occasion: "casual",
    position: 3
  }
});
```

> [!NOTE]
> Note
> 
> The extension evaluates the selector once, about one second after `add()` is called. The product elements must already exist in the DOM at that time. Call `add()` after your widget has rendered, and call it again whenever new product elements are added later, for example after a carousel loads more items, after a route change in a single-page application, or after the widget re-renders. Elements that are already registered are skipped, so a repeated call does not change their data. The loaded event is sent when an element is registered. Viewable and clicked events follow from the visitor scrolling the product into view and clicking it, and need no further registration.

### Fields

| **Field** | **Required** | **Description** |
| --- | --- | --- |
| selector | Yes | CSS selector or DOM element of the recommended product. If the selector matches several elements, all of them receive the same `data`. |
| shadowRoot | No | Selector for a Shadow DOM root if applicable |
| exclude | No | Elements to exclude from click tracking |
| data.id | Yes | Product identifier (same value as used for product tracking) |
| data.cost | Yes | Product price. The extension always sends a quantity of 1. |
| data.currency | No | ISO currency code, e.g., `EUR` |
| data.placement | Yes | Widget placement (e.g., `PDP`, `homepage`) |
| data.algorithm | Yes | Algorithm (e.g., `similar items`, `trending`) |
| data.occasion | No | Occasion of an outfit recommendation (for example `casual`). Only relevant for Mapp Fashion outfit widgets. Sent as E-Commerce parameter 768. |
| data.position | Yes | Product position in widget (e.g., `3`) |
| data.productId | No | ID of the parent product (same value as used for **fashionProductId** in product tracking) |

> [!NOTE]
> Note
> 
> The extension listens for click events on all clickable elements inside the widget (`a`, `area`, `button`, `input[type="submit"]`).

> [!WARNING]
> Warning
> 
> Call `add()` for every product element you want to track. A selector that matches several elements gives all of them the same `id` and `position`, so use one call per product.

### Example

```javascript
// register multiple products inside the same widget
document.querySelectorAll(".recos li.item").forEach((el, index) => {
  wtSmart.extension.recommendation_tracking.add({
    selector: el,
    data: {
      id: el.dataset.sku,
      cost: el.dataset.price,
      currency: "EUR",
      placement: "homepage",
      algorithm: "similar items",
      occasion: "casual",
      position: index + 1
    }
  });
});
```

---

## Testing your implementation

To verify that recommendation events are firing correctly, use your browser's developer tools or the [Mapp Cloud debugger](/v1/docs/mapp-cloud-debugger):

1. Open the page with a recommendation widget and start the Debugger.
2. Trigger the events (widget load, product in view, click, and later a purchase).
3. Check the outgoing requests and verify that the following values are sent:

| **Event** | **How to trigger** | **What you should see in the Mapp Cloud Debugger** |
| --- | --- | --- |
| **Widget product loaded** | Load the page with the recommendation widget. The widget does not have to be scrolled into view. | A product with status `loaded-reco`, or `display-reco` on Smart Pixel versions before 6.12.1, and the configured product fields (`id`, `cost`, `placement`, `algorithm`, `position`). The widget context parameters **765 (placement)**, **766 (product position)** and **767 (algorithm)** appear in the request. |
| **Widget product viewable** | Scroll the product fully into view and leave it on screen for more than a second. | A product with status `viewable-reco`, or `view-reco` on Smart Pixel versions before 6.12.1, plus the same product fields and the widget context parameters **765 / 766 / 767**. Scrolling the same product out of view and back does not produce a second event. |
| **Widget product clicked** | Click a product inside the recommendation widget. | A product with status `click-reco` plus the same product fields and the widget context parameters **765 / 766 / 767**. This confirms that recommendation click tracking works. |
| **Purchase after a recommendation click** | Complete a test purchase for a product that was previously clicked in a recommendation widget (within seven days). | A **normal purchase status** (e.g., `conf`), not a recommendation-specific status, **together with** the widget context parameters **765 / 766 / 767**. These parameters show that the purchase is linked to a prior recommendation click and enables attribution. |

## Related

- [Recommendation Tracking](/recommendation-tracking.md)
- [Step 4: Analyze Recommendation Performance](/step-4-analyze-recommendation-performance.md)
- [Step 1: Creating Recommendation Parameters](/step-1-creating-recommendation-parameters.md)