Pages

You create and configure recommendations in the Frosmo Control Panel or through the Graniitti API. The following instructions only cover the Control Panel.

A recommendation configuration defines the settings for generating the data of a recommendation. The settings include:

  • Recommendation type
  • How often the recommendation data should be regenerated
  • Number of past hours of source data on which to base the recommendation
  • Maximum number of recommended items to return
  • Options for filtering the generated recommendation data

To create and configure a recommendation:

  1. In the Control Panel, select Data Management > Recommendations.
  2. Click Create recommendation.
  3. In the code editor, edit the recommendation configuration. The configuration is in the JSON format, so you need to directly edit the correct properties.
  4. Click Save. The Frosmo Platform queues the recommendation for processing.
  5. To return to the list of recommendations, click Cancel.

To track the generation progress, check the recommendation status, which updates dynamically on the page:

  • New: Recommendation generation has yet to be scheduled.
  • Scheduled: Recommendation generation has been scheduled. Depending on how many other recommendations are queued for generation, it might take anywhere from a fraction of a second to several minutes before the generation starts.
  • Started: Recommendation is being generated.
  • Success: Recommendation was successfully generated.
  • Failure: Recommendation generation failed.

Checking the recommendation generation status

Figure: Checking the recommendation generation status

Once the recommendation data has been successfully generated, you can retrieve it through the Recommendations API.

Recommendation configuration

For the full recommendation configuration specification, see the Graniitti API guide.

Settings: General

Table: General recommendation settings

PropertyDescriptionTypeExample
name

Descriptive name for the recommendation.

For users to easily distinguish between recommendations in the Frosmo Control Panel, it is recommended that you define a name that's unique within a site. The Frosmo Platform does not check the name for uniqueness.

String
"name": "Most viewed products"
descriptionDescription of what the recommendation is about.String
"description": "Top 10 most viewed products (24 h)"
frequency

How often the recommendation data should be regenerated.

The possible values are:

  • 15m: 15 minutes
  • 1h: 1 hour
  • 1d: 1 day (24 hours)

The default value is 15m.

If you enter a value not listed above and save the configuration, the platform ignores the value and retains the existing one (default value, unless previously saved to another valid value).

The generation time is calculated based on the last time the data was generated (either automatically or manually). For example, if the frequency is 15 minutes, and the data is generated at 10:15, the data is next generated at 10:30. If the frequency was 1 day, the data would be next generated at 10:30 the following day.

It is recommended that you set frequency based on hours as follows:

HoursFrequency
Less than or equal to 24 (1 day)15m
25168 (1 – 7 days)1h
Greater than 168 (7 days)1d

If generating the recommendation data takes longer than the defined frequency, increase the frequency, as there's no point in having a frequency that's shorter than the actual generation time. You can check the time after the recommendation data has been generated at least once.

String
"frequency": "15m"
hours

Number of past hours of source data on which to base the recommendation.

For example, if you set this to 10, the recommendation will always be generated based on the last 10 hours of product data collected from the site (views, purchases, and so on).

The maximum value is 336 (14 days).

Number
"hours": 24
limit

Maximum number of products to include in the recommendation.

The value must be between 1 and 120.

Number
"limit": 10
map_ids

If you want to return the product data for each recommended product, enter product.

If you want to return the raw recommendation data (product ID, recommendation weight, and optional custom data) for each product, enter an empty string.

String

Return product data:

"map_ids": "product"

Return raw recommendation data:

"map_ids": ""

Settings: Most viewed or purchased products

Table: Recommendation settings for most viewed or purchased products

PropertyDescriptionTypeExample
type

If you're creating a recommendation for most viewed products, enter most_viewed.

If you're creating a recommendation for most purchased products, enter most_converted.

String
"type": "most_viewed"
params

Names of the request parameters for filtering the recommendation data. If you also want to filter the recommendation data by segment, define a parameter for the segment ID as the last string in the array.

The parameters must be included in each Recommendations API request that retrieves this recommendation data.

You can filter recommendation data by any product data field or segment. How exactly you want to filter the data, and therefore what parameters to define for the request, is up to you. You can also freely name the parameters.

If you're using Recommendations API v2, you must define at least one parameter, as the API expects a request to include one or more parameters for filtering the recommendation data.

If you're using Recommendations API v1, do not use "name" as a parameter name, as the name property is reserved for defining the recommendation name in the API request.

The parameters together define a subset of recommended products whose data to return. In the request, you must define a value for each parameter. If you do not want to filter the returned data by a specific parameter, set its value to an empty string.

For example, if you want to return the recommendation data by product type, define a parameter name for type, such as type.

The options.product_attrs array defines how the parameters map to fields in the product data from which the recommendation is generated.

Array of strings

Filter products by product type:

"params": [
  "type"
]

Filter products by product name, type, and area:

"params": [
  "name",
  "type",
  "area"
]

Filter products by product type and visitor segment:

