A recommendation strategy provides the recommendation data that forms the core content of a recommendation: the details of the set of recommended items. To build the recommendation for display on a page or in an application UI, you need to first retrieve the recommendation data from the Frosmo back end and then populate the recommendation element with the data.
Before you can retrieve the recommendation data, the strategy must be created, and the Frosmo Platform must generate the data.
You have two API options for retrieving recommendation data:
- Frosmo Core's fetch function for recommendations. Use this option if you're retrieving the data on a website that has a page context setup in place. For more information, see Context and Frosmo Core fetch function.
- Recommendations API. Use this option if you're retrieving the data in a native mobile application or a server-side application, or on a website without a page context setup. You must provide the page context as part of the API request. For more information, see Context and the Recommendations API guide.
If you're using a modification to display the recommendation on a website, you retrieve the recommendation data and create the recommendation element in a template. You retrieve and process the data in the template prerenderer.
Context
To generate recommendation data, some strategies rely on contextual information about the current web page or visitor, or both:
- Page context: Information about the page where the recommendation is displayed. The information describes the relevant aspects of the page based on the page type, such as item ID for a product page or category names for a category page. The API must provide the page context dynamically at runtime based on the specifics of the target page.
- User context: Information about the visitor who sees the recommendation. The information describes the visitor's latest and most prominent interactions on a 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.
Frosmo Core's fetch function for recommendations automatically handles the context on a website. However, the function expects that Frosmo Core programmatically sets the page context on page load. Frosmo developers create the page context setup as part of a basic feature setup. If your site does not have a page context setup in place, 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 guide.
What context information a strategy requires depends on its algorithms and filters:
- The following algorithms require a page context:
- Bought together with current category
- Bought together with current item
- Bought together with items in the cart
- Viewed together with current category
- Viewed together with current item
- Viewed together with recently searched categories
- Viewed together with recently searched items
- The following algorithms require a user context:
- Bought together with categories recently bought by the visitor
- Bought together with items recently viewed by the visitor
- Most viewed by the visitor
- Recently viewed by the visitor
- Viewed together with categories recently viewed by the visitor
- Viewed together with items recently viewed by the visitor
- The Only return items filter options require a page context.
For example, if you have a category page strategy with the algorithms Bought together with current category and Most viewed by the visitor, the strategy requires both a page context (specifically, a category page context) and a user context to generate its recommendation data.
You only need to define the page context manually. The Recommendations API gets the correct user context automatically when you define the cookieId query parameter.
Frosmo Core fetch function
To retrieve the recommendation data for a strategy using Frosmo Core:
- 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. For more information about the function, see fetch() request. - Extract the data from the response object. For more information about the object, see fetch() response.
You can now use the data in your recommendation content.
For a practical example of retrieving and using recommendation data in a template, see Example: Recommending trending products in a category (strategy).
fetch() request
The frosmo.easy.strategies.fetch() function returns a Frosmo Core Promise (compatible with a Promise) that is either resolved with a response object containing the recommendation data or rejected with an error object.
frosmo.easy.strategies.fetch('strategy-id')
.then(function (response) {
console.log(response.data);
})
.catch(function (error) {
console.error(error);
});
The frosmo.easy.strategies.fetch() function expects that the page context for the strategy has been set and that the context matches the page type defined for the strategy. If the correct page context is not available, the function fails. For example, if the page type of the strategy is Product, the function expects that it's called on a product page that has a product page context set.
You can check the context set for the current page by calling the frosmo.easy.strategies.getContext() function.
Parameters
The following table describes the parameters you can define for the frosmo.easy.strategies.fetch() function.
Table: Parameters for frosmo.easy.strategies.fetch()
| Parameter | Description | Type | Role | Example |
|---|---|---|---|---|
strategy | ID of the recommendation strategy whose recommendation data to retrieve. To find out the ID of a recommendation strategy, check the strategy settings. | String | Required | frosmo.easy.strategies.fetch('strategy-id')
|
options | Options for configuring the fetch and response. For more information, see the following table. | Object | Optional | frosmo.easy.strategies.fetch('strategy-id', {shuffle: true})
|
Table: Options object properties
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
debug | Define whether to return debugging information about the recommendation data. The possible values are:
The default value is | Boolean | Optional | frosmo.easy.strategies.fetch('strategy-id', {debug: true})
|
shuffle | Define whether to randomly shuffle the order of items in the recommendation data. By default, the items are in descending order of rank, with the most recommended item (as defined by the strategy) ranked highest. The possible values are:
The default value is | Boolean | Optional | frosmo.easy.strategies.fetch('strategy-id', {shuffle: true})
|
timeout | Time in milliseconds that the fetch call waits for the Recommendations API to return the requested data. If the API does not return data in the specified time, the fetch call rejects the Promise. The default value is undefined, meaning the fetch call waits forever. | Number | Optional | frosmo.easy.strategies.fetch('strategy-id', {timeout: 10000})
|
fetch() response
The response is a JSON object.
The response 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. Unless shuffled, the items are in descending order of rank, with the most recommended item (as defined by the algorithms) ranked highest.debug: Object containing the debugging information. This property is included only when thedebugoption is set totruein the fetch call.
The following examples show the same response without and with debugging information.
