Page Configurations¶
The content of pages can be modified through supplying a page configuration. The page configuration allows pages to be extended with additional recommendation listings and supports product rules and filtering of primary product listings, such as search results and category pages.
Pages with modified content must be retrieved through POST
requests, where the content modification specification is supplied as the body.
Product rules¶
Product rules, productRules
, is a configuration that is equal to defining a Product selection in the eSales Apps. The product rules are a form of logical expressions that are used to restrict the data set used in a query. Rules can go from easy, such as to only include a single product using its product key or items that are in stock, to more complex with multiple attributes for the product selection.
An expression may consist of multiple rules where each rule must have at least one restriction. A restriction must include a condition, which in turn consist of an attribute that is either a list of strings, an interval, or a specified newness.
Risk of competing product selections
Product filters and Product rules cannot be present in the same page configuration.
Definitions | Description |
---|---|
Rule | A rule, rule , must have at least one restriction. Rules are separated with a space. |
Restriction | A restriction is either an include, incl , or an exclude, excl , followed by a condition. |
Condition | A condition must consist of an attribute and is either a list of strings, a numeric interval, or a specified newness. |
Attribute | An attribute as defined in the data feed. Can be either product_key , department , brand , pattern , custom. , price , discount , rating , stock_number , or newness . |
List of strings | A list of strings. A list of strings is enclosed within curly brackets, { } , with each string enclosed with double quotation marks, " . Strings are separated with a space. Double quotation marks and backslashes within strings are escaped with a prefixed backslash, \ . |
Interval | A closed numeric range, enclosed within square brackets, [ ] . Numbers are separated by a comma, , . -infinity and infinity are used to specify undefined min and max values. |
Newness | The age of the products in days, calculated using the release_date attribute in the data feed. Can be a positive integer suffixed by the character d , or default . If default is used, the number of days as defined in the Page settings will be used. |
Number | Any decimal number from 4.9e-324 up to and including 1.7976931348623157e308. |
Positive integer | Any positive integer between 1 up to and including 2 147 483 647. |
When productRules
is used with Category and Landing Pages and product keys are specified equal to Handpicked, this rule must be the first rule and must contain a set of product keys as the only condition.
Examples¶
Handpick products p1234
and p5678
.
rule incl product_key { "p1234" "p5678" }
Include only products with the pattern striped
with default newness.
rule incl pattern { "striped" } incl newness default
Include products from the brands Bosch
or Dewalt
, but exclude products with a price
above 2000
.
rule incl brand { "Bosch" "Dewalt" } excl price [ 2000.01, infinity ]
Include products from the department Kids
where newness
is three days or less, and the products have a rating
between 3
and 5
.
rule incl department { "Kids" } incl newness 3d incl rating [ 3, 5 ]
Include in-stock products from the categories Kitchen
and Dining
with a discount
that is less than 30%.
rule incl custom.category_name { "Kitchen" "Dining" } incl discount [ -infinity, 30 ] incl stock_number [ 1, infinity ]
Include all products that match any of the included rules.
rule incl product_key { "ABC123" "DEF456" "GHJ789" }
rule incl custom.material { "leather" } excl price [ -infinity, 100.00 ]
rule incl newness 10d
rule incl brand { "Birkenstock" } excl custom.isActive { "false" }
Product filters¶
To be superseded
The Product filters configuration is to be superseded by the Product rules configuration. It is recommended to use the Product rules configuration for new eSales 4 integrations.
Product filters can be applied to both primary listings and recommendation listings and are included in the request body for the target listing. Applying a filter will restrict the set of returned products to be included in the actual result set and can be either numeric or value filters.
Listing multiple attributes to filter on will restrict the products to all conditions (logical AND
). When listing values within one attribute, products with any of the listed properties apply (logical OR
).
Risk of competing product selections
Product filters and Product rules cannot be present in the same page configuration.
Request example
The following illustrates an example on applying a filter for a Calvin Klein outlet of products from old seasons.
- All products will be of the brand
Calvin Klein
. - All products will at least be 1 percent discounted.
- All products belong to either the
Winter
orSpring
season.
{
"productFilter": {
"brand": "Calvin Klein",
"discount": {"min": 1},
"custom.season": ["Winter", "Spring"],
}
}
Numeric product filters¶
Numeric filters can be provided as a range, single values, or as lists of values. All ranges are inclusive and may be provided with a one sided limitation, where min
defaults to 0
and max
defaults to the maximum eligible value.
Request example
{
"price": {"max": 300.0},
"discount": 70,
"rating": {"min": 4.0, "max": 5.0},
"stock_number": [0, 1, 2]
}
Supported numeric filter attributes¶
Name | Type | Description |
---|---|---|
discount | int | The discount percentage of the product. |
price | double | The selling price of the product. |
rating | double | The rating of the product. |
stock_number | int | The stock number of the variants in the product. Will include applicable variants. |
daysOld | int | The age of the product in days, calculated using the release_date attribute in the data feed. This enables queries to include a max age for displayed products when displaying new products. Must be provided on the form "daysOld": {"max": 7} (value selections and requests providing a min value will be rejected). Related to isNew in Supported value filter attributes. |
Value product filters¶
Value filters can be provided as single values or as a list of values.
Request example
{
"brand": "Calvin Klein",
"custom.season": ["Winter", "Spring"],
}
Supported value filter attributes¶
Name | Type | Description |
---|---|---|
pattern | string | The pattern value of the product as provided in the data feed. |
department | string | The department value of the product as provided in the data feed. |
brand | string | The brand value of the product as provided in the data feed. |
custom.* | string | Any custom attribute can be used as a value filter, through prefixing the attribute to be filtered with custom. , for example custom.season . |
product_key | string | The key of the product as provided in the data feed. |
isNew | boolean | Whether the product is considered new, as defined in the settings for New products in the Experience App. By default, "isNew": true includes products newer than 7 days. Same as daysOld , see Supported numeric filter attributes, but based on the app setting instead of a fixed max limit. "isNew": false will not apply any filter. |
Primary list¶
Some page types include primary listings such as search and category pages. Primary lists can be configured with filters settings.
Request example
{
"primaryList": {
"include": true,
"productFilter": {
"brand": "Calvin Klein"
}
}
}
Name | Type | Description |
---|---|---|
include | boolean | Specifies if the primary list should be included or not in the response. Always included in search page requests. |
productFilter | ProductFilter | A product filter restricting which products that the listing may contain. |
Recommendation lists¶
Most page types support recommendation lists. To include recommendation lists in a page response, the request body must include the recommendation configuration.
Request example
{
"recommendationLists": [
{
"id": "START-PAGE-1",
"limit": 8,
"algorithm": "PERSONAL"
},
{
"id": "START-PAGE-2",
"algorithm": "ALTERNATIVES",
"params": {
"productKey": "P1"
}
},
{
"id": "START-PAGE-3",
"algorithm": "TOP_PRODUCTS",
"productFilter": {
"discount": {"min": 1}
}
},
]
}
Name | Type | Description | Example |
---|---|---|---|
id | string | An identifier for the recommendation listing area. Multiple pages using the same template can share identifiers, but one identifier may not appear twice within a page. E.g. all product pages should use the same identifier for their alternative recommendation areas. Required | PDP-1 |
algorithm | Algorithm | The algorithm to apply on the recommendation listing. Defaults to TOP_PRODUCTS . | PERSONAL |
params | Parameters | Any parameters required by the applied algorithm. Conditionally required | { "productKey": "P1" } |
limit | int | The number of product hits to list. For each product hit in the list, its product group is returned in full to facilitate rendering of color swatches and more. Defaults to 4 . | 8 |
productFilter | ProductFilter | An expression restricting the products that the recommendation listing may contain. | { "discount": {"min": 1} } |
Algorithms¶
Name | Description |
---|---|
TOP_PRODUCTS | Returns the most relevant product within the provided filter, based on set business goals. |
PERSONAL | Returns personal recommendations based on the interaction history of the current visitor. Requires Visitor identification for cross device personalisation. |
ALTERNATIVES | Returns alternative products based on a product key. Requires productKey as parameter. |
UPSELL | Returns complementary products for up sell, based on a product key. Requires productKey as parameter. |
CART | Returns recommendations based on the provided cart products. Requires cart as parameter. |
NEWEST_PRODUCTS | Returns the newest products within the provided filter, productFilter . |
STYLE_WITH | Returns products defined by the retailer in the data feed based on a product key. Requires productKey as parameter. |
FAVORITES | Returns recommendations based on favorites notified for the current visitor. Requires Visitor identification for cross device personalisation. |
Avoid filters for product recommendations
Recommendations for product pages, ALTERNATIVES
and UPSELL
, are best utilized without filters. Too strict filters may prevent actual visitor behavior to being properly reflected and thus reduce sales.
Parameters¶
Name | Type | Description | Example |
---|---|---|---|
productKey | string | The base product for the ALTERNATIVES , STYLE_WITH , and UPSELL recommendation algorithms. Defaults to the provided product key parameter for product-page requests. | P1 |
cart | string[ ] | A list of product and/or variant keys depicting the cart content. Must match keys of variants or products in the data feed. Always use the variant key when possible. Defaults to the provided cart parameter for cart-page requests. | ["P2", "V2", "V3"] |
Content filters¶
Content filters can be applied to most content listings and are included in the request body for the target listing. Applying a filter will restrict the set of returned content and can only be string value filters e.g. not numeric.
Listing multiple attributes to filter on will restrict the content to all conditions (logical AND
). When listing values within one attribute, content with any of the listed properties apply (logical OR
).
Request example
The following illustrates an example on applying a filter for content by the author Pelle
containg both articles and size-guides.
- All content will be from the author
Pelle
. - All products will be of either the
article
orsize-guide
type.
{
"contentFilter": {
"custom.author": "Pelle",
"type": ["article", "size-guide"]
}
}
Value content filters¶
Value filters can be provided as single values or as a list of values.
Request example
{
"type": "article",
"custom.season": ["Winter", "Spring"]
}
Supported value filter attributes¶
Name | Type | Description |
---|---|---|
type | string | The type value of the content item as provided in the data feed. |
custom.* | string | Any custom attribute can be used as a value filter, through prefixing the attribute to be filtered with custom. , for example custom.season . |
content_key | string | The key of the content item as provided in the data feed. |
Content lists¶
Search-page, autocomplete and landing-page support content lists. To include content lists in a page response, the request body must include a content list configuration.
Request example
{
"contentLists": [
{
"id": "bottom-right-mini-faq",
"limit": 8,
"contentFilter": {
"type": "faq"
}
}
]
}
Name | Type | Description | Example |
---|---|---|---|
id | string | An identifier for the content listing area. Multiple pages using the same template can share identifiers, but one identifier may not appear twice within a page. Required Type restrictions: Maximum length is 20 characters. Allowed characters are letters, numbers, dash, and underscore. | CDP-2 |
limit | int | The number of content items to list. Defaults is page-type specific. Type restrictions: Must be a positive number that is less than 200. | 8 |
contentFilter | ContentFilter | An expression restricting the content in the content listing. | { "type": "article" } |
algorithm | Algorithm | The algorithm to apply on the content listing. The algorithm only works when used on a Category Page and Landing page. Defaults to TOP_CONTENT . | NEWEST_CONTENT |
Algorithms (Content)¶
Name | Description |
---|---|
TOP_CONTENT | Returns the most relevant content, based on clicks. |
NEWEST_CONTENT | Returns the newest content based on releaseDate of the content items as provided in the data feed. Content items with the same release date are internally sorted by TOP_CONTENT . |