Overview

Embed personalised product recommendations on any page of your website using the Unbxd Recs SDK. Integrating the Recs SDK involves three steps. Each is described in detail in the sections that follow.

Add the SDK Script: Include the region-specific V3 SDK URL in the root HTML of every page where recommendations will appear.
Place Widget Containers: Add <div> elements with unique IDs at each position on the page where a recommendation widget should render.
Call getUnbxdRecommendations(): Invoke the SDK function with a context object that describes your widgets, user, and current page.

Add the SDK Script

Add the region-specific Recs SDK <script> tag to the <head> or end of <body> on every page where recommendations will be displayed. Make sure you are using the V3 URL provided by Unbxd.

<!-- Add in <head> or end of <body> on every recommendations page -->
<script src="https://<region-specific-unbxd-recs-sdk-v3-url>"></script>

📘
Note
Contact your Unbxd account team to obtain the correct region-specific V3 SDK URL for your deployment.

Place Widget Containers

At each location on your page where you want a recommendation widget to appear, add a <div> with a unique ID. The SDK will render the widget inside these elements.

<!-- Widget 1 placement -->
<div id="product_recommendations1"></div>

<!-- Widget 2 placement -->
<div id="product_recommendations2"></div>

<!-- Widget 3 placement -->
<div id="product_recommendations3"></div>

Each id corresponds to the selector value you will specify in the widgets array in Step 3.

Call the SDK Function

Once the script is loaded and the containers are in place, call getUnbxdRecommendations() and pass a context object as its argument. The SDK will fetch the recommendations and render them inside the corresponding containers.

Function Signature:

getUnbxdRecommendations(context);

Full Context:

const context = {

  // REQUIRED — Widget targets (array)
  widgets: [
    { name: "Widget1", selector: "product_recommendations1" },
    { name: "Widget2", selector: "product_recommendations2" },
    { name: "Widget3", selector: "product_recommendations3" }
  ],

  // REQUIRED — User and site credentials
  userInfo: {
    userId:  'uidValue',
    siteKey: 'siteKeyValue',
    apiKey:  'apiKeyValue'
  },

  // REQUIRED — Page context
  pageInfo: {
    pageType:   'PRODUCT',
    productIds: ['uniqueId1', 'uniqueId2']
  },

  // OPTIONAL — Fires when a recommended product is clicked
  itemClickHandler: function (product) {
    alert(JSON.stringify(product));
  },

  // OPTIONAL — Modify API response data before it reaches the template
  dataParser: function (templateData) {
    // Transform data as needed, then return it
    return templateData;
  }

};

getUnbxdRecommendations(context);

Context Objects

The context object is the JavaScript object you pass to getUnbxdRecommendations() to tell the SDK everything it needs to fetch and display recommendations. It has five keys:

Key	Requirement	Description
widgets	Required	An array that specifies which DOM elements will display recommendations and which widget configuration to use for each.
userInfo	Required	Contains `userId`, `siteKey`, and `apiKey`. These are used by the SDK to authenticate and personalize recommendations for the user.
pageInfo	Required	Defines the page type (HOME, PRODUCT, CART, CATEGORY, BOUTIQUE). Some page types may require additional fields like `productIds` or `catlevel1Name` for accurate recommendations.
itemClickHandler	Optional	A callback function triggered when a user clicks on a recommended product. Useful for tracking user interactions or executing custom logic.
dataParser	Optional	A callback function that allows you to modify or transform API response data before it is passed to the template. Useful for custom UI implementations.

Context: Widget

An array of widget configuration objects. Each object maps a named widget to a DOM element on the page. At least one widget must be provided. Up to three widgets are supported.

Key	Type	Description
name	String	The name identifier for the widget (e.g. "Widget1", "Widget2", "Widget3").
selector	String	The id of the target DOM element where this widget will be rendered.

widgets: [
  { name: "Widget1", selector: "product_recommendations1" },
  { name: "Widget2", selector: "product_recommendations2" },
  { name: "Widget3", selector: "product_recommendations3" }
]

Context: userInfo

This is a required field. It has authentication and identification details for the current user and site.

Key	Type	Description
userId	String	User tracking ID used to personalise recommendations for the visitor.
siteKey	String	Site key provided by Unbxd during onboarding.
apiKey	String	API key provided by Unbxd during onboarding.

userInfo: {
  userId:  'uid',
  siteKey: 'site-key',
  apiKey:  'apiKey'
}

Context: pageInfo

This is a required field. It describes the type of page the visitor is currently viewing. The SDK uses this information to determine which recommendation strategy to apply.

Supported Page Types are:

HOME: Site homepage.
PRODUCT: A single product detail page.
CART: Shopping cart or checkout page.
CATEGORY: A product category listing page.
BOUTIQUE (New in V3): A boutique-style curated page.

Parameters:

