Pages

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Comment: Published by Scroll Versions from this space and version 8.0

You Learn how to 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 > Configurations.
  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 statusImage Removed

Figure: Checking the recommendation generation status

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

Recommendation configuration

Table of Contents
maxLevel2
minLevel2

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

Settings: General

Table: General recommendation settings

...

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.

...

Code Block
languagebash
themeRDark
"name": "Most viewed products"

...

Code Block
languagebash
themeRDark
"description": "Top 10 most viewed products (24 h)"

...

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
Info

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.

...

Code Block
languagebash
themeRDark
"frequency": "15m"

...

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

...

Code Block
languagebash
themeRDark
"hours": 24

...

Maximum number of products to include in the recommendation.

The value must be between 1 and 120.

...

Code Block
languagebash
themeRDark
"limit": 10

...

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.

...

Return product data:

Code Block
languagebash
themeRDark
"map_ids": "product"

Return raw recommendation data:

Code Block
languagebash
themeRDark
"map_ids": ""

...

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.

Info

The field names are based on the product object properties of a Product API response.

To reference a property, whether a direct property of the product object, such as name, or a child property of the attributes object, such as price, simply use the property's name.

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

You can also reference a property of the attributes object by using either dot notation (attributes.propertyName) or bracket notation (attributes['propertyName']), but this method is officially deprecated and will be phased out in the future.

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.

The default value is [].

...

Map a lone request parameter to product type:

Code Block
languagebash
themeRDark
"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:

Code Block
languagebash
themeRDark
"options": {
  "product_attrs": [
    "name",
    "type",
    "area"
  ]
}

No request parameters to map to product data:

Code Block
languagebash
themeRDark
"options": {
  "product_attrs": []
}

...

Advanced product data filters for refining the set of recommended products to return.

While params define the product data fields and segments that you can specify in a Recommendations API request to filter the results, filters define advanced result filtering that the platform applies automatically to all requests.

Note

filters apply only to product data fields. If you want to filter recommendation results based on segments, use params.

If you define multiple filters, the platform applies them all, that is, the platform treats the filters as combined with logical AND operators. The platform only returns items for whom all the filters evalute to true.

The platform automatically applies filters on top of the filtering performed with params. If a request does not perform any filtering with params, either because the recommendation configuration does not define any params or because the request uses empty values for its params, the platform nonetheless applies the filters, if defined.

The default value is null.

For more information, see Filter object.

...

Exclude books:

Code Block
languagebash
themeRDark
"filters": [{
    "name": "Exclude books",
    "rules": [{
        "attribute": "type",
        "operator": "!=",
        "value": "Books"
    }]
}]

Only return books whose title ends with "for dummies" and that cost less than 30 (in the site currency):

Code Block
languagebash
themeRDark
"filters": [{
    "name": "Include 'For Dummies' books",
    "rules": [{
        "attribute": "type",
        "operator": "=",
        "value": "Books"
    },{
        "attribute": "name",
        "operator": "endsWith",
        "value": "for dummies"
    }]
},{
    "name": "Include products that cost < 30",
    "rules": [{
        "attribute": "price",
        "operator": "<",
        "value": "30"
    }]
}]

For more examples, see the recommendations developer guide.

Settings: Most viewed or purchased products

Table: Recommendation settings for most viewed or purchased products

...

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.

...

Code Block
languagebash
themeRDark
"type": "most_viewed"

...

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.

Note

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.

Note

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.

Info

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

...

Filter products by product type:

Code Block
languagebash
themeRDark
"params": [
  "type"
]

Filter products by product name, type, and area:

Code Block
languagebash
themeRDark
"params": [
  "name",
  "type",
  "area"
]

Filter products by product type and visitor segment:

Code Block
languagebash
themeRDark
"params": [
  "type",
  "segment"
]

...

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.

...

Allow filtering by two segments:

Code Block
languagebash
themeRDark
"options": {
  "segments": [
    "123",
    "456"
  ]
}

Do not allow filtering by segment:

Code Block
languagebash
themeRDark
"options": {
  "segments": []
}
Code Block
languagebash
themeRDark
titleExample: 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"
    ]
  }
}
Code Block
languagebash
themeRDark
titleExample: 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

...

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.

Info

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.

...

Code Block
languagebash
themeRDark
"type": "bundle_viewed"

...

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

Note

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.

...

Code Block
languagebash
themeRDark
"params": [
  "id"
]

...

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.

...

Code Block
languagebash
themeRDark
"options": {
  basket_size": 20
}
Code Block
languagebash
themeRDark
titleExample: 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
  }
}

Filter object

The following table describes the filter object of the filters array. A filter defines a single rule set for filtering recommended products.

Table: Filter object properties

...

Code Block
languagebash
themeRDark
"name": "Exclude books"

...

One or more rules that together define the filtering logic for the filter.

