Skip to content

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 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 filters

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

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 or Spring 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.

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.

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 groups to list. 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 favourites notified for the current visitor. Requires Visitor identification for cross device personalisation.

Tip

Recommendations for product pages, ALTERNATIVES and UPSELL, are best utilized without filters. Too strict filters may prevent actual visitor behaviour 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 or size-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, dashes, and underscores.
CDP-2
limit int The number of content items to list. Defaults is page-type specific.

Type restrictions:
Must be postive a positivie 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.

Last update: October 5, 2021
Back to top
×
Copyright

This online publication is intellectual property of Apptus Technologies. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Apptus Technologies nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Apptus Technologies essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE