The Recommendations module provides methods to retrieve personalized product recommendations based on various strategies.
Getting Started The recommendations module is available on your Constructor.io client instance:
const ConstructorioClient = require ( '@constructor-io/constructorio-client-javascript' ); const constructorio = new ConstructorioClient ({ apiKey: 'YOUR_API_KEY' , }); // Access the recommendations module constructorio . recommendations . getRecommendations ( 'best-sellers' );
Methods getRecommendations Retrieve personalized recommendations for a specific pod.
A “pod” is a recommendation strategy configured in your Constructor.io dashboard. Each pod has a unique identifier and can use different algorithms (e.g., best sellers, trending, personalized, item-to-item).
Basic Usage
With Parameters
Item-to-Item Recommendations
Search-Based Recommendations
constructorio . recommendations . getRecommendations ( 'best-sellers' ) . then (( response ) => { console . log ( response . response . results ); });
Parameters The unique identifier for the recommendation pod (configured in your Constructor.io dashboard)
Additional parameters to refine results The number of results to return
Item ID(s) to retrieve recommendations for. Required for item-to-item recommendation strategies. Can be a single item ID string or an array of item IDs: // Single item itemIds : 'product-123' // Multiple items itemIds : [ 'product-123' , 'product-456' ]
The search term to use to refine results. Used by search-based recommendation strategies.
The section to return results from
Key/value mapping of filters used to refine results Example: { category : 'shoes' , color : 'blue' , inStock : true }
The variations map object to aggregate variations
Faceting expression to scope search results
Format options to format different aspects of the response
Hidden metadata fields to return
Parameters relevant to the network request Request timeout in milliseconds
Response Structure { "response" : { "results" : [ { "matched_terms" : [ "recommendation" ], "data" : { "id" : "product-123" , "title" : "Blue T-Shirt" , "url" : "/products/product-123" , "image_url" : "https://example.com/image.jpg" , "price" : 29.99 }, "result_id" : "abc123-xyz789" } ], "total_num_results" : 10 , "pod" : { "id" : "best-sellers" , "display_name" : "Best Sellers" } }, "result_id" : "abc123-xyz789" , "request" : { ... } }
Each result item includes a result_id field that should be used when tracking user interactions.
Recommendation Strategies Display your top-performing products: constructorio . recommendations . getRecommendations ( 'best-sellers' , { numResults: 12 , filters: { category: 'clothing' } });
Show recommendations based on user behavior: // Ensure userId is set in client configuration const constructorio = new ConstructorioClient ({ apiKey: 'YOUR_API_KEY' , userId: 'user-123' }); constructorio . recommendations . getRecommendations ( 'for-you' , { numResults: 8 });
Display items similar to a given product: constructorio . recommendations . getRecommendations ( 'similar-items' , { itemIds: 'current-product-id' , numResults: 6 });
Show items commonly purchased with a product: constructorio . recommendations . getRecommendations ( 'bought-together' , { itemIds: 'product-123' , numResults: 4 });
Common Use Cases
Homepage Recommendations
Display personalized or trending products: async function loadHomeRecommendations () { const response = await constructorio . recommendations . getRecommendations ( 'homepage-recs' , { numResults: 12 }); displayProducts ( response . response . results ); }
Product Detail Page
Show similar or complementary products: async function loadProductRecommendations ( currentProductId ) { const [ similar , boughtTogether ] = await Promise . all ([ constructorio . recommendations . getRecommendations ( 'similar' , { itemIds: currentProductId , numResults: 6 }), constructorio . recommendations . getRecommendations ( 'bought-together' , { itemIds: currentProductId , numResults: 4 }) ]); displaySimilarProducts ( similar . response . results ); displayBoughtTogether ( boughtTogether . response . results ); }
Cart Page
Suggest additional items based on cart contents: async function loadCartRecommendations ( cartItemIds ) { const response = await constructorio . recommendations . getRecommendations ( 'cart-recs' , { itemIds: cartItemIds , numResults: 8 }); displayCartRecommendations ( response . response . results ); }
Events The recommendations module dispatches custom events on the browser window when requests complete:
window . addEventListener ( 'cio.client.recommendations.getRecommendations.completed' , ( event ) => { // event.detail contains the response data console . log ( event . detail ); console . log ( 'Pod ID:' , event . detail . response . pod . id ); }, false );
Tracking Recommendations Always track when users interact with recommendations:
function handleRecommendationClick ( product ) { // Navigate to product window . location . href = product . data . url ; // Track the click constructorio . tracker . trackRecommendationClick ( product . data . id , { result_id: product . result_id , pod_id: 'best-sellers' } ); }