If you define multiple rules, the platform applies them all, that is, the platform treats the rules as combined with logical AND operators. The platform only returns products for whom all the rules evalute to true.

For more information, see Filter rule object.

...

Code Block
languagebash
themeRDark
"rules": [{
    "attribute": "type",
    "operator": "!=",
    "value": "Books"
}]

Filter rule object

The following table describes the filter rule object of the rules array. A filter rule defines a single comparison operation that is used to include or exclude products from recommendation results.

Table: Filter rule object properties

...

Code Block
languagebash
themeRDark
"attribute": "type"

...

Relational operator used to compare the value of the field defined in attribute to the value defined in value.

The comparison is case insensitive.

The platform supports the following operators:

  • =
  • !=
  • <
  • >
  • <=
  • >=
  • startsWith
  • endsWith
  • contains
  • in (value must be a JSON-stringified array)
  • notIn (value must be a JSON-stringified array)
  • regex

By default, the platform treats the product data field and value as strings. If the product data field is price or quantity, and if the operator is <, >, <=, or >=, the platform treats the product data field and value as numbers, not as strings, for comparison purposes.

For regular expressions (regex), use the RE2 syntax.

...

Code Block
languagebash
themeRDark
"operator": "!="

...

Value against which the value of the field defined in attribute is compared.

The value can be either a regular string or, if the operator is in or notIn, a JSON-stringified array.

...

Compare against a regular string:

Code Block
languagebash
themeRDark
"value": "Books"

Compare against a JSON-stringified array:

...

languagebash
themeRDark

...

Platform:

Table of Contents
maxLevel1

Before you start

Recommendations typically rely on data collected from the site, but they can also use data that is directly fed or imported to the Frosmo Platform. Before you can create a recommendation, you must have the necessary data tracking implemented, or you must otherwise fetch and store the data to the Frosmo back end.

For example, a retail product recommendation relies on product data and transaction data. The product data gives you:

  • The product information, such as name and price, that you display in the recommendation
  • The product view statistics that tell the recommendation engine which products get the most views and which products visitors typically view together

The transaction data, in turn, tells the recommendation engine how well different products sell and which products visitors typically purchase together.

You can use either the product view statistics or the transaction data, or both, to drive how product recommendations are generated. But you need to first get the data:

  • For the product data, you must have product tracking set up on the site, or you must use a product data feed or file import to store the data to the Frosmo back end.
  • For the transaction data, you must have transaction tracking set up on the site.

Once the data is accumulating in the Frosmo back end, you can start generating product recommendations from it. To check whether the data is coming in from the site, check the site status.

Getting the data required to generate product recommendationsImage Added

Figure: Getting the data required to generate product recommendations (click to enlarge)

For more information about tracking data on a site, see:

If you want to use a data feed or file import, contact Frosmo support, as only a Frosmo team can currently implement these solutions.

Creating a recommendation

A recommendation is the end product of multiple Frosmo components working together. Some of the components are mandatory, while some are optional.

Components of a recommendation coming together on the pageImage Added

Figure: Components of a recommendation coming together on the page

Tip

You can use a workspace to develop and test the modification, placement, and optionally template of the recommendation.

To create a recommendation:

  1. Plan the recommendation. This involves answering questions such as:
    • What business goal do you want to achieve with the recommendation?
    • What type of recommendation do you want to create?
    • What items do you want to recommend?
    • Who do you want to target with the recommendation?
    • When, where, how do you want to display the recommendation on the site?
  2. Create a recommendation configuration. The recommendation configuration defines the logic and settings for generating the recommendation data.
  3. Optionally, create a template for the recommendation. If you want to use the same recommendation in multiple modifications, create the recommendation as a template.

    For example, if you want to create a customizable recommendation carousel that can be used in different parts of the site, create the carousel as a template with the relevant content options, and then use and configure the template in individual modifications.

  4. Create a modification for the recommendation. Create the necessary placement and optionally segments for the modification.

    The modification both defines the recommendation content and displays that content on the site. You can define the content either directly in the modification as custom content for a variation, or in a template that you then use in a variation (see step 3 above).

    Irrespective of where you define the content, the content must:

    • Create the web page element for the recommendation. This is the static part of the recommendation: the HTML, CSS, and JavaScript that together define how the recommendation looks and behaves on the page.
    • Fetch the recommendation data, and populate the web page element with that data. This is the dynamically generated content of the recommendation: the details of the recommended items. You fetch the recommendation data using the Recommendations API.
  5. Test the recommendation. You can use variation preview or test mode.
  6. Publish the recommendation. You do this by activating the modification (or, if the modification is already active but in test mode, by disabling test mode for the modification).

The recommendation is now live on the site. You can freely edit the different components to improve or otherwise change how the recommendation looks and works.

For an end-to-end example of creating a product recommendation, see Example: Recommending products purchased together.