Tracking Upsell & Cross-Sell Products Shown

This event tracks when recommendation products are displayed to users for analytics and personalization tracking.

// The product shape returned by the recommendation API. Of these, this event reads only
// `id` (required) and `rec_src` — everything else is optional here and shown for context,
// because you normally pass the objects the API already gave you.
interface Product {
  id: string; // Product ID - the only REQUIRED field for this event; must be numeric
  rec_src?: string; // Recommendation source for this product, from the widget response
  l?: string; // Product label/name
  c?: string; // Currency
  u?: string; // Product URL
  p?: string; // Price
  p_min?: string; // Minimum price
  p_max?: string; // Maximum price
  p_c?: string; // Compare at price
  p_min_c?: string; // Minimum compare at price
  p_max_c?: string; // Maximum compare at price
  d?: string; // Description
  t?: string; // Thumbnail image URL
  t2?: string; // Secondary thumbnail URL
  f?: number; // Featured flag
  s?: string; // Variant selector
  sku?: string; // SKU identifier
  p_spl?: number; // Price split flag
  c_date?: number; // Creation date timestamp
  skus?: any[]; // Array of SKUs
  v_c?: number; // Variant count
  iso?: boolean; // ISO flag
  vra?: any[]; // Variations array
  att?: any[]; // Attributes array
}

interface RecommendationsProductsShownEventData {
  products: (Product | string | number)[]; // Required - the products this ONE widget showed
                                           // (see "One call per widget"). A bare numeric id is
                                           // accepted in place of a Product object.
  widget_id: string; // Required in practice - omitting it records the impression with a NULL
                     // widget_id, which the widget-performance pipeline filters out, so the
                     // widget never appears in the dashboard
  id?: string; // Optional - the source product (usually the current product page).
               // The field is named `id`, NOT `sourceProductID`. The CLICK event
               // (RecommendationProductClicked) uses `sourceProductID`; this one does not.
               // Passing `sourceProductID` here is silently ignored and the impression is
               // recorded with no source product.
}

// Example of sending a Recommendations Products Shown event
window.FastSimonSDK.event({
  eventName: window.FastSimonEventName.RecommendationsProductsShown,
  data: {
    products: [ 
      {
        "l": "Classic Running Shoes",
        "c": "USD",
        "u": "/products/fastsimon-demo-site-classic-running-shoes-blue-132131",
        "p": "89.99",
        "p_min": "",
        "p_max": "",
        "p_c": "0.00",
        "p_min_c": "0.00",
        "p_max_c": "0.00",
        "d": "Comfortable running shoes perfect for daily workouts. Features breathable mesh upper and cushioned sole for optimal performance and comfort during your runs.",
        "t": "https://fastsimon-demo-site.myshopify.com/files/running-shoes-blue.jpg",
        "t2": "https://assets.instantsearchplus.com/thumbs/fastsimon-demo-site/a6e46466-e4f9-499b-a7b1-013d5976701b",
        "f": 0,
        "s": "9891167699248::49924203217200",
        "sku": "DEMO-SHOES-001-8.5",
        "p_spl": 0,
        "c_date": 1751897237,
        "id": "9891167699248",
        "skus": [/* list of SKUs */],
        "v_c": 13,
        "iso": false,
        "vra": [/* variations list */],
        "att": [/* attributes list */]
      }
    ], // or a widget's own products from the productRecommendationByWidget callback: response.payload[i].payload
       // (NOT response.payload itself — that is the array of widgets, and passing it breaks reporting)
    widget_id: "17496353898304754", // Required, the widget id from the same widget entry: response.payload[i].widgetID
    id: "9891167650432" // Optional - the source product id. Note: `id`, not `sourceProductID`.
                        // Must be numeric: it is parsed as an int, and a non-numeric value is
                        // recorded as no source product at all.
  }
});

Only two fields are read from each element of products: id, which must be a numeric product id (a numeric string is fine — a handle, title or SKU is dropped), and rec_src, which is carried through to analytics. The rest of the Product interface is shown for context and is not required, so passing bare numeric ids also works and loses only rec_src:

products: [9891167699248, 9891167699249]

One call per widget

Send one RecommendationsProductsShown event per widget, containing all the products that widget displayed — not one event per product. A page with three widgets sends three events, each with its own widget_id and its own product list:

response.payload.forEach((widget) => {
  window.FastSimonSDK.event({
    eventName: window.FastSimonEventName.RecommendationsProductsShown,
    data: { products: widget.payload, widget_id: widget.widgetID, id: currentProductID }
  });
});

Read widget_id from widget.widgetID rather than from the array of ids you requested — the response is ordered by the server, not by your request, so indexing the request array can attach the wrong widget id to a widget's products.

When to Use

Use this event to report when recommendation products are displayed to users:

• Product Page Recommendations: When related/similar products are shown
• Upsell/Cross-sell Widgets: When recommendation widgets render products
• Cart Recommendations: When products are recommended in cart/checkout
• Category Page Recommendations: When recommended products appear on collection pages

Best Practices

1. Call after products are actually visible: Only report when products are rendered and visible to users
2. Include id and rec_src on each product: those are the two fields that are read
3. widget_id: Helps distinguish different recommendation contexts
4. Know what is and is not validated. The SDK does check the product list: it drops any element without a numeric id, and if products was non-empty but nothing survived that filter it logs an error and reports the impression with no product data. What it does not check is the top level — a misnamed sourceProductID instead of id, or a non-numeric source product id, produces no error anywhere and simply records the impression without a source product. So a clean console rules out a bad product list, but not a bad id; confirm that by checking recommendation impressions in the dashboard.

danger

trackViewportImpression does not report this event. It sends a different, grid-level impression to a different endpoint and never records a recommendation-widget impression. Use RecommendationsProductsShown for recommendation widgets.