Pages

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. To verify that the data for the strategy has been generated, preview the data.

To return the correct recommendation data, some algorithms require extra information about the current page or visitor. This information is known as the context for a strategy. On a website, the context can be set programmatically with Frosmo Core, so that pages load with the correct context automatically available. Frosmo developers create the correct context setup for a site. In cases where this setup is not available or possible, you must explicitly provide the context when retrieving the recommendation data for a strategy. For more information about the context, see the context parameter documentation in the Recommendations API guide.

You have two options for retrieving the recommendation data:

  • Frosmo Core fetch function. Use this option if you're retrieving the data on a website that has a context setup in place. For more information, see the following section.
  • 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 context setup. You must provide the context as part of the API request. For more information, see the Recommendations API guide.

    The API does not currently support algorithms that require context information about the current visitor. You cannot use the API to retrieve data for strategies that use these algorithms.

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.

Frosmo Core fetch function

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

  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. For more information about the function, see fetch() request.
  2. 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 context for the strategy has been set and that the context matches the page type defined for the strategy. If the correct 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 the correct product 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()

ParameterDescriptionTypeRoleExample
strategy

ID of the recommendation strategy whose recommendation data to retrieve.

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

StringRequired
frosmo.easy.strategies.fetch('strategy-id')
options

Options for configuring the fetch and response.

For more information, see the following table.

ObjectOptional
frosmo.easy.strategies.fetch('strategy-id', {shuffle: true})

Table: Options object properties

PropertyDescriptionTypeRoleExample
debug

Define whether to return debugging information about the recommendation data.

The possible values are:

  • false: Do not return debugging information.
  • true: Return debugging information.

The default value is false.

BooleanOptional
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:

  • false: Do not shuffle the order of items.
  • true: Shuffle the order of items.

The default value is false.

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

NumberOptional
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 the debug option is set to true in the fetch call.

The following examples show the same response without and with debugging information.

Example: Recommendation data in a response
{
  "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"
      }
    }
  ]
}
Example: Recommendation data in a response 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"
      }
    }
  ],
  "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
      }
    ]
  }
}