Written by Dawid Gulbicki

Implementing the on-site Recommendation Box with User.com prediction model

Maximize your website's potential with User.com's product recommendations

User.com's Recommendation Box feature allows you to display personalized product suggestions directly on your website pages, enhancing user engagement and driving sales. This guide details how to implement, customize, and manage these powerful on-site widgets. It covers hosting and managing the JavaScript, the structure of the default script, advanced configurations, deployment strategies, integration of interactive elements, and common use cases.

Displaying recommendations on-site: The Recommendation Box

A Recommendation Box is an embeddable on-site widget. Its core is a JavaScript script integrated into your website's HTML, responsible for:

Communicating with the User.com recommendations API.
Dynamically building the HTML structure for the recommended products.
Injecting or applying the necessary CSS styles.

This script allows you to display a specified number of recommended products within one or more Recommendation Box instances.

Hosting and managing scripts in User.com

You can host your custom JavaScript recommendation scripts directly within the User.com platform (Settings > App settings > Product > Product recommendations). Each script can power a distinct Recommendation Box. This is ideal whether you're customizing the default script or building a completely unique widget from scratch.

Benefits:

Centralized management: Keep all scripts in one place.
Version control: Single source of truth, simplifying updates.
Simplified deployment: User.com provides a simple fetch script to load it onto your website, which is easier than managing large scripts directly or in tag managers with character limits.

Fetch script format:

When a Recommendation Box script is saved in User.com, a unique slug is created from the widget name. Load this hosted script using the automatically generated fetch script:

<script src="https://your_app_name.user.com/predictions/widget/fetch/?slug=your_widget_slug"></script>

The system generates the complete script with your subdomain and slug. Copy it using the "Copy script" button next to your saved widget.

Getting started: The default Recommendation Box script

User.com provides a default JavaScript script (Settings > App settings > Product > Product recommendations) for creating a Recommendation Box. It handles API communication, HTML generation, and basic CSS injection. You can use it as is, customize it extensively, or use it as a reference for building your own scripts, which can then be hosted in User.com as described above.

The default script includes:

Initialization: Creates a global window._UErecommender object.
Configuration (config object):
- placement: CSS selector for the HTML div where recommendations are injected.
- method: HTTP method for API request (usually 'POST').
- apiDomain: Your User.com tenant domain and API endpoint (e.g., 'your_app_name.user.com/predictions/predict-for-user/').
- dataPost: JSON payload for the API request (user_id, userKey, limit, etc.).
- priceCurrency: Currency symbol string (e.g., 'USD', 'zł').
Styling (injectStyle function): Adds predefined CSS rules.
Request handling (getRequest function): Uses XMLHttpRequest to send dataPost to apiDomain.
Rendering logic:
- On successful API response, iterates recommended_products.
- preparingProduct function generates HTML for each product (image, name, price, static "Add to cart" button).
- renderContentHTML injects HTML into the div specified by placement.

You'll likely need to customize the JavaScript (HTML generation and CSS) to match your site.

Advanced configuration & customization

While the default script provides a solid foundation, you'll often want to tailor its behavior or even build a completely custom widget. User.com fully supports hosting your own bespoke JavaScript solutions. The following are examples of possible enhancements and configurations you can implement in your scripts, whether modifying the default or creating your own. For more comprehensive details on the available API configuration options, please refer to this article.

Getting userKey to identify user: Retrieve userKey from the __ca__chat cookie for the /predictions/predict-for-user/ endpoint (cookie consent required).

function getCookie(name) {
  var nameEQ = name + "=";
  var ca = document.cookie.split(';');
  for (let i = 0; i < ca.length; i++) {
    let c = ca[i];
    while (c.charAt(0) == ' ') c = c.substring(1, c.length);
    if (c.indexOf(nameEQ) == 0) return c.substring(nameEQ.length, c.length);
  }
  return null;
}
var userKeyFromCookie = getCookie('__ca__chat');

