Skip to main content

Retrieving recommendation data for strategies

Recommendation data represents the raw data content of a recommendation. The data contains the details of the set of recommended items that together make up the recommendation. The logic and settings for generating the data are defined in a recommendation strategy.

To build the recommendation for display on a web page or in an application UI, you must first retrieve the corresponding recommendation data and then populate the recommendation web page element with that data. You retrieve the data based on the recommendation strategy responsible for generating the data.

You have two API options for retrieving recommendation data:

tip

If you use a modification to display the recommendation on a website:

  1. Retrieve the recommendation data and build the recommendation web page element in a template.

  2. Retrieve and process the data in the template's content prerenderer.

Context​

To return the correct recommendation data for a specific web page or visitor, the recommendation engine requires contextual information about the page or visitor. This information is the context.

The recommendation engine relies on two types of context:

  • Page context: Information about the page where the recommendation is displayed. The page context describes the relevant aspects of the page based on page type. For example, a product page requires a product ID as context, while a category page requires one or more category names as context. The API must provide the page context dynamically at runtime based on the specifics of the current page.

  • User context: Information about the visitor who sees the recommendation. The user context describes the visitor's latest and most prominent interactions on the site. The Frosmo Platform automatically creates and maintains a user context for each visitor. The API must retrieve the user context from the Frosmo back end at runtime.

The Frosmo Core fetch function can automatically handle the context on any website that has a basic feature setup. The function requires the necessary page context to be always available on a page. If your site has a basic feature setup, the Frosmo Platform programmatically sets the correct page context on page load, allowing the fetch function to work. If your site does not have a basic feature setup, or if you're retrieving recommendation data from an external application, where Frosmo Core is not available, you cannot use the fetch function.

You need to worry about the context only if you're using the Recommendations API. For more information, see the cookieId and context query parameters in the Recommendations API reference.

Using the fetch function​

To retrieve the recommendation data for a strategy using the Frosmo Core fetch function:

  1. Call the frosmo.easy.strategies.fetch() function with the strategy ID as a string parameter. Make sure that the page where you call the function matches the page type defined for the strategy.

  2. Extract the data from the response.

You can now use the data in a recommendation web page element.

For a practical example of retrieving and using recommendation data in a template, see Example: Recommending trending products in a category (strategy).

frosmo.easy.strategies.fetch()​

The frosmo.easy.strategies.fetch() function returns a Frosmo Core promise object (compatible with a Promise) that is either resolved with a success object containing the requested recommendation data or rejected with an error object.

The function requires that the necessary page context is available and that the context matches the page type defined for the recommendation strategy. If the correct page context is not available, the promise fails to resolve. For example, if the page type of the strategy is Product, the function expects to be called on a product page that has a product page context available.

The function uses the Recommendations API to retrieve recommendation data.

tip

You can check the context set for the current page by calling the frosmo.easy.strategies.getContext() function.

Request​

Retrieve recommendation data
frosmo.easy.strategies.fetch('strategy-id')
    .then(function (response) {
        console.log(response.data);
    })
    .catch(function (error) {
        console.error(error);
    });
Retrieve recommendation data with custom options
frosmo.easy.strategies.fetch('strategy-id', { debug: true, timeout: 10000, variants: true })
    .then(function (response) {
        console.log(response.data);
        console.log(response.debug);
    })
    .catch(function (error) {
        console.error(error);
    });

Parameters​

The following table describes the parameters you can define for the frosmo.easy.strategies.fetch() function.

Parameters for frosmo.easy.strategies.fetch()
ParameterDescriptionTypeRoleExample

strategy

ID of the recommendation strategy whose data to retrieve.

To find out the ID of a recommendation strategy, check the strategy settings.

String

Required

'most-viewed-on-site-weeks-100-affinity'

options

Options for configuring the fetch operation and response.

For more information about the options, see the following table.

Object

Optional

{ debug: true, timeout: 10000, variants: true }
Options object properties
PropertyDescriptionTypeRoleExample

debug

Define whether to return debugging information about the recommendation.

warning

Use the debugging information only for development and testing purposes. Do not use the information in production, since Frosmo does not guarantee that the information structure and content will remain the same.

The possible values are:

  • false: Do not return debugging information.

  • true: Return debugging information.

The default value is false.

For more information about what the debugging information contains, see the Recommendations API reference.

Boolean

Optional

debug: true

timeout

Time in milliseconds that the function waits for the Recommendations API to return the requested data. If the API does not return data in the specified time, the function rejects the Promise.

The default value is undefined, meaning the function waits forever.

Number

Optional

timeout: 10000

variants

Define whether to also return the data for product variants.

If a recommended product has one or more variants, the API returns the full product data for each variant in the variants array property of the recommended item object.

The possible values are:

  • false: Do not return product variant data.

  • true: Return product variant data.

The default value is false.

Boolean

Optional

variants: true

Response​

Success​

On a success, the frosmo.easy.strategies.fetch() function returns a JSON object containing the requested recommendation data.

The success object contains the following root properties:

  • data: Recommendation data as an array of objects, where each object contains the details of a single recommended item. The order of items depends on the sorting option defined for the strategy.

  • debug: Object containing the debugging information. This property is included only when the debug option is set to true in the request.

For more information about the contents of the success object, see the Recommendations API reference.

Error​

On an error, the frosmo.easy.strategies.fetch() function returns an object containing information about the error.

The error object contains the following properties:

  • errorThrown: Object containing information about the error.

  • textStatus: Value of the xhr.statusText property.

  • xhr: XMLHttpRequest object containing information about the HTTP request triggered by the function.