Quickstart: Integrating Recco.js for on-site recommendations

Introduction

This guide provides the fastest way to build a feature-rich and interactive recommendation widget on your website using the Recco.js library. This library is the recommended integration path for most websites, as it handles all the complex parts for you: it makes the API calls, renders a professional UI, and automatically tracks all necessary analytics to improve recommendation quality over time. By the end of this guide, you will have a fully functional recommendation widget displaying relevant products on any page of your site.

What you'll learn

  • How to add a recommendation widget to a page (e.g., a product detail page).
  • How to include and initialize the Recco.js library with essential configurations.
  • How to configure the widget to show specific recommendation types, such as "similar items" or "frequently bought together."

Who is this guide for

  • Developers looking for a fast, out-of-the-box solution for on-site recommendations.
  • Users who want to quickly implement powerful recommendation models without needing to work directly with the API.

Prerequisites

Before you start, please ensure you have the following in place:

  • The ability to edit HTML and add JavaScript to your website.
  • Your Luigi's Box TrackerId.
  • An existing page, such as a product detail page, where a unique product ID is available.

Step-by-step: Building the recommendation widget

Step 1: Choose a page and add a placeholder

First, decide where you want to display recommendations. Product detail pages, shopping carts, and homepages are all excellent choices. On your chosen page, add an empty placeholder element where Recco.js will render the recommendation interface. If the element is not empty, its contents will be replaced.

Example: Placeholder on a product detail page

<!-- Your product detail content -->
<div class="product-details">
  <h1>Awesome T-Shirt</h1>
  <p>Product ID: TSHIRT-123</p>
  <!-- Other product info -->
</div>

<!-- This is the placeholder where the recommender UI will be rendered -->
<div id="recommender-alternatives">
  <!-- Optional: Add a loading spinner for a better user experience -->
</div>

<!-- Other page content -->

Step 2: Add and initialize the Recco.js script

Next, add the following script block just before the closing </body> tag on your page. This will load and initialize the Recco.js library. The configuration tells Luigi's Box what to recommend and where to render it. In this example, we will configure a recommender to show alternative items on a product detail page.

Example: Initialize Recco.js for "similar items"

<!-- Add this script at the end of your <body> -->
<script src="https://cdn.luigisbox.com/recco.js"></script>
<script>
  // This initializes the Luigi's Box Recommender UI
  Luigis.Recommend(
    {
      // --- Configuration Start ---
      TrackerId: 'YOUR_TRACKER_ID', // Replace with your actual Tracker ID
      Theme: 'luigis',              // Use the 'luigis' theme for a modern look
      Size: 4,                      // The number of items you want to display

      // Specify which recommender model to use.
      // 'item_detail_alternatives' is perfect for showing similar items on a product page.
      Type: 'item_detail_alternatives',

      // This function tells the recommender which product to base its recommendations on.
      // In a real application, you would get this ID dynamically from your page.
      GetItemIds: function() {
        return ['TSHIRT-123']; // The ID of the product the user is currently viewing
      },
      // --- Configuration End ---
    },
    '#recommender-alternatives'    // CSS selector for the placeholder element
  );
</script>

Step 3: Verify your integration

You're all set! To verify the integration:

  1. Open the page where you added the script (e.g., the product detail page for "TSHIRT-123").
  2. You should see a fully styled recommendation widget appear inside your #recommender-alternatives div
  3. The widget will display products from your catalog that are considered alternatives to the main product on the page.

Best practices

  • Automatic analytics: A key advantage of Recco.js is that it automatically handles sending all necessary analytics events. You do not need to implement any manual tracking.
  • Theming: The Theme option is a powerful way to control the look and feel. Luigi's Box recommends starting with 'luigis' for a modern, responsive design that works well on all devices.
  • Dynamic product IDs: In the example, we used a hardcoded product ID ('TSHIRT-123'). For a real-world application, your GetItemIds function must be able to dynamically get the current product's ID from your page's data or HTML.

Next steps

Now that you have a basic recommender running, you can explore more advanced features: