@magento/recommendations-js-sdk

Product Recommendations SDK

The Recommendations JavaScript SDK is a web services API wrapper that allows you to fetch and render recommendations programmatically in the browser. With the SDK, you do not need to manage the full lifecycle or understand the complexity of the web services API.

• Initializing the client
• Registering recommendations
• Registering custom recommendations
• Fetching recommendations
• Injecting recommendations on your web site
• Defining a template
• Rendering a recommendation on your web site

Installing

DataServices Module

Before installing the Product Recommendations JavaScript SDK, make sure you have installed the DataServices Module

Product Recommendations JavaScript SDK

After you have installed the DataServices Module, refer to the readme for information about how to install the Product Recommendations JavaScript SDK.

Initializing the client

To programmatically fetch and render recommendations on your web site, you must first initialize your client by calling new RecommendationsClient().

Example

const client = new RecommendationsClient()

When you initialize the client, your store's instanceId, storeCode, storeViewCode, and websiteCode values are automatically retrieved by the SDK.

Registering recommendations

With the client initialized, register the recommendations you want by calling the client.register() function and specifying the recommendation type. Refer to the following table for more information about the inputs to this function.

Attributes

Input	Description
name	The user-specified name of the recommendation unit
type	Options: people also viewed, more like this, most viewed, most added to cart, and most purchased
filter	String used to filter the results. If you are setting a filter based on price, you must use the base currency specified for your store. Currency conversion is currently not supported when filtering

Examples

The following example registers a recommendation with a type of people also viewed.

client.register({
    name: "Product Page Recommendations",
    type: "people also viewed",
})

The following example shows how to filter a recommendation that has a base price of less than $200.

client.register({
    name: "people also viewed, under $200",
    type: "people also viewed",
    filter: "base_price.1:<200",
})

Registering custom recommendations

Instead of using one of the built-in types, the SDK provides a way to define a custom type by calling the client.register() function and passing in specific search criteria. For example, you can pass in a search query, such as "categories:(159 OR 377)" to register a recommendation that has a category ID of either 159 or 377.

The following table describes the inputs for a custom recommendation.

Attributes

Input	Description
name	The user-specified name of the recommendation unit
search	Defines the search criteria for your custom recommendation. This input contains the signal attribute. In non-custom recommendations, the values specified in this attribute are the types defined above. However, in a custom recommendation, the value is "query". search might also contain a key attribute, such as "categories:(159 OR 377)". The key attribute is not required by all custom recommendations. Some types require you to be on a product page, which would mean you know the current SKU. Other types are more broad, and do not require you to have any specific filter data as they are site wide. Site wide types do not require the key attribute. Possible key values are: user_purchase_history, cart, current_pdp, user_view_history, and <custom query>
boost	User-specified value that indicates the rank of a specific recommendation

Fetching recommendations

You can fetch the registered recommendations by calling the client.fetch() function and specifying the inputs as described in the following table:

Attributes

Input	Description
ids	Specifies the IDs of the recommendations. If unspecified, all recommendations are fetched; otherwise, only those recommendations you specify are fetched
limit	(Optional) Specifies the number of recommendations to fetch. The maximum is 25
offset	(Optional) Specifies where in the recommendations array to begin fetching the recommendations
currentSku	The SKU of the product on the current product page
cartSkus	The SKUs of the products within the cart
userViewHistorySkus	List of SKUs the user recently viewed
userPurchaseHistorySkus	List of SKUs the user recently purchased

Example

const {status, data} = await client.fetch({
    currentSku: "134524",
})

The following shows an example of the fetched recommendations. This example is intentionally truncated.

{
    "units": [
        {
            "unitInstanceId": "45687",
            "unitName": "test-recs",
            "searchTime": 10,
            "totalResults": 3,
            "results": [
                {
                    "rank": 1,
                    "score": 0.38299224,
                    "sku": "35123",
                    "name": "Pursuit Lumaflex™ Tone Band",
                    "shortDescription": null,
                    "type": "simple",
                    "categories": [
                        "gear",
                        "gear/fitness-equipment"
                    ],
                    "weight": 0.0,
                    "weightType": null,
                    "currency": "USD",
                    "image": {
                        "label": "",
                        "url": "http://magento2sc.local/pub/media/catalog/product/cache/fbb00452bcc1f45faf89264b683c708f/u/g/ug02-bk-0.jpg"
                    },
                    "smallImage": {
                        "label": "",
                        "url": "http://magento2sc.local/pub/media/catalog/product/cache/fbb00452bcc1f45faf89264b683c708f/u/g/ug02-bk-0.jpg"
                    },
                    "thumbnailImage": null,
                    "swatchImage": null,
                    "parents": [],
                    "url": "http://magento2sc.local/pursuit-lumaflex-trade-tone-band.html",
                    "prices": {
                        "maximum": {
                            "finalAdjustments": [],
                            "final": 16.0,
                            "regular": 16.0,
                            "regularAdjustments": []
                        },
                        "minimum": {
                            "finalAdjustments": [],
                            "final": 16.0,
                            "regular": 16.0,
                            "regularAdjustments": []
                        }
                    }
                }

Injecting recommendations on your web site

To display recommendations on your web site, you need to define a template for the recommendation then render the recommendation on the web site.

Defining a template

The SDK works with the mustache.js template.

Rendering a recommendation on your web site

The client.render() function creates a string of HTML you can then place on your web site. The following table lists the inputs for the client.render() function.

Attributes

Input	Description
template	A mustache.js HTML template string. Uses reserved variable names such as {{#rec-items}} : {{url}}, {{image}}, {{title}}, {{price}}, which are keys returned in the unit object
unit	An object returned by the client.fetch method that contains the results