Deliver recommendations (Qubit)
Deliver recommendations (Qubit)
This is for:
DeveloperIn this article, we’ll explore how to use our Recommendations API to present your customers with products or content that match one of Qubit’s recommendation strategies.
Making a request
Called via a POST request:
POST https://recs.qubit.com/vc/recommend/2.1/<tracking_id>?strategy=<strategy_name>&n=<no_of_recs_to_return>&locale=<language-currency>
Prerequisites
Unique values
Before using the Recommendations API, you’ll require the following unique values:
Name | Description |
---|---|
|
Qubit tracking ID for the property the request is made from. This will be provided by your CSM |
Understanding the endpoint
Sample request
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/demo_uk_prod?strategy=popular&n=10&locale=en-gb-GBP&experienceId=20351' \
-H 'content-type: application/json' \
-d '{"h": ["all"]}'
Where:
-
demo_uk_prod
is the Qubit tracking ID for the property the request is made from. Your CSM at Coveo will provide this. -
strategy
is one of Qubit’s recommendations strategies. See Strategies for more information. If not specified, defaults topopular
. -
n
is the number of products to recommend. If not specified, defaults to 10. Maximum is 50. -
locale
see Locales. If not specified, defaults to the most common language/currency combination seen in your product catalog. -
experienceId
is the ID of a recommendations experience containing promotion or blocklisting rules you want to pass into your request. -
h
is an optional parameter to define the history or seed to generate recommendations for. Can accept an array of product IDs/SKUs. See The recommendation seed for details and examples.
Recommendations are typically generated using product ID. If you wish to use SKU instead, you’ll need to inform Coveo during the onboarding process. |
Note
Recommendations are generated using the products from across your entire product catalog and all provided locales.
This means, for example, if you’re using the popular strategy |
Sample response
The Recommendations API will always generate a response with HTTP status 200 for any responses it has control over.
Leading-practice
Always check the status field to ensure that the response has been successful. |
The response body will be a JSON object containing the following fields.
Name | Description | Required |
---|---|---|
status |
HTTP status code of the response |
Yes |
result |
In case of errors, this will be a string. In other cases it will be another JSON object containing the data requested |
Yes |
segment |
Name of the server-side segment calculated for this visitor |
No |
annotations.segment |
JSON object containing additional data that pertains to the segment |
No |
annotations.strategy |
JSON object containing additional data that pertains to the strategy |
No |
Sample successful response
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
items: [
{
id: '5637911031',
weight: 0.07154133712308453,
details: {
category: 'Craft Essentials',
unit_sale_price: 1.5,
subcategory: 'Craft Paint',
url: 'http://www.crafters.co.uk/deco-art-crafters-acrylic-white-2oz/563791-1031',
sku_code: '5637911031',
unit_price: 1.5,
name: 'Deco art Crafters Acrylic White 2oz',
currency: 'GBP',
image_url: 'http://www.crafters.co.uk/supplyimages/563791_1031_1_170.jpg',
stock: 3,
id: '563791',
description: 'Deco art Crafters Acrylic White 2oz'
}
}
]
}
Sample unsuccessful responses
Invalid strategy or tracking ID
If either the strategy or tracking ID is invalid, we will return a response with status code 200, but with 0 results:
HTTP/1.1 200 OK
Content-Type: application/json;charset=utf-8
{
items: []
}
Missing tracking ID
If you make an error passing in the tracking ID for your property, we will return a response with status code 404:
HTTP/1.1 404 OK
Content-Type: application/json;charset=utf-8
{
"status": 404,
"message": "Requested URL /vc/recommend/2.1/ not found"
}
A summary of Qubit’s strategies
Refer to the following tables for details of each of Qubit’s strategies. We’ve also included the name of each strategy as it displays in the Experience Hub:
Strategy Name | Description | Seed | Name in Hub |
---|---|---|---|
engagement |
Draws visitors further into your product inventory by showing similar and related products |
productId |
Discover similar products |
upsell |
Encourages users to buy more by showing products that are complementary to one another |
productId |
Upsell products |
conversion |
Builds reassurance into the later stages of the conversion funnel, and is therefore often used further down the user journey to validate purchase decisions |
product ID |
Bought after viewing |
trending |
Highlights the latest product trends from your brand. It suits for repeat users on their return to your site |
|
Showcase trending products |
popular |
Shows products with the higher number of views within the last 30 days |
category ID / |
Popular products |
best_sellers_revenue_7_days |
Shows products that generated most revenue within the last 7 days |
category ID / |
Popular products |
best_sellers_revenue_28_days |
Shows products that generated most revenue within the last 28 days |
category ID / |
Popular products |
best_sellers_revenue_90_days |
Shows products that generated most revenue within the last 90 days |
category ID / |
Popular products |
best_sellers_volume_7_days |
Shows products with the higher number of sold SKUs within the last 7 days |
category ID / |
Popular products |
best_sellers_volume_28_days |
Shows products with the higher number of sold SKUs within the last 28 days |
category ID / |
Popular products |
best_sellers_volume_90_days |
Shows products with the higher number of sold SKUs within the last 90 days |
category ID / |
Popular products |
best_sellers_blended_7_days |
Shows products with the higher combined value of
and
|
category ID / |
Popular products |
best_sellers_blended_28_days |
Shows products with the higher combined value of
and
|
category ID / |
Popular products |
best_sellers_blended_90_days |
Shows products with the higher combined value of
and
|
category ID / |
Popular products |
new_arrivals_7_days |
Shows products recently added to your product catalog within the last 7 days, ordered by popularity (views) |
|
Promote new products |
new_arrivals_28_days |
Shows products recently added to your product catalog within the last 28 days, ordered by popularity (views) |
|
Promote new products |
new_arrivals_90_days |
Shows products recently added to your product catalog within the last 90 days, ordered by popularity (views) |
|
Promote new products |
pllr_bought_next |
Focuses on the first and second purchases in the purchase cycle to recommend products that other users bought next after purchasing the seeded product(s), and will be of particular interest to brands looking to drive retention through more relevant recommendations |
product ID |
Bought next |
You can read more about each of Qubit’s strategies in Qubit’s plug and play strategies.
Recommended use of Qubit’s strategies
Refer to the following table for guidance on the best place to use each strategy:
Strategy Name | Placement |
---|---|
engagement |
Product detail page |
upsell |
Basket page, checkout page |
conversion |
Product detail page |
trending |
Homepage |
popular best_sellers_revenue_7_days best_sellers_revenue_28_days best_sellers_revenue_90_days best_sellers_volume_7_days best_sellers_volume_28_days best_sellers_volume_90_days best_sellers_blended_7_days best_sellers_blended_28_days best_sellers_blended_90_days |
Homepage, search results page |
new_arrivals_7_days new_arrivals_28_days new_arrivals_90_days |
Homepage |
pllr_bought_next |
Checkout page, order confirmation page |
Composite strategies
Qubit’s engagement, upsell, conversion, and trending strategies are referred to as composite strategies because they’re composed of a principal strategy and one or more additional strategies that function as fallbacks.
The fallback logic ensures that if the principal strategy for the given seed doesn’t return the requested number of recommendations, the request is fulfilled by falling back to the next strategy.
For example, if fifteen results are requested, and the first strategy returns ten results, we would fetch the remaining five from the first fallback strategy, and so on.
Refer to the following tables for details of the fallbacks for our composite strategies:
Engagement
-
cf_viewed
: Uses collaborative filtering based on views of product items. -
pllr
: Uses log-likelihood ratio to surface product connections based on views.
Default strategy | Fallback 1 | Fallback 2 |
---|---|---|
cf_viewed Uses collaborative filtering to recommend products based on product views |
pllr Most viewed together (log likelihood ratio) with the seeded product(s) over the last 30 days |
trending_popular_views_1 Most viewed/bought across a site over the last 30 days |
Upsell
-
cf_bought
: Uses collaborative filtering based on purchases of product items. -
pllr_bought
: Uses log-likelihood ratio to surface product connections based on purchases.
Default strategy | Fallback 1 | Fallback 2 |
---|---|---|
cf_bought Uses collaborative filtering to recommend products based on product purchases |
pllr_bought Most bought together with the seeded product(s) over the last 30 days |
trending_popular_views_1 Most viewed/bought across a site over the last 30 days |
Conversion
-
pllr_viewed_bought
: Uses log-likelihood ratio to surface product connections based on a combination of views and purchases.
Default strategy | Fallback 1 |
---|---|
pllr_viewed_bought Products that were eventually bought when the seeded product(s) were viewed |
trending_popular_views_1 Most viewed/bought products across a site over the last 30 days |
Trending
Default strategy | Fallback 1 |
---|---|
trending_ols_views_1 Trending products (see below for details) |
trending_ewma_views_1 Products that are popular by views with a greater emphasis on more recent views |
For a discussion of the differences between collaborative filtering and log-likelihood ratio, refer to What’s the difference between collaborative filtering and log-likelihood ratio?
Non-composite strategies
Unlike composite strategies, by default, non-composite strategies don’t operate with fallbacks:
-
popular
: Recommends most viewed products across a site over the last 30 days. -
best_sellers_revenue_7_days
,best_sellers_revenue_28_days
,best_sellers_revenue_90_days
: Recommends products that generated most revenue during the last N days. -
best_sellers_volume_7_days
,best_sellers_volume_28_days
,best_sellers_volume_90_days
: Recommends products that sold most SKUs during the last N days. -
best_sellers_blended_7_days
,best_sellers_blended_28_days
,best_sellers_blended_90_days
: Recommends products with the higher combined value ofbest_sellers_revenue_<N>_days
andbest_sellers_volume_<N>_days
-
new_arrivals_7_days
,new_arrivals_28_days
,new_arrivals_90_days
: Recommends new products, that is, products shown for the first time during the last N days. -
pllr_bought_next
: Recommends products purchased after purchasing the seeded product.
The last N days
meaning-
the last 7 days, compared to the previous 8..100 days
-
the last 28 days, compared to the previous 29..100 days
-
the last 90 days, compared to the previous 91..200 days
You can add fallbacks of your own to ensure that recommendations are delivered if the chosen strategy doesn’t deliver the required number of products. Let’s look at an example:
https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=pllr,pllr_bought&seed=4000135NI_1100&n=100&locale=en-GBP
Where:
-
strategy
is a comma-separated list of strategies, with the principal strategy in position one and any fallbacks you want to use after that, for example,pllr,pllr_bought
. -
seed
is a product ID, for example,4000135NI_1100
. -
n
is the number of recommendations to return.
Although the API doesn’t enforce limits, there’s no practical reason to use more than two to three fallbacks. |
A focus on trending products
Qubit’s trending strategy considers views over time to determine which products are genuinely trending. For example, if a product is viewed 100 times every day, its popularity isn’t changing over time, and it’s therefore not trending. If a product was viewed 5 times day 1, 20 times day 2, and 50 times day 3, its popularity is changing over time. We consider this product to be trending.
Other strategies
We no longer support the following strategies and recommend that they’re no longer used:
Name | Explanation | Use |
---|---|---|
pp1 |
Users who viewed this product also viewed these products |
Composite strategy to increase engagement by recommending products viewed together and recently viewed together with the recommendation seed |
pp3 |
Users who bought this product also bought these products |
Composite strategy to encourage cross-sell by recommending products bought together and recently bought together with the recommendation seed |
pop |
Products most frequently viewed or bought |
Inspire new visitors by presenting popular products viewed over the last 30 days |
Example requests
In this section, we will take a look at how you can use strategies to deliver recommendations.
Strategy engagement
Recommend products viewed together with a specific product, returning 5 product recommendations:
-
strategy=engagement
-
W000277351
-
n=5
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=engagement&n=5&locale=fr-EUR' \
-H 'content-type: application/json' \
-d '{"h": ["W000277351"]}'
Strategy upsell
Recommend products bought together with a specific product, returning 10 product recommendations:
-
strategy=upsell
-
W000277351
-
n=10
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=upsell&n=10&locale=en-us-USD' \
-H 'content-type: application/json' \
-d '{"h": ["W000277351"]}'
Strategy popular
Recommend the most popular products, returning 5 product recommendations:
-
strategy=popular
-
all
-
n=5
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=popular&n=5&locale=en-GBP' \
-H 'content-type: application/json' \
-d '{"h": ["all"]}'
Strategy popular with category ID seed
Recommend the most popular products within the provided seed category, returning 5 product recommendations.
Example 1:
-
strategy=popular
-
{"type": "c", "id": "handbags"}
-
n=5
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=popular&n=5&locale=en-GBP' \
-H 'content-type: application/json' \
-d '{"h": [{"type": "c", "id": "handbags"}]}'
Example 2:
-
strategy=popular
-
{"type": "c", "id": "Home > Shoes"}
-
n=10
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=popular&n=10&locale=en-GBP' \
-H 'content-type: application/json' \
-d '{"h": [{"type": "c", "id": "Home > Shoes"}]}'
In |
Strategy pllr_bought_next
Recommend products bought next after purchasing the seeded product, returning 3 product recommendations:
-
strategy=pllr_bought_next
-
W000277351
-
n=3
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=pllr_bought_next&n=3&locale=en-GBP' \
-H 'content-type: application/json' \
-d '{"h": ["W000277351"]}'
The recommendation seed
The seed parameter defines the products and product categories to generate recommendations for. If there is sufficient data about the provided seed, for example, products viewed or bought together with a product, we will return recommendations.
By adding or omitting a seed, you can use each strategy in the manner best suited to where you are adding the recommendations carousel.
Leading-practice
Although there are places where a single product ID should be used as the seed, for example, on product detail pages, where possible, we recommend using an array of product IDs as the seed to guarantee a richer, aggregated set of recommendations. This is especially true for a home page or a search page that hasn’t returned results from a product search. |
Except for the strategy |
Example seed
{
"h": ["W000277351"]
}
Where:
-
h
is an optional parameter to define the history or seed to generate recommendations for.
A seed is considered contextual if the value is a product ID, an array of IDs, or a category ID (only for popular
):
{
"h": ["W000277351","W000277352","W000277353"]
}
And generic if the value is all
:
{
"h": ["all"]
}
Contextual seed
A contextual seed is obtained by passing specific product IDs or, and only for popular
, a category ID, to generate recommendations.
On product detail pages, you might generate recommendation for the product being viewed by passing its product ID:
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_property?strategy=engagement&n=15&locale=en-us-USD' \
-H 'content-type: application/json' \
-d '{"h": ["W000277351"]}'
On basket pages, you might generate recommendations for all of the products present in the shopper’s basket by passing an array of product IDs:
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_property?strategy=conversion&n=5&locale=en-us-USD' \
-H 'content-type: application/json' \
-d '{"h": ["W000277351","W000277352","W000277353"]}'
Leading-practice
By sending multiple product IDs, the endpoint will aggregate the results and return the top sorted recommendations. |
Generic seed
On the other hand, a generic seed is obtained by seeding the recommendation with all
.
For example, on a home page, it may make more sense to recommend trending products from across your product inventory:
curl -X POST \
'https://recs.qubit.com/vc/recommend/2.1/example_property?strategy=trending&n=10&locale=fr-EUR' \
-H 'content-type: application/json' \
-d '{"h": ["all"]}'
Per-request filters
You can refine recommendations through the application of rules. These can be defined globally for your property or for one or more experiences on the Recommendations page.
For certain use cases, for example, where you wish to heavily promote a product by applying a higher weight than can be defined when defining rules in the platform, it might be appropriate to use rules on a per-request basis.
We refer to these rules as per-request filters
because they’re restricted to the API request containing the filter and are then discarded.
Some important considerations
When calling the Recommendations API, per-request filters are added to any global rules defined in the platform and any experience-specific rules (if passed in your request). Observe the following points closely:
-
Per-request filters are restricted to the request containing them
-
Filters are added to global rules and any experience-specific rules (but only if you pass the experienceId in your request) but don’t override them
-
The application of filters in requests containing multiple seeds is impractical. For this reason, filters are only applied to the first seed within the request
For information about adding global rules for blocklisting and promoting products in Coveo Experimentation Hub, see Available Rules.
Let’s look at a simple per-request filter that includes blocklist and promotion elements. We’ve not passed an experienceId in the request, so the rules will only be added to globally-defined rules:
curl -X POST \
'http://localhost:6662/vc/recommend/2.1/example_property?strategy=popular&n=10&locale=en-us-USD' \
-H 'Content-Type: application/json' \
-d '{
"h":["all"],
"rules":[
{
"name":"Blocklist low price",
"condition":{ "<=":[ 0, { "var":"rec.unit_price" }, 30 ] },
"factor":0
},
{
"name":"Promote Shirts-Tops",
"condition":{ "in":[ "Shirts-Tops", { "var":"rec.categories" } ] },
"factor":2
}
]
}'
Where:
-
name
is the filter name, used for information purposes only. -
condition
is the logic used to filter products–written in JsonLogic. -
factor
determines whether the filtered products are blocklisted"factor":0
, or promoted (for example,"factor":1
,"factor":2
, etc) if condition evaluates as true.
Looking at the previous example, the first rule blocklists products with a unit price less than or equal to 30. The second rule promotes products in the Shirts-Tops product category by a factor of 200. It’s worth remembering that a promotion rule added in the platform will apply a factor of 2.
To assist you in building filters, the JsonLogic site includes a playground for testing condition logic. To use the site, copy the entire condition value into Rule field:
{
"seed": <seed product details>,
"rec": <recommended product details>
}
For a list of supported operations, see Operations.
A quick look at weights and factors
Take note of the following points:
-
Weight determines the position in the recommendations carousel. The higher the weight, the higher the position
-
Where applied, factors impact the weight applied to a product from a particular strategy
weight x factor
:-
factor=0 (blocklisting) -> last position in carousel and filtered from it
-
factor=1 -> no effect
-
== factor=>1 (promotion) -> higher position in the carousel
-
Using regex
You can also use regex to define filters using the match operator.
If you want to use multiple regexes, then use match_some
instead of match
:
Example - match:
{
"name": "Blocklist product IDs starting with RX_",
"factor": 0,
"condition": {
"match": [{"var": "rec.id"}, "^RX_.*$"]
}
}
Example - match_some:
{
"name": "Blocklist product IDs containing test or starting with RX_",
"factor": 0,
"condition": {
"match_some": [{"var": "rec.id"},["^RX_.*$", ".*test.*"]]
}
}
Examples
Refer to the following examples that show how you can use per-filters.
Promotion
Promote products by a factor of 2 belonging to a specific brand in the product categories shoes and pants:
{
"name": "Brand promotion",
"condition": { "and": [
{"or": [
{ "in": [ "Shoes": { "var": "rec.categories" }]},
{"in": ["pants": { "var": "rec.categories" }]}
]},
{ "==": [ { "var": "rec.brand" }, "adidas" ] }
]},
"factor": 2
}
Same field filter
Only recommend products that are the same size as the returned seed product:
{
"name": "same size recommendations",
"condition": { "!=": [ { "var": "seed.size" }, { "var": "rec.size" } ] },
"factor": 0
}
Different field filter
Don’t recommend products that are the same size as the returned seed product:
{
"name": "different size recommendations",
"condition": { "==": [ { "var": "seed.size" }, { "var": "rec.size" } ] },
"factor": 0
}
Low stock
Don’t recommend products with less than ten items in stock:
{
"name": "low stock products filter ",
"condition": { "<": [ { "var": "rec.stock" }, 10 ] },
"factor": 0
}
Price range filter
Don’t recommend products with a price between 11 and 99 USD:
{
"name": "filter products with 10 < price < 100 USD",
"condition": {"and": [
{ "<": [ 10, { "var": "rec.price" }, 100 ] },
{ "==": [ { "var": "rec.currency" }, "USD" ] }
]},
"factor": 0
}
High price filter
Don’t recommend products that have a price higher than the returned product seed:
{
"name": "higher price recommendations",
"condition": { ">": [ { "var": "rec.price" }, { "var": "seed.price" } ] },
"factor": 0
}
Cross sale (blocklisting style)
Only recommend products from the category blow dryers
when viewing combs
:
{
"name": "only sell blow dryer with a comb",
"condition": { "and": [
{ "in": [ "combs", { "var": "rec.categories" }]}
{ "!": {"in": [ "blow dryer", { "var": "seed.categories" }]}}
]},
"factor": 0
}
Cross sale (promotion style)
Recommend blow dryers
when viewing combs by a factor of 2:
{
"name": "promote blow dryers when viewing combs",
"condition": {"and": [
{"in": ["combs", { "var": "rec.categories" }]}
{"in": ["blow dryer", { "var": "seed.categories"}]}
]},
"factor": 2
}
Real-life example
In this real-life example, we demonstrate the possibilities when using per-request filters to customize the recommendation seed fully:
{
"rules": [
{
"name": "low stock config",
"condition": { "<": [ { "var": "rec.stock" }, 10 ] },
"factor": 0
},
{
"name": "low price config",
"condition": { "and": [
{ "<": [ { "var": "rec.price" }, 30 ] },
{ "==": [ { "var": "rec.currency" }, "GBP" ] }
]},
"factor": 0
},
{
"name": "blocklist config",
"condition": { "or": [
{ "in": [ "Adult", { "var": "rec.categories" }] },
{"match_some": [{"var":"rec.description"},["^Sample*", "*Tester.$"]]},
{ "==": [ { "var": "rec.is_clearance" }, true ] },
{ "in": [
{ "var": "rec.sku_id" },
[ "23757604", "23757639", ... ]
]}
]},
"factor": 0
},
{
"name": "promote products",
"condition": { "==": [ { "var": "rec.id" }, "24004952" ] },
"factor": 2
}
]
}
Debugging rules
You can output the rules object in the response by appending a query parameter debug=True
to the API request.
You can view this object to determine which rules, if any, are being used to filter a recommendation:
https://recs.qubit.com/vc/recommend/2.1/example_trackingId?strategy=engagement&n=5&debug=True
Calling the API in an Experimentation Hub experience
Basic
You can retrieve recommendations by passing through the Experience API (options)
.
Recommendations will be returned based on the defaults listed in the Configuration section below.
const recommendations = require('@qubit/recommendations')(options)
recommendations.get().then((recs) => {
console.log(recs)
})
Standard
If you’re making only one type of recommendation 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 Configuration section below.
const productId = options.state.get('productId')
const recommendations = require('@qubit/recommendations')(options, {
strategy: 'pp1',
limit: 20,
seed: productId
})
recommendations.get().then((recs) => {
console.log(recs)
})
Advanced
Sometimes, we’re required to implement more a customized recommendations call. To do this, we specify our configuration at the time of making the request. This approach is useful if you need to make more than one request on a pageview.
Configuration passed to get overrides any configuration you pass when initializing the module, such as in the Standard example above.
Any keys you leave out will fallback to the configuration passed when initialized or the defaults described in Configuration if no initial configuration was used.
const recommendations = require('@qubit/recommendations')(options)
recommendations.get({
strategy: 'popular',
limit: 30,
seed: [{ category: 'jeans' },{ category: 'blazers' }],
rules: [{
condition: {
'!==': [{
var: 'rec.custom_field'
}, {
var: 'seed.custom_field'
}]
},
factor: 0
}]
}).then((recs) => {
console.log(recs)
})
Example
We will return ID, weight, and strategy for every recommendation, so if you’re looping through the API response to render recommendations, this data will be immediately available to make the 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)
})
Note
If you include this package in the Coveo Experimentation Hub experience, the get call should take place in triggers.js, so you can verify a response before activating. |
Configuration
You can override as little or as much of the configuration shown in the examples above.
strategy
-
type: String
-
default:
popular
-
options:
engagement
upsell
conversion
trending
popular
best_sellers_revenue_7_days
best_sellers_revenue_28_days
best_sellers_revenue_90_days
best_sellers_volume_7_days
best_sellers_volume_28_days
best_sellers_volume_90_days
best_sellers_blended_7_days
best_sellers_blended_28_days
best_sellers_blended_90_days
new_arrivals_7_days
new_arrivals_28_days
new_arrivals_90_days
pllr_bought_next
locale
-
type: String
-
default: The most common language/currency combination seen in your product catalog.
limit
-
type: Number
-
default:
10
A number specifying the number of recommendations you wish to return. The API might respond with fewer recommendations than the specified limit, in which case, depending on the strategy used, we will fall back to a secondary strategy. See Composite strategies for more information.
If no recommendations are generated from the seed, the promise will be rejected. See timeout for details of how to handle errors.
seed
-
type: String or array
-
default:
all
As mentioned above, you can seed recommendations with product IDs/SKUs.
Product IDs/SKUs can be passed as a string. Place within an array to combine:
[{"W000277351","W000277352","W000277353"}]
timeout
-
type: Number
-
default:
0
The default of 0 milliseconds means no timeout will occur. Should you wish to cancel the loading of recommendations after a set period, pass the timeout key and attach a catch block to perform an alternate operation:
const recommendations = require('@qubit/recommendations')(options, {
timeout: 3000, // 3 sec
})
recommendations.get().then((recs) => {
console.log(recs)
}).catch((e) => {
// perform alternate action
})
trackingId
-
type: String
-
default:
options.meta.trackingId
Should you wish to request recommendations for a different property, perhaps to build on a staging environment, but would like to request production recommendations, this can be set here.
visitorId
-
type: String
-
default:
options.meta.visitorId
This package assumes usage within the Experimentation Hub experience.
If using elsewhere, you can specify how the Experimentation Hub Visitor ID should be found, typically via the _qubitTracker
cookie.
url
-
type: String
-
default:
https://recs.qubit.com/vc/recommend/2.1/
The Recommendations API endpoint.
Required events
Metrics and reporting in Coveo Experimentation Hub
To enable the metrics and reporting features within the Experimentation Hub 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: 'pop'
})
-
When a recommendation is clicked:
recommendations.clicked({
id: 'ABC123',
weight: '0.9',
strategy: 'pop',
position: 1
})
Coveo Experience Hub
Refer to Product recommendations for details of which events need to be emitted to deliver product recommendations.
We recommend also referring to our Events page to determine which events to emit.