@magento/recommendations-js-sdk

Product Recommendations JavaScript SDK

📚 JavaScript library for retrieving and displaying product recommendations.

📦 Installation

This SDK can be pulled down from a CDN or installed as a module from NPM.

CDN

The latest version of the SDK is placed in the latest directory.

<script src="https://sdk.magento-datasolutions.com/latest/index.js"></script>

Specific versions are also published on the CDN under their respective directories.

<script src="https://sdk.magento-datasolutions.com/v0.0.7/index.js"></script>

NPM

npm install @magento/recommendations-js-sdk

🥑 Usage

import {RecommendationsClient} from "@magento/recommendations-js-sdk"

const client = new RecommendationsClient({
    instanceId: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    storeCode: "store-code",
    storeViewCode: "store-view-code",
    websiteCode: "website-code",
})

// status check
await client.ping()

// register a recommendation unit
client.registerUnit({
    unitName: "more like what you bought but under 200",
    filterQueryString: "base_price.1:<=200",
    limit: 5,
    rankerBlended: [
        {
            signal: "shopper_view_view",
            key: "user_view_history",
            boost: 100,
        },
        {
            signal: "shopper_view_view",
            key: "user_purchase_history",
            boost: 10,
        },
    ],
})

// multiple units can be registered
client.registerUnit({
    unitName: "custom query sent",
    limit: 5,
    rankerBlended: [
        {
            signal: "query",
            key: "categories:(159 OR 377)",
            boost: 1,
        },
    ],
})

// retrieve recommendations for all units
const {status, data} = await client.fetchUnits({
    currentSku: "134524",
    cartSkus: ["140805", "140294"],
    userViewHistorySkus: ["96039", "134103", "137685"],
    userPurchaseHistorySkus: ["140307", "94079"],
})

// status: 200
// data: {
//     "units": [
//         {
//             "unitInstanceId": "1234",
//             "unitName": "more like what you bought but under 200",
//             "searchTime": 2,
//             "totalResults": 5,
//             "results": [
//                 {
//                     "rank": 1,
//                     "score": 861.38995,
//                     "sku": "134104",
//                     "name": "PRODUCT ONE",
//                     "base_price": 45.0,
//                     "special_price": 0.0,
//                     "tier_price": 0.0,
//                     "price": 45.0,
//                     "currency_code": "USD",
//                     "canonical_url": "https://company.com/product-name",
//                     "main_image_url": "https://company.com/product-name.jpg",
//                     "categories": [
//                         "60",
//                         "316",
//                         "325",
//                         "376"
//                     ]
//                 },
//                 ...
//             ]
//         }
//         ...
//     ]
// }

// define your template
const template = `
    <div id="product-recommendation-unit">
        {{#results}}
            <div id="product-recommendation">
                <p>{{name}}</p>
                <p>{{price}}</p>
            </div>
        {{/results}}
    </div>
`

// render the markup
const markup = client.renderUnit(template, data.units[0])

// markup:
// <div id="product-recommendation-unit">
//     <div id="product-recommendation">
//         <p>PRODUCT ONE</p>
//         <p>45</p>
//     </div>
//     <div id="product-recommendation">
//         <p>PRODUCT TWO</p>
//         <p>40</p>
//     </div>
//     <div id="product-recommendation">
//         <p>PRODUCT THREE</p>
//         <p>35</p>
//     </div>
//     <div id="product-recommendation">
//         <p>PRODUCT FOUR</p>
//         <p>33</p>
//     </div>
//     <div id="product-recommendation">
//         <p>PRODUCT FIVE</p>
//         <p>55</p>
//     </div>
// </div>

❓ Questions

If you have questions or need help, there are a few ways you can get in touch.

📧 Email us at [e-mail]
💬 Join us in the #p-rex channel
🐞 Open an issue in this repository