Product Recommendations Installation

This guide will help you install and configure the product recommendations drop-in component in your storefront.

Prerequisites

Before you begin, ensure you have:

Adobe Commerce instance with Product Recommendations enabled
Access to your store’s GraphQL endpoint
Required API keys and credentials
Node.js and npm installed on your development environment

Step-by-step

Use the following steps to install the product recommendations component:

Install the packages

Use a CDN or NPM (recommended for performance) to install the drop-in component tools (@dropins/tools) and product recommendations (@dropins/storefront-recommendations) packages.

npm install @dropins/tools @dropins/storefront-recommendations

<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Your Storefront</title>

  <script src="https://cdn.jsdelivr.net/npm/@dropins/tools@latest"></script>
  <script src="https://cdn.jsdelivr.net/npm/@dropins/storefront-recommendations@latest"></script>
</head>

Map the packages

In the <head> tag of your index.html or head.html file, use an importmap pointed to the node_modules directory, a custom local directory, or CDN (for run-time environments).

This example shows an importmap added to a head.html The importmap points both packages to the local node_modules directory that contains your installed drop-in component files from the drop-in component tools (@dropins/tools) and the product recommendations (@dropins/storefront-recommendations):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/node_modules/@dropins/tools/",
      "@dropins/storefront-recommendations/": "/node_modules/@dropins/storefront-recommendations/",
    }
  }
</script>
<script src="/scripts/scripts.js" type="module"></script>

This example shows an importmap added to a head.html The importmap points both packages to local directories that contain all the optimized/minified files from the drop-in component tools (@dropins/tools) and the product recommendations (@dropins/storefront-recommendations):

<script type="importmap">
  {
    "imports": {
      "@dropins/tools/": "/scripts/__dropins__/tools/",
      "@dropins/storefront-recommendations/": "/scripts/__dropins__/storefront-recommendations/",
    }
  }
</script>
<script src="/scripts/scripts.js" type="module"></script>

This example shows an importmap pointing both packages to a CDN for the drop-in component tools (@dropins/tools) and the product recommendations (@dropins/storefront-recommendations):

<head>
  <script type="importmap">
    {
      "imports": {

        "@dropins/tools/": "https://cdn.jsdelivr.net/npm/@dropins/tools@latest",
        "@dropins/storefront-recommendations/": "https://cdn.jsdelivr.net/npm/@dropins/storefront-recommendations@latest",
      }
    }
  </script>
</head>

With the importmap defined for both runtime and build-time environments, you can now import the required files from these packages into your product recommendations block as described in the next step.

Import the required files

Import the required files from the drop-in components tools (@dropins/tools/fetch-graphql.js', @dropin/tools/initializers.js) and the product recommendations (@dropins/storefront-recommendations) into a JavaScript file for your product recommendations block. The example here shows the imports added to a product-recommendations.js file. These imports constitute the minimum imports you need to create a fully functioning product recommendations for your site:

// component tools
import { initializers } from '@dropins/tools/initializer.js';

// drop-in component functions
import * as pkg from '@dropins/storefront-recommendations/api.js';

// Drop-in component provider
import { render as provider } from '@dropins/storefront-recommendations/render.js';

// Drop-in component containers
import ProductList from '@dropins/storefront-recommendations/containers/ProductList.js';

Connect to the endpoint

Connect your product recommendations component to the Catalog Service GraphQL endpoint and set the required headers as shown in the example below. Replace the endpoint URL and header placeholder values with the actual values from your Commerce backend services:

// Set endpoint configuration
product.setEndpoint('https://<catalog-service-endpoint>/graphql');

product.setFetchGraphQlHeaders({
  // Environment required headers
  'Magento-Environment-Id': 'your-environment-id',
  'Magento-Store-View-Code': 'your-store-view-code',
  'Magento-Website-Code': 'your-website-code',
  'x-api-key': 'your-api-key',
  'Magento-Store-Code': 'main_website_store',
  'Magento-Customer-Group': 'your-customer-group',
  'Content-Type': 'application/json',
});

Register and load the drop-in

The code below shows how to register the product recommendations component, load it (mount), and enable the logger for debugging purposes. You can add these functions within a <script> tag in your product recommendations HTML page as shown here:

<script type="module">
  // more code above...

  // Register and load the Product Recommendations drop-in
  initializers.register(pkg.initialize);

  // Mount Initializers (must be called after all initializers are registered)
  window.addEventListener('load', initializers.mount);
</script>

This function registers the product recommendations component to be loaded on the page by the initializers.mount function.
This event handler triggers the initializers.mount function to load the product recommendations component after the page has loaded.

Recommendation types

The following recommendation types are available:

Type	Description
viewed	Products viewed by other customers
bought	Products bought by other customers
related	Related products based on category
trending	Currently trending products
popular	Most popular products
recently-viewed	Recently viewed products by the current customer

Placement options

You can place recommendations in various locations:

Product page
Category page
Cart page
Checkout page
Home page
Search results page