Getting Started

The Recommendations SDK enables you to integrate personalized product recommendations into your e-commerce platform. This guide walks you through setting up the SDK to display relevant product recommendations based on page context and user behavior.

Who is this intended for?

This package is designed for developers building e-commerce platforms that require:

Personalized Recommendations: Show relevant products based on user behavior and context
Product Discovery: Help customers discover products on homepage, category pages, and product detail pages
Contextual Recommendations: Display different recommendations based on page type (HOME, PRODUCT, CATEGORY, CART)
Custom Recommendation Widgets: Build custom UI components for displaying recommendations

Prerequisites

Ensure the following before proceeding:

React (v18.2 or higher)
Node.js (v18 or higher)
npm or yarn for package management
A pre-existing React project

Installation

ℹ️

Note:

Make sure you have your Unbxd Site Key and API Key ready before proceeding with the installation.

Install the Recommendations Hooks Package

Add the Unbxd Recommendations hooks package to your project:

npm install @unbxd-ui/react-recs-hooks

Or with Yarn:

yarn add @unbxd-ui/react-recs-hooks

Install the Recommendations Components Package (Optional)

If you want to use pre-built components, add the components package:

npm install @unbxd-ui/react-recs-components

Or with Yarn:

yarn add @unbxd-ui/react-recs-components

Basic Setup

Wrap your application with UnbxdRecsCSRWrapper

The UnbxdRecsCSRWrapper component provides context and state management for recommendations. Wrap your app (or the section where you need recommendations) with this component:

import { UnbxdRecsCSRWrapper } from "@unbxd-ui/react-recs-hooks";
 
function App() {
  return (
    <UnbxdRecsCSRWrapper
      sitekey="YOUR_SITE_KEY"
      apikey="YOUR_API_KEY"
      extraParams={{
        pageType: "HOME",
        uid: "user123"
      }}
      onEvent={({ type, message, value, state }) => {
        console.log("Recs event:", type, message);
      }}
    >
      <YourComponent />
    </UnbxdRecsCSRWrapper>
  );
}

Use the useRecs hook

Inside any component within the wrapper, use the useRecs hook to access recommendation data and functions:

import { useRecs } from "@unbxd-ui/react-recs-hooks";
 
function RecommendationsComponent() {
  const { apiResponse, isLoading, getSingleWidgetResponse } = useRecs();
  
  useEffect(() => {
    // API call is automatically triggered by DataFetcher
  }, []);
  
  // Get a specific widget's recommendations
  const homeWidget = getSingleWidgetResponse("HOME_WIDGET_1");
  
  if (isLoading) {
    return <div>Loading recommendations...</div>;
  }
  
  return (
    <div>
      {homeWidget && (
        <div>
          <h2>{homeWidget.title}</h2>
          {homeWidget.products.map(product => (
            <ProductCard key={product.uniqueId} product={product} />
          ))}
        </div>
      )}
    </div>
  );
}

Configure extraParams based on context

Update extraParams to match your page context:

// For homepage
extraParams={{
  pageType: "HOME",
  uid: userId
}}
 
// For product detail page
extraParams={{
  pageType: "PRODUCT",
  id: productId,
  uid: userId
}}
 
// For category page
extraParams={{
  pageType: "CATEGORY",
  category: ["Electronics", "Laptops"],
  uid: userId
}}
 
// For cart page
extraParams={{
  pageType: "CART",
  uid: userId
}}

Best Practices

Follow these practices to get the most out of the Recommendations SDK:

1. Set Correct Page Type Always set the appropriate pageType in extraParams to ensure you get contextually relevant recommendations:

Use "HOME" for homepage , "PRODUCT" with product id for product detail page recommendations , "CATEGORY" with category array for category page recommendations, "CART" for cart page recommendations.

// Good: Specific page type with context
extraParams={{
  pageType: "PRODUCT",
  id: "product123",
  uid: "user123"
}}
 
// Avoid: Generic page type without context
extraParams={{
  pageType: "HOME"  // When actually on product page
}}

2. Pass User ID for Personalization Always include uid in extraParams to enable personalized recommendations based on user behavior and preferences:

extraParams={{
  uid: getUserId()  // Get from your auth system
}}

3. Update Page Type on Navigation When users navigate between pages, update extraParams prop in UnbxdRecsCSRWrapper to fetch contextually relevant recommendations:

const [extraParams, setExtraParams] = useState({
  pageType: "HOME",
  uid: userId
});
 
useEffect(() => {
  if (currentPage === 'product') {
    setExtraParams({
      pageType: "PRODUCT",
      id: productId,
      uid: userId
    });
  }
}, [currentPage, productId]);
 
<UnbxdRecsCSRWrapper
  extraParams={extraParams}
  // ... other props
>

4. Use Widget Components Leverage the pre-built Widget component from @unbxd-ui/react-recs-components for consistent, optimized recommendation displays:

import { Widget } from "@unbxd-ui/react-recs-components";
 
// Use widget component instead of custom implementation
<Widget widgetId="HOME_WIDGET_1" />

5. Optimize API Calls Avoid unnecessary re-renders and API calls by:

Wrapping UnbxdRecsCSRWrapper at the appropriate level (app-level or page-level, not per component)
Using memoization for callback functions passed to onEvent
Updating extraParams only when context actually changes

6. Track Recommendation Interactions Implement event tracking for recommendation clicks, impressions, and other interactions to measure performance:

<UnbxdRecsCSRWrapper
  onEvent={({ type, value }) => {
    if (type === 'API_CALL_SUCCESS') {
      // Track recommendation impressions
      analytics.track('recommendations_loaded', {
        widgetCount: value?.length,
        pageType: extraParams.pageType
      });
    }
  }}
>

Introduction Changelog