Retrieving recommendation data for strategies
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.
| Parameter | Description | Type | Role | Example |
|---|---|---|---|---|
| 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 | |
| Options for configuring the fetch and response. For more information, see the following table. | Object | Optional | |
| Property | Description | Type | Role | Example |
|---|---|---|---|---|
| Define whether to return debugging information about the recommendation data. The possible values are:
The default value is | Boolean | Optional | |
| warning This property is deprecated. If you want to shuffle the order of items, use the corresponding sorting setting in the strategy. Define whether to randomly shuffle the order of items in the recommendation data. The possible values are:
The default value is | Boolean | Optional | |
| 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 | |
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. The order of items depends on the sorting setting defined in the strategy. -
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.
{
"data": [
{
"id": "3",
"type": "Power Tools/Drills",
"name": "Drill Screwdriver Brandix ALX7054 200 Watts",
"created_at": "2020-09-10T13:50:41+02:00",
"updated_at": "2021-06-09T13:22:09+02:00",
"attributes": {
"availability": "In stock",
"badges": [
],
"brand": "Wakita",
"category": "Power Tools/Drills",
"deliverTime": 1,
"discountPrice": "0",
"displayDiscountPrice": null,
"displayPrice": "€850.00",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-3.jpg",
"manufacturer": "Wakita",
"price": 850,
"rating": 4,
"reviews": 8,
"stock": 9,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/3"
}
},
{
"id": "4",
"type": "Power Tools/Drills",
"name": "Drill Series 3 Brandix KSR4590PQS 1500 Watts",
"created_at": "2020-09-10T14:38:37+02:00",
"updated_at": "2021-06-09T13:22:10+02:00",
"attributes": {
"availability": "In stock",
"badges": [
],
"brand": "Wakita",
"category": "Power Tools/Drills",
"deliverTime": 3,
"discountPrice": "0",
"displayDiscountPrice": null,
"displayPrice": "€949.00",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
"manufacturer": "Wakita",
"price": 949,
"rating": 3,
"reviews": 15,
"stock": 4,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/4"
}
},
{
"id": "16",
"type": "Power Tools/Drills",
"name": "Brandix Screwdriver SCREW1500ACC",
"created_at": "2020-09-15T13:59:08+02:00",
"updated_at": "2021-06-09T14:06:33+02:00",
"attributes": {
"availability": "In stock",
"badges": [
],
"brand": "Cakita",
"category": "Power Tools/Drills",
"deliverTime": 3,
"discountPrice": "0",
"displayDiscountPrice": null,
"displayPrice": "€1499.00",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
"manufacturer": "Cakita",
"price": 1499,
"rating": 5,
"reviews": 3,
"stock": 5,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/16"
}
}
]
}
{
"data": [
{
"id": "3",
"type": "Power Tools/Drills",
"name": "Drill Screwdriver Brandix ALX7054 200 Watts",
"created_at": "2020-09-10T13:50:41+02:00",
"updated_at": "2021-06-09T13:22:09+02:00",
"attributes": {
"availability": "In stock",
"badges": [
],
"brand": "Wakita",
"category": "Power Tools/Drills",
"deliverTime": 1,
"discountPrice": "0",
"displayDiscountPrice": null,
"displayPrice": "€850.00",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-3.jpg",
"manufacturer": "Wakita",
"price": 850,
"rating": 4,
"reviews": 8,
"stock": 9,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/3"
}
},
{
"id": "4",
"type": "Power Tools/Drills",
"name": "Drill Series 3 Brandix KSR4590PQS 1500 Watts",
"created_at": "2020-09-10T14:38:37+02:00",
"updated_at": "2021-06-09T13:22:10+02:00",
"attributes": {
"availability": "In stock",
"badges": [
],
"brand": "Wakita",
"category": "Power Tools/Drills",
"deliverTime": 3,
"discountPrice": "0",
"displayDiscountPrice": null,
"displayPrice": "€949.00",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-4.jpg",
"manufacturer": "Wakita",
"price": 949,
"rating": 3,
"reviews": 15,
"stock": 4,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/4"
}
},
{
"id": "16",
"type": "Power Tools/Drills",
"name": "Brandix Screwdriver SCREW1500ACC",
"created_at": "2020-09-15T13:59:08+02:00",
"updated_at": "2021-06-09T14:06:33+02:00",
"attributes": {
"availability": "In stock",
"badges": [
],
"brand": "Cakita",
"category": "Power Tools/Drills",
"deliverTime": 3,
"discountPrice": "0",
"displayDiscountPrice": null,
"displayPrice": "€1499.00",
"image": "https://demo-retail-bp.docker-box.inpref.com/images/products/product-16.jpg",
"manufacturer": "Cakita",
"price": 1499,
"rating": 5,
"reviews": 3,
"stock": 5,
"url": "https://demo-retail-bp.docker-box.inpref.com/shop/product/16"
}
}
],
"debug": {
"slots": [
{
"dataPoint": {
"id": "3",
"weight": 12
},
"algorithm": "trending_viewed"
},
{
"dataPoint": {
"id": "4",
"weight": 6
},
"algorithm": "trending_viewed"
},
{
"dataPoint": {
"id": "16",
"weight": 6
},
"algorithm": "trending_viewed"
}
],
"dataPoints": [
{
"id": "3",
"weight": 12
},
{
"id": "4",
"weight": 6
},
{
"id": "16",
"weight": 6
}
],
"recos": [
{
"id": 2090,
"name": "strategy52_position1_trending_viewed",
"limit": 120,
"mapping": "product",
"filters": [
{
"Name": "Only include items that match the viewed category",
"Rules": [
{
"Source": "context",
"SourcePath": "page.category.categories",
"Attribute": "type",
"Operator": "startsWithAny",
"Value": ""
}
]
}
],
"postDynamicFilters": [
{
"ParamName": "type",
"Operator": "startsWithAny",
"Comparator": "[\"Power Tools/Drills\"]"
}
],
"modelUpdatedAt": "2021-06-09T11:29:26Z",
"params": null,
"excludeIds": null,
"dataPoints": [
{
"id": "3",
"weight": 12
},
{
"id": "4",
"weight": 6
},
{
"id": "16",
"weight": 6
}
]
},
{
"id": 2091,
"name": "strategy52_position2_trending_bought",
"limit": 120,
"mapping": "product",
"filters": [
{
"Name": "Only include items that match the viewed category",
"Rules": [
{
"Source": "context",
"SourcePath": "page.category.categories",
"Attribute": "type",
"Operator": "startsWithAny",
"Value": ""
}
]
}
],
"postDynamicFilters": [
{
"ParamName": "type",
"Operator": "startsWithAny",
"Comparator": "[\"Power Tools/Drills\"]"
}
],
"modelUpdatedAt": "2021-06-09T11:11:44Z",
"params": null,
"excludeIds": null,
"dataPoints": null
}
],
"strategy": {
"site_id": 2271,
"id": 52,
"id_string": "trending-in-category",
"slots": [
],
"positions": [
{
"id": 1,
"items": 4,
"algorithm": "trending_viewed",
"reco_id": 2090,
"anchor_source": "",
"anchor_source_path": "",
"anchor_items": 0
},
{
"id": 2,
"items": 4,
"algorithm": "trending_bought",
"reco_id": 2091,
"anchor_source": "",
"anchor_source_path": "",
"anchor_items": 0
}
],
"updated_at": "2021-03-12T06:56:47Z"
},
"positions": [
{
"id": 1,
"dataPoints": [
{
"id": "3",
"weight": 12
},
{
"id": "4",
"weight": 6
},
{
"id": "16",
"weight": 6
}
],
"addedDataPoints": [
{
"id": "3",
"weight": 12
},
{
"id": "4",
"weight": 6
},
{
"id": "16",
"weight": 6
}
],
"duplicateDataPoints": [
]
},
{
"id": 2,
"dataPoints": [
],
"addedDataPoints": [
],
"duplicateDataPoints": [
]
}
],
"context": {
"page": {
"type": "category",
"cart": null,
"category": {
"name": "Power Tools/Drills",
"categories": [
"Power Tools/Drills"
]
},
"product": null,
"search": null
},
"user": {
"area": "",
"lastBought": {
"ids": [
],
"categories": [
]
},
"lastViewed": {
"ids": [
],
"categories": [
]
},
"mostViewed": {
"ids": [
],
"categories": [
]
}
}
},
"productAPI": [
{
"id": "3",
"message": "added product data",
"cached": false
},
{
"id": "4",
"message": "added product data",
"cached": false
},
{
"id": "16",
"message": "added product data",
"cached": false
}
]
}
}