"params": [
  "type",
  "segment"
]
options.product_attrs

Product data fields for filtering the generated recommendation data.

Define the field names that map to the request parameters defined in the params array. The mapping is done in order, so make sure you provide the field names in the same order as the matching parameter names in the params array.

To find out the available product data fields, use the Product API.

The field names are based on the product object structure of a Product API response. Use the appropriate JavaScript accessor notation to reference nested object properties.

To reference a direct property of the product object, simply use its name (propertyName).

To reference a property of the attributes object, itself a direct property of the product object, use either dot notation (attributes.propertyName) or bracket notation (attributes['propertyName']).

To reference within an array or object property of the attributes object, use dot or bracket notation (attributes.propertyName.nestedName) or index notation (attributes.propertyName[i]) as appropriate, depending on the nesting structure leading up to the target element or property.

The product_attrs array tells the Frosmo Platform how to map the parameters in the Recommendations API request to product data fields.

For example, if you've defined a request parameter for product type, define type as the product data field name to which the parameter maps.

If you define no request parameters, meaning you do not want to filter the recommendation data, leave this array empty.

Array of strings

Map a lone request parameter to product type:

"options": {
  "product_attrs": [
    "type"
  ]
}

Map the first request parameter to product name, the second request parameter to product type, and the third request parameter to product area:

"options": {
  "product_attrs": [
    "name",
    "type",
    "attributes.area"
  ]
}

No request parameters to map to product data:

"options": {
  "product_attrs": []
}
options.segments

IDs of the segments by which you want to allow the returned recommendation data to be filtered. You can use one of the IDs in a Recommendations API request (as the value of the segment parameter) to retrieve the recommendations only for that segment. If you do not define the ID of a given segment, you cannot filter the results by that segment.

If you define one or more segment IDs, the params array must include one parameter for the segment ID as its last item.

For example, if you define segment as the last item in the params array, and you define the segment IDs 123 and 456 in this property, you can use the parameter "segment": "123" or "segment": "456" in the Recommendations API request to filter the returned data by the corresponding segment.

The segment IDs are numerical strings, such as "123", without the sgmt_ prefix, which you see as part of segment IDs in the Frosmo Control Panel.

Array of strings

Allow filtering by two segments:

"options": {
  "segments": [
    "123",
    "456"
  ]
}

Do not allow filtering by segment:

"options": {
  "segments": []
}
Example: Top 10 most viewed products in the past 24 hours by type
{
  "name": "Most viewed products",
  "description": "Top 10 most viewed products (24 h)",
  "type": "most_viewed",
  "frequency": "15m",
  "hours": 24,
  "limit": 10,
  "map_ids": "product",
  "params": [
    "type"
  ],
  "options": {
    "product_attrs": [
      "type"
    ]
  }
}
Example: Top 10 most viewed products in the past 24 hours by type and segment
{
  "name": "Most viewed products",
  "description": "Top 10 most viewed products (24 h)",
  "type": "most_viewed",
  "frequency": "15m",
  "hours": 24,
  "limit": 10,
  "map_ids": "product",
  "params": [
    "type",
    "segment"
  ],
  "options": {
    "product_attrs": [
      "type"
    ],
    "segments": [
      "123",
      "456"
    ]
  }
}

Settings: Products viewed, purchased, or viewed and purchased together

Table: Recommendation settings for products viewed, purchased, or viewed and purchased together

PropertyDescriptionTypeExample
type

If you're creating a recommendation for products viewed together, enter bundle_viewed.

If you're creating a recommendation for products purchased together, enter bundle_converted.

If you're creating a recommendation for products viewed and purchased together, enter bundle_viewed_converted.

Products need not have been purchased in the same transaction for them to be considered as purchased together. If the same visitor purchases two or more products within the time frame defined by the hours parameter, they are considered purchased together, regardless of whether the visitor purchased them as part of the same transaction or separate transactions.

String
"type": "bundle_viewed"
params

Name of the request parameter for providing the product ID for which to generate the recommendation. You can freely name the parameter.

Do not define any other parameters. You can only define the one parameter, which the Frosmo Platform automatically uses as the product ID for generating the recommendation.

Array of strings
"params": [
  "id"
]
options.basket_size

Maximum number of viewed or purchased products to consider per visitor, starting with the first view or purchase within the time frame over which the recommendation is generated.

For example, if you set this to 10, and a visitor purchases 20 products within the time frame over which the recommendation is generated, the generation will only consider and potentially return the first 10 purchases when determining which products were purchased together.

Number
"options": {
  basket_size": 20
}
Example: Top 5 products viewed together in the past 2 hours
{
  "name": "Products viewed together",
  "description": "Top 5 products viewed together (2 h)",
  "type": "bundle_viewed",
  "frequency": "15m",
  "hours": 2,
  "limit": 5,
  "map_ids": "product",
  "params": [
    "id"
  ],
  "options": {
    "basket_size": 20
  }
}
  • No labels