Fallback to general recommendations: If userKey (or user_id) is unavailable, script can fall back to /predictions/predict/ endpoint. dataPost might send custom_ids: [0] and a segment_id (e.g., "All Available Products").
Using a general segment: Always include a segment_id (e.g., for "All Available Products") in dataPost to ensure recommendations are from relevant items.
Displaying sale price and price formatting:
- Parse API response for sale_price and display accordingly.
- Include logic for consistent price formatting (currency symbols, decimals).
Custom display logic: Develop your own JavaScript to fetch data from User.com recommendation endpoints and render the products in any way that fits your site design for each Recommendation Box. This might involve using a JavaScript carousel library or building custom HTML structures and CSS styles from scratch within your script. Remember, these custom scripts can be hosted directly in User.com.

Example of advanced request payload configuration (Scenario: related to viewed product)

For /predictions/predict/ endpoint to show products related to one the user is viewing.

// Assuming 'currentViewedProductId' holds the ID of the product being viewed
// and 'availableProductsStoreSegmentId' is the ID of your "All Available Products" segment.
// And your app domain is 'your_app_name.user.com'

const recommenderAppConfig = { // This object would be part of your script's config
  appDomain: 'your_app_name.user.com',
  limit: 4,
  segment_id: availableProductsStoreSegmentId,
  custom_ids: [currentViewedProductId],
  extra_data: 0
};

// Your script would then construct the full dataPost object for the API call:
const dataPostBody = {
   limit: recommenderAppConfig.limit,
   segment_id: recommenderAppConfig.segment_id,
   custom_ids: recommenderAppConfig.custom_ids,
   extra_data: recommenderAppConfig.extra_data
};
// And send it to: `https://your_app_name.user.com/predictions/predict`

Deploying your recommender script

Options:

Direct embedding: Embed the <script> tag directly into your website's HTML.
Using a User.com hosted script (recommended): Host JavaScript in User.com and use the fetch script:
<script src="https://your_app_name.user.com/predictions/widget/fetch/?slug=your_widget_slug"></script>. This is the recommended approach for both customized default scripts and entirely custom-built widgets.
Tag management system (e.g., GTM): Deploy script versions using GTM for centralized management without direct code modification.

Integrating interactive buttons (e.g., Add to Cart, Add to Favorites)

Enhance Recommendation Boxes with dynamic interactive buttons.

Custom implementation required:User.com provides product data; your website's JavaScript handles the action (integrating with Shopify, Magento, etc.).

General approach:

Modify JavaScript rendering logic to include HTML for buttons.
Attach JavaScript event listeners to these buttons.
When clicked, the listener:
- Identifies the product (e.g., product_id).
- Executes your e-commerce platform's function/API call to add to cart/favorites.

Collaboration with developers familiar with your e-commerce system is key.

Common Use Cases for on-site product recommendations

Configure your script's dataPost for each use case:

Shopping cart/checkout page: "You might also like"

Goal: Increase average order value.
Endpoint: /predictions/predict/

Request payload (dataPost):

{
  "limit": 3,
  "custom_ids": [/* dynamically populate from cart data */],
  "segment_id": /* ID of 'All Available Products' segment */,
  "extra_data": 0
}

Product detail pages: "Customers who viewed this also liked"

Goal: Encourage product discovery.
Endpoint: /predictions/predict/

Request payload (dataPost):

{
  "limit": 4,
  "custom_ids": [/* ID of current product */],
  "segment_id": /* ID of 'All Available Products' segment */,
  "extra_data": 0
}

Homepage: "Recommended for you" or "Trending products"

Goal: Personalize homepage or highlight popular items.
Endpoint logic: /predictions/predict-for-user/ if userKey available. Fallback to /predictions/predict/.

Request payload ("Recommended for you" - dataPost):

{
  "limit": 5,
  "userKey": "/* current user's userKey */",
  "segment_id": /* ID of 'All Available Products' or 'General Recommendations' segment */,
  "extra_data": 0
}

Request payload (Fallback to "Trending" - dataPost):

{
  "limit": 5,
  "custom_ids": [0],
  "segment_id": /* ID of 'Trending Products' or 'Bestsellers' segment */,
  "extra_data": 1
}

Search through more than a hundred articles on every aspect of User.com