Skip to main content
Sends a recommendation view event to Constructor.io’s API. This tracks when a recommendation pod or widget is displayed to a user, which is essential for measuring recommendation performance.

​
Method Signature

constructorio.tracker.trackRecommendationView(parameters, networkParameters?)

​
Parameters

​
parameters
object
required
Parameters for the recommendation view event
​
networkParameters
object
Optional parameters for the network request

​
Returns

Returns true on success or an Error object if validation fails.

​
Examples

​
Basic Example

import ConstructorIOClient from '@constructor-io/constructorio-client-javascript';

const constructorio = new ConstructorIOClient({
  apiKey: 'YOUR_API_KEY',
});

// Track recommendation view
constructorio.tracker.trackRecommendationView({
  url: window.location.href,
  podId: 'home_page_bestsellers',
  numResultsViewed: 4,
  items: [
    { itemId: 'ITEM-001' },
    { itemId: 'ITEM-002' },
    { itemId: 'ITEM-003' },
    { itemId: 'ITEM-004' },
  ],
});

​
Complete Example

// Track recommendation view with all parameters
constructorio.tracker.trackRecommendationView({
  url: window.location.href,
  podId: 'pdp_similar_items',
  numResultsViewed: 5,
  items: [
    { itemId: 'ITEM-001', itemName: 'Similar Product 1' },
    { itemId: 'ITEM-002', itemName: 'Similar Product 2' },
  ],
  resultCount: 20,
  resultPage: 1,
  resultId: '019927c2-f955-4020-8b8d-6b21b93cb5a2',
  section: 'Products',
  seedItemIds: ['CURRENT-ITEM-123'],
});

​
Integration Example

// Track after loading recommendations
async function loadRecommendations(podId) {
  const response = await constructorio.recommendations.getRecommendations(
    podId,
    { numResults: 10 }
  );
  
  // Render recommendations
  const recommendationWidget = renderRecommendations(response.results);
  
  // Track when widget becomes visible
  const observer = new IntersectionObserver((entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        const items = response.results.map(item => ({
          itemId: item.data.id,
        }));
        
        constructorio.tracker.trackRecommendationView({
          url: window.location.href,
          podId: podId,
          numResultsViewed: items.length,
          items: items,
          resultCount: response.total_num_results,
          resultId: response.result_id,
        });
        
        observer.unobserve(entry.target);
      }
    });
  });
  
  observer.observe(recommendationWidget);
}

​
Example with Seed Items

// Track item-based recommendations (e.g., "Similar Items")
constructorio.tracker.trackRecommendationView({
  url: window.location.href,
  podId: 'similar_items',
  numResultsViewed: 4,
  items: [
    { itemId: 'SIMILAR-001' },
    { itemId: 'SIMILAR-002' },
  ],
  seedItemIds: ['CURRENT-ITEM-123'], // The item being viewed
  resultId: '019927c2-f955-4020-8b8d-6b21b93cb5a2',
});

​
Multiple Recommendation Pods Example

// Track multiple recommendation widgets on same page
const recommendationPods = [
  { podId: 'frequently_bought_together', selector: '#fbt-widget' },
  { podId: 'recently_viewed', selector: '#recent-widget' },
  { podId: 'trending_now', selector: '#trending-widget' },
];

recommendationPods.forEach(async (pod) => {
  const response = await constructorio.recommendations.getRecommendations(
    pod.podId
  );
  
  const items = response.results.map(item => ({
    itemId: item.data.id,
  }));
  
  constructorio.tracker.trackRecommendationView({
    url: window.location.href,
    podId: pod.podId,
    numResultsViewed: items.length,
    items: items,
    resultId: response.result_id,
  });
});

​
When to Use

Call trackRecommendationView() when:
  • A recommendation widget becomes visible on the page
  • Recommendations are loaded and rendered
  • A user scrolls to view a recommendation pod
  • A carousel or slider with recommendations is displayed

​
Important Notes

  • Always include the resultId from Constructor.io’s recommendations response
  • Track when recommendations become visible, not just when they’re loaded
  • The podId should match the pod ID used in the recommendations API call
  • The numResultsViewed should reflect how many items are actually visible
  • Use Intersection Observer API to track visibility accurately

​
Pod ID Examples

Common pod IDs:
  • "home_page_recommendations" - Homepage recommendations
  • "pdp_similar_items" - Similar items on product pages
  • "pdp_frequently_bought_together" - Frequently bought together
  • "cart_page_recommendations" - Recommendations on cart page
  • "recently_viewed" - Recently viewed items

​
Seed Items

For item-based recommendations, include the seed item(s): 
// Single seed item
seedItemIds: 'ITEM-123'

// Multiple seed items
seedItemIds: ['ITEM-123', 'ITEM-456']

// Numeric item ID
seedItemIds: 123

​
Tracking Visibility

Use Intersection Observer to track when recommendations become visible: 
const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach(entry => {
      if (entry.isIntersecting) {
        constructorio.tracker.trackRecommendationView({
          url: window.location.href,
          podId: 'home_recommendations',
          numResultsViewed: 4,
          items: getVisibleItems(),
        });
        observer.unobserve(entry.target);
      }
    });
  },
  { threshold: 0.5 } // Track when 50% visible
);

observer.observe(document.querySelector('#recommendation-widget'));

​
Relationship with Other Events

Track these events in sequence:
  1. trackRecommendationView - When recommendations are displayed (this method)
  2. trackRecommendationResultClick - When user clicks a recommendation
  3. trackConversion - If the click leads to a conversion

​
API Endpoint

This method sends a POST request to: 
/v2/behavioral_action/recommendation_result_view

Build docs developers (and LLMs) love

Get started for freeTalk to us