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 5.16

...

PropertyDescriptionTypeRoleExample
id

Recommendation ID.

Info

The Frosmo Platform sets this property. You cannot change it.


NumberRequired


Code Block
languagebash
themeRDark
"id": 1212


site_id

Site ID.

Info

The Frosmo Platform sets this property. You cannot change it.


NumberRequired


Code Block
languagebash
themeRDark
"site_id": 2080


name

Recommendation name.

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.

StringRequired


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


descriptionDescription of what the recommendation is about.StringOptional


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


type

Recommendation type.

The type defines the algorithm or filter that the Frosmo Platform uses to generate the recommendation data.

The possible values for the built-in types are:

  • bundle_converted
  • bundle_viewed
  • bundle_viewed_converted
  • most_converted
  • most_viewed

The default value is most_viewed.

For more information about the types, see Recommendations in the Frosmo Platform.

StringRequired


Code Block
languagebash
themeRDark
"type": "most_viewed"


status

Status of the recommendation data generation process.

The possible values are (in process order):

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

The default value is new.

Info

The Frosmo Platform sets this property. You cannot change it.


StringRequired


Code Block
languagebash
themeRDark
"status": "success"


duration

Total number of seconds it took to generate the recommendation data.

Info

The Frosmo Platform sets this property. You cannot change it.


NumberOptional


Code Block
languagebash
themeRDark
"duration": 2


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


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.


StringRequired


Code Block
languagebash
themeRDark
"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 data collected from the site.

The maximum value is 336 (14 days).

The default value is 1.

NumberRequired


Code Block
languagebash
themeRDark
"hours": 24


limit

Maximum number of items, such as products, to include in the recommendation.

The default value is 100.

The value must be between 1 and 120.

NumberRequired


Code Block
languagebash
themeRDark
"limit": 10


map_ids

Logic for mapping the IDs of the recommended items to source data in the Frosmo back end. This determines what data the recommendation actually returns for each item.

The possible values are:

  • product: Map each item ID to a product ID. Return the full product data for each ID.
  • Empty string: Do not map the item IDs to anything. Return the raw recommendation data (product ID, recommendation weight, and optional custom data) for each item. For more information, see Data point.

The default value is product.

StringOptional

Map each item ID to a product ID:

Code Block
languagebash
themeRDark
"map_ids": "product"

Do not map the item IDs:

Code Block
languagebash
themeRDark
"map_ids": ""


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 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 items whose data to return. In the request, you must either define values for all the parameters or leave all the values empty. In the latter case, the returned data is not filtered based on any parametersa 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're creating a product recommendation and want to return the recommendation data by product type, define a parameter name for type, such as type.

Info

If the recommendation type is bundle_converted, bundle_viewed, or bundle_viewed_converted, define only the parameter for providing the ID of the product for which to generate the recommendation. Do not define any other parameters.


Info

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

The default value is ["type"].

Array of stringsOptional

Filter items by type:

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

Filter items by name, type, and area:

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

Filter items by type and visitor segment:

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


options

Configuration options specific to recommendation type.

The default value is {}.

For more information, see Options object.

ObjectRequiredFor examples, see Options object.
model

Latest generated recommendation data and configuration details related to generating the data.

For more information, see Model object.

Note

The value of this property describes an object, but the Graniitti API returns the object in stringified form.


Info

The Frosmo Platform sets this property. You cannot change it.


String (stringified object)OptionalFor examples, see Model object.
error

Error trace of what happened when the recommendation data generation failed.

If the data generation was successful, the value is an empty string.

StringOptional


Code Block
languagebash
themeRDark
"error": ""


created_at

Date and time when the recommendation was created.

For more information about the data and time format, see Data formats.

Info

The Frosmo Platform sets this property. You cannot change it.


StringRequired


Code Block
languagebash
themeRDark
"created_at": "2018-11-08T10:37:25+00:00"


updated_at

Date and time when the recommendation was last updated.

For more information about the data and time format, see Data formats.

Info

The Frosmo Platform sets this property. You cannot change it.


StringRequired


Code Block
languagebash
themeRDark
"updated_at": "2018-11-20T12:07:08+00:00"


...

For recommendation types that allow empty parameter values, meaning unfiltered results, the :

  • The first data point set has an empty string as its key ("") and contains all the recommended items
  • The data point sets also include combinations for cases where one or more parameters are set to empty values. The keys for these sets are built with the non-empty values.

For example, if a most_converted product recommendation defines the request parameters type and color, the recommendation data will contain data point sets for every combination of type and color values found among the product data stored in the Frosmo database. The , including data point sets where the other parameter value is empty. The following example shows the data point sets when the database contains products of type Shoe in colors Black and White and products of type Suit in colors Black, Brown Purple, and Red.

Code Block
languagebash
themeRDark
"data": {
  "": [<data points for all recommended products> products, no filtering by any parameter>],
  "Shoe": [<data points for recommended shoes, no filtering by color>],
  "ShoeBlack": [<data points for recommended black shoes>],
  "ShoeWhite": [<data points for recommended white shoes>],
  "Suit": [<data points for recommended suits, no filtering by color>],
  "SuitBlack": [<data points for recommended black suits>],
  "SuitBrownSuitPurple": [<data points for recommended brownpurple suits>],
  "SuitRed": [<data points for recommended red suits>]
},
  "Black": [<data points for recommended black products, no filtering by type>],
  "Purple": [<data points for recommended purple products, no filtering by type>],
  "Red": [<data points for recommended red products, no filtering by type>],
  "White": [<data points for recommended white products, no filtering by type>]
}

When a client calls the Recommendations API for the above recommendation, the platform constructs the return returned data from the data points matching the parameters defined in the client's request. For example, in the request:

  • If "type":"" and color are empty strings "color":"", the platform uses the "" data point set.
  • If "type":"" and "color":"Purple", the platform uses the Purple data point set.
  • If "type=":"Shoe" and color=White "color":"", the platform uses the ShoeWhite Shoe data point set.
  • If "type=":"Suit" and "color=":"Red", the platform uses the SuitRed data point set.
  • If "type=":"Shoe" and "color=":"Orange", the platform returns an errorempty data object, as there's no ShoeOrange data point.

...