The Recommendations API provides an endpoint to present a visitor with one or more products or content pieces that may be of interest. For example, recommended products to upsell on a basket page.
The API endpoint includes rate-limiting to prevent abuse. Currently, we allow at most 30 requests from the same IP address within a 10 second window.
You can override as little or as much of the configuration as shown in Usage examples below.
type: String
default: 'pop'
Can be:
| Strategy Name | Placement |
|---|---|
| engagement | Product detail pages, product listing pages |
| recent | Product listing pages, Homepage |
| upsell | Basket pages, checkout pages |
| conversion | Product detail pages |
| trending | Homepage |
| popular | Homepage, search results pages |
| new | Homepage |
See our documentation page for more details
type: Number
default: 10
A Number specifying the amount of recommendations you wish to return. The API might respond with less recommendations than the specified limit. If no recommendations are available, the promise will be rejected. See the timeout section for how to handle errors.
type: String or Array
default: 'all'
You can seed (provide context to the recommendations API) with product IDs/SKUs (depending on your setup) and/or product categories. Product IDs/SKUs can be passed as String, however product categories must be passed as objects, e.g. { category: 'jeans' }. Place within an Array to combine - see Advanced usage example.
Please note that if you're passing in seed as an array, the maximum amount of IDs you should pass is 3. Any more than this, and only the last 3 items passed in will be considered; i.e.
// Product ID 123 will be no be considered in the API response
const idSeeds = ['123','456','789','ABC']
// Could process this within the code by doing something like the below:
const recommendations = require('@qubit/recommendations')(options, {
strategy: 'engagement',
limit: 20,
seed: idSeeds.slice(-3) // only take most recent three items in array
})type: Array
default: not included
Rules can be globally defined in our backend configuration (see Data tools -> Recommendations in the Qubit app), but sometimes you may want to vary them per request. Refer to http://jsonlogic.com/ for the possible rule combinations.
type: Number
default: 0
The default of 0 miliseconds means no timeout will occur. Should you wish to cancel the loading of recommendations after a set time period, pass the timeout key and attach a catch block after your then to perform an alternate operation.
const recommendations = require('@qubit/recommendations')(options)
recommendations.get().then((recs) => {
console.log(recs)
}).catch((e) => {
// perform alternate action
})type: String
default: options.meta.trackingId
Should you wish to request recommendations for a different property (perhaps you are building on staging, but would like to request production recommendations), this can be set here.
type: String
default: options.meta.visitorId
This package assumes usage within a Qubit experience. If using elsewhere you can specify how the Qubit Visitor ID should be found - typically via the _qubitTracker cookie.
type: String
default: 'https://recs.qubit.com/vc/recommend/2.0/'
The Qubit Recommendations API endpoint.
type: String
default: currency emitted in QP view event
Allows you to add a fallback currency for the recs endpoint locale; e.g. 'GBP'
type: String
default: language emitted in QP view event
Allows you to add a fallback language for the recs endpoint locale; e.g. 'en-gb'
type: String
default: undefined
Allows you to override the default locale for the recs endpoint; e.g. 'en-gb'
Recommendations can be retrieved by only passing through the Experience API (options). Recommendations will be returned based on the defaults listed in the Configuration section above.
const recommendations = require('@qubit/recommendations')(options)
recommendations.get().then((recs) => {
console.log(recs)
})If you'll be making only one type of recommendations request where the strategy and number of products you wish to use will be the same, you can define this upfront by providing your own configuration. You can override any key shown in the Configuration section above.
const productId = options.state.get('productId')
const recommendations = require('@qubit/recommendations')(options, {
strategy: 'engagement',
limit: 20,
seed: productId
})
recommendations.get().then((recs) => {
console.log(recs)
})Sometimes, we're required to implement a more custom recommendations call whereby we specify our configuration at the time of making the request. This approach is useful if you're required to make more than one request on a pageview.
Configuration passed to get overrides any configuration you pass when initialising the module (such as in the Standard example above). Any keys you leave out will fallback to the configuration passed when initialised or the defaults described in Configuration if no initial configuration was used.
const recommendations = require('@qubit/recommendations')(options)
recommendations.get({
strategy: 'engagement',
limit: 30,
seed: [{ category: 'jeans' }, 'ABC123', { category: 'blazers' }],
rules: [{
condition: {
'!==': [{
var: 'rec.custom_field'
}, {
var: 'seed.custom_field'
}]
},
factor: 0
}]
}).then((recs) => {
console.log(recs)
})To enable the metrics and reporting features within the Qubit app for a recommendations experience, implement the following events.
- When a recommendation is shown/rendered onto the page:
recommendations.shown({
id: 'ABC123',
weight: '0.9',
strategy: 'popular'
})- When a recommendation is clicked:
recommendations.clicked({
id: 'ABC123',
weight: '0.9',
strategy: 'popular',
position: 1
})id, weight and strategy will be returned for every recommendation, so if you're looping through the API response to render recommendations, this data will be immediately available to make the shown call. Here's an example of how you might choose to emit shown and clicked events:
const recommendations = require('@qubit/recommendations')(options)
recommendations.get().then((recs) => {
const $recs = recs.map((product, i) => {
const { details } = product
recommendations.shown(product)
return $(`
<div class="t001-rec">
<a href="${details.url}">
<img class="t001-img" src="${details.image_url}" />
<div class="t001-name">${details.name}</div>
<div class="t001-price">${details.unit_sale_price}</div>
</a>
</div>
`).click(() => {
recommendations.clicked(_.assign({ position: i + 1 }, product))
})
})
$(`.product-details`).append($recs)
}).catch(err => {
console.log(err)
})If you're including this package in a Qubit experience, the get call should take place in triggers so you can verify a response prior to activating.