Key	Type	Required When	Description
pageType	String	Always	One of: HOME, PRODUCT, CART, CATEGORY, BOUTIQUE.
productIds	String	PRODUCT or CART	Array of product IDs relevant to the current page.
catlevel1Name	String	CATEGORY	First (top-level) category name. Required for category pages.
catlevel2Name	String	Optional (CATEGORY)	Second-level subcategory name.
catlevel3Name	String	Optional (CATEGORY)	Third-level subcategory name.
catlevel4Name	String	Optional (CATEGORY)	Fourth-level subcategory name.
boutiqueButton	Boolean	Optional	Set to `true` to display a redirect button to the Boutique page within the widget template

📘
Important Point to Remember

Category level ordering: Category level values must be provided in contiguous order starting with catlevel1Name. If a level is skipped, all subsequent levels are ignored by the SDK and will not be used to fetch recommendations.

Category Example:

pageInfo: {
  pageType:      'CATEGORY',
  catlevel1Name: 'Women',
  catlevel2Name: 'Clothes',
  catlevel3Name: 'Top',
  catlevel4Name: 'Denim'
}

Context: Callback Handlers

The context object accepts two optional callback functions that let you hook into the SDK's lifecycle.

itemClickHandler(Optional)

Key	Type	Description
itemClickHandler	Function	Called when a visitor clicks a recommended product. Receives a single argument containing all product attributes returned by the recommendations platform.

itemClickHandler: function (product) {
  // 'product' contains all attributes from the recommendations platform
  alert(JSON.stringify(product));
}

dataParser(Optional)

Key	Type	Description
dataParser	Function	Called just before the recommendation data is passed to the template. Use this to transform the API response if you need to restructure data for a custom template—avoiding the need to write parsing logic inside the template itself. Must return the (modified) data.

dataParser: function (templateData) {
  // Modify templateData as needed, then return it
  return templateData;
}

Examples

Refer to the code examples below for complete, ready-to-use function calls for specific page types.

Home Page

getUnbxdRecommendations({

  widgets: [
    { name: "Widget1", selector: "home_recommendations1" },
    { name: "Widget2", selector: "home_recommendations2" },
    { name: "Widget3", selector: "home_recommendations3" }
  ],

  userInfo: {
    userId:  'uidValue',
    siteKey: 'siteKeyValue',
    apiKey:  'apiKeyValue'
  },

  pageInfo: {
    pageType: 'HOME'
  },

  itemClickHandler: function (product) {
    alert(JSON.stringify(product));
  },

  dataParser: function (templateData) {
    return templateData;
  }

});

Boutique Page(New in V3)

The BOUTIQUE page type is introduced in V3 and follows the same structure as a HOME page. Additionally, you can enable a redirect button to the Boutique page by setting boutiqueButton: true inside pageInfo. The client controls which pages display this button.

const context = {

  widgets: [
    { name: "Widget1", selector: "home_recommendations1" },
    { name: "Widget2", selector: "home_recommendations2" },
    { name: "Widget3", selector: "home_recommendations3" }
  ],

  userInfo: {
    userId:  'uidValue',
    siteKey: 'siteKeyValue',
    apiKey:  'apiKeyValue'
  },

  pageInfo: {
    pageType:      'HOME',
    boutiqueButton: true   // enables the boutique redirect button
  },

  itemClickHandler: function (product) {
    alert(JSON.stringify(product));
  },

  dataParser: function (templateData) {
    return templateData;
  }

};

getUnbxdRecommendations(context);

Migration from V2 to V3

If you are upgrading an existing V2 integration, the following changes are required. All other context parameters (userInfo, pageInfo, and the callback handlers) remain the same between versions.

Update the SDK Script URL: Replace the V2 SDK URL in your root HTML with the V3 URL provided by Unbxd.
Rename the function call

In V2, the function was called _unbxd_getRecommendations(context)
In V3, it has been renamed to getUnbxdRecommendations(context)

Change widgets from an object to an array In V2, widgets was a plain object with named keys. In V3, it must be passed as an array of widget objects, each containing a name and a selector.

V2 objects	V3 array
`widgets: { widget1: { name: "home_rec1" }, widget2: { name: "home_rec2" }, widget3: { name: "home_rec3" } }`	`widgets: [ { name: "Widget1", selector: "home_rec1" }, { name: "Widget2", selector: "home_rec2" }, { name: "Widget3", selector: "home_rec3" } ]`

V2 objects

V3 array

widgets: {
  widget1: {
    name: "home_rec1"
  },
  widget2: {
    name: "home_rec2"
  },
  widget3: {
    name: "home_rec3"
  }
}

widgets: [
  {
    name: "Widget1",
    selector: "home_rec1"
  },
  {
    name: "Widget2",
    selector: "home_rec2"
  },
  {
    name: "Widget3",
    selector: "home_rec3"
  }
]

👍
Good to Know
The BOUTIQUE page type and the boutiqueButton parameter are exclusive to V3 and are not available in V2.