Deliver recommendations (Qubit)

This is for:

Developer

In 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

<tracking_id>

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 to popular.

  • 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.

Warning

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 strategy=popular, we will generate a list of product IDs for popular products from all locales. The locale passed in your request is then used to return specific product information (name, description, price, etc).

Sample response

The Recommendations API will always generate a response with HTTP status 200 for any responses it has control over.

Tip
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

all

Showcase trending products

popular

Shows products with the higher number of views within the last 30 days

category ID / all

Popular products

best_sellers_revenue_7_days

Shows products that generated most revenue within the last 7 days

category ID / all

Popular products

best_sellers_revenue_28_days

Shows products that generated most revenue within the last 28 days

category ID / all

Popular products

best_sellers_revenue_90_days

Shows products that generated most revenue within the last 90 days

category ID / all

Popular products

best_sellers_volume_7_days

Shows products with the higher number of sold SKUs within the last 7 days

category ID / all

Popular products

best_sellers_volume_28_days

Shows products with the higher number of sold SKUs within the last 28 days

category ID / all

Popular products

best_sellers_volume_90_days

Shows products with the higher number of sold SKUs within the last 90 days

category ID / all

Popular products

best_sellers_blended_7_days

Shows products with the higher combined value of

best_sellers_revenue_7_days

and

best_sellers_volume_7_days

category ID / all

Popular products

best_sellers_blended_28_days

Shows products with the higher combined value of

best_sellers_revenue_28_days

and

best_sellers_volume_28_days

category ID / all

Popular products

best_sellers_blended_90_days

Shows products with the higher combined value of

best_sellers_revenue_90_days

and

best_sellers_volume_90_days

category ID / all

Popular products

new_arrivals_7_days

Shows products recently added to your product catalog within the last 7 days, ordered by popularity (views)

all

Promote new products

new_arrivals_28_days

Shows products recently added to your product catalog within the last 28 days, ordered by popularity (views)

all

Promote new products

new_arrivals_90_days

Shows products recently added to your product catalog within the last 90 days, ordered by popularity (views)

all

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.

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

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 of best_sellers_revenue_<N>_days and best_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.

Warning

Although the API doesn’t enforce limits, there’s no practical reason to use more than two to three fallbacks.

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"]}'

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"]}'

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"}]}'
Warning

In "type": "c", the value "c" is case sensitive and must be lower-case. In "id": "category", the category name must exactly match the value in the QP field product.categories.

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.

Tip
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.

Warning

Except for the strategy popular, the recommendation seed will always be a product ID (or SKU, if specified during onboarding).

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"]}'
Tip
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"}]

rules

  • type: Array

  • default: none

See Per-request filters for details.

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.