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 14.5

...

Information about the context into which the recommendation data is retrieved. The context consists of information about the current page (where the API request is made).

The context allows the API to return the correct recommendation data for the current page. The exact context information required depends on the page type of the recommendation strategy: the context must match the page type.

You specify the context object using the JSON format.

ParameterDescriptionTypeRoleExample
method

Request type.

Use the value strategy.

StringRequired


Code Block
languagebash
themeRDark
method=strategy


origin

Site origin.

To find out your site's origin, see Getting your site origin.

StringRequired


Code Block
languagebash
themeRDark
origin=shop_company_com


strategyRecommendation strategy ID.StringRequired


Code Block
languagetext
themeRDark
strategy=product-page--recommended-for-you
context
Note

Some algorithms require a user context, which provides information about the current visitor (whom the recommendation must target). The API does not currently support these algorithms nor strategies that use them.

Recommendation strategy context objectRequired


Code Block
languagebash
themeRDark
# Product page context context={ "page": { "product": { "cookieId

Local Frosmo ID of the visitor who sees the recommendation returned by the API request.

This parameter is required if (a) the strategy is set to apply some level of visitor affinity or (b) you want to apply affinity in the API request even if the strategy is not set to apply affinity. The ID allows the platform to use the visitor's affinity profile for personalizing the recommendation for the visitor.

This parameter has no effect if the strategy is not set to apply affinity or if affinityPercentage is not defined.

StringOptional


Code Block
languagetext
themeRDark
cookieId=dsr77t.kstzihlx


context

Information about the context into which the recommendation data is retrieved. The context consists of information about the current page (where the API request is made).

The context allows the API to return the correct recommendation data for the current page. The exact context information required depends on the page type of the recommendation strategy: the context must match the page type.

You specify the context object using the JSON format.

Note

Some algorithms require a user context, which provides information about the current visitor (whom the recommendation must target). The API does not currently support these algorithms nor strategies that use them.


Recommendation strategy context objectRequired


Code Block
languagebash
themeRDark
# Product page context

context={
  "page": {
    "product": {
      "id": "719",
      "category": "Books/Fiction/Fantasy"
    }
  }
}


shuffle

Define whether to randomly shuffle the order of items in the recommendation data.

By default, the items are in descending order of rank, with the most recommended item (as defined by the recommendation strategy) ranked highest.

The possible values are:

  • false: Do not shuffle the order of items.
  • true: Shuffle the order of items.

The default value is false.

BooleanaffinityPercentage

Level of visitor affinity (in percentages) applied to the recommendation. The higher the level, the more personalized the set of recommended items is for each individual visitor.

The minimum value is 0 (no affinity applied, an algorithm fully determines how the items it returns are ranked). The maximum value is 100 (affinity fully determines how the items returned by an algorithm are ranked).

If defined, this parameter overrides the level of affinity set in the strategy.

This parameter has no effect unless cookieId is also defined.

NumberOptional


Code Block
languagebash
themeRDark
shuffleaffinityPercentage=true50


debugshuffle

Define whether to return debugging information about the recommendation data.

The debugging information for a recommendation consists of:

The randomly shuffle the order of items in the recommendation data.

By default, the items are in descending order of rank, with the most recommended item (as defined by the recommendation strategy) ranked highest.

The possible values are:

  • false:  Do not return debugging informationDo not shuffle the order of items.
  • true:  Return debugging informationShuffle the order of items.

The default value is false.

BooleanOptional
Code Block
languagebash
themeRDark
debug=true

Recommendation strategy context object

The following table describes the context object for recommendation strategies. The object provides information about the context into which the recommendation data is retrieved.

Table: Recommendation strategy context object properties

...

Code Block
languagebash
themeRDark
# Page context object for a product page

"page": {
  "product": {
    "id": "719",
    "category": "Books/Fiction/Fantasy"
  }
}

Page context object

The following table describes the page object of the recommendation strategy context object. The page object provides context information about the current page.

Note

The page context must match the page type of the recommendation strategy.

...

Note

If any affinity is applied, shuffling is disabled, irrespective of the value of this parameter. Affinity is applied when cookieId is defined, and the level of affinity is set to greater than 0% either in the strategy or with affinityPercentage.


BooleanOptional


Code Block
languagebash
themeRDark
shuffle=true


debug

Define whether to return debugging information about the recommendation data.

The debugging information for a recommendation consists of:

The possible values are:

  • false: Do not return debugging information.
  • true: Return debugging information.

The default value is false.

BooleanOptional


Code Block
languagebash
themeRDark
debug=true


Recommendation strategy context object

The following table describes the context object for recommendation strategies. The object provides information about the context into which the recommendation data is retrieved.

Table: Recommendation strategy context object properties

Context
PropertyDescriptionTypeRoleExample
cartpageContext information about the current shopping cart page.Cart page Page context objectOptionalRequired


Code Block
languagebash
themeRDark
"cart# Page context object for a product page

"page": {
  "idsproduct": [{
    "id": "958719",
    "175",
    "280category": "Books/Fiction/Fantasy"
  ]}
}
category


Page context object

The following table describes the page object of the recommendation strategy context object. The page object provides context information about the current

...

page.

Note

...

The page context must match the page type of the recommendation strategy.

Table: Page context object properties

Optionalcodelanguagebashtheme"category":cartHere, "product" refers to any item that a site sells or offers to
PropertyDescriptionTypeRoleExample
RDarkContext information about the current shopping cart page.Cart page context objectOptional


Code Block
languagebash
themeRDark
"cart": {
  "nameids": "Books/Fiction/Fantasy",[
    "categories958": [,
    "Books/Fiction/Fantasy175",
    "Books/Fiction/Speculative280"
  ]
}


productcategoryContext information about the current product category page.
Info
Category page context objectOptional


Code Block
languagebash
themeRDark
"category": {
  "name": "Books/Fiction/Fantasy",
  "categories": [
    "Books/Fiction/Fantasy",
    "Books/Fiction/Speculative"
  ]
}


product

Context information about the current product page.

Info

Here, "product" refers to any item that a site sells or offers to visitors, or that the site otherwise tracks for conversions or transactions. A product can be, for example, a retail product, a blog article, an online game, a magazine subscription, or a downloadable brochure.


Product page context objectOptional


Code Block
languagebash
themeRDark
"product": {
  "id": "719",
  "category": "Books/Fiction/Fantasy"
}


searchContext information about the current search page.Search page context objectOptional


Code Block
languagebash
themeRDark
"search": {
  "ids": [
    "958",
    "655",
    "358",
    "809",
    "955"
  ],
  "categories": [
    "Books/Fiction/Fantasy",
    "Books/Fiction/Speculative"
    "Books/Fiction/Scifi"
  ]
}


...

PropertyDescriptionTypeRoleExample
ids

IDs of the items returned by the current search.

The IDs are relevant for strategies that use a Viewed together with recently searched items algorithm. The IDs are the target items against which the platform generates the recommendation.

The platform matches the IDs against the id attribute value tracked for an item.

Note

The platform only uses the first three IDs in the list, so it's enough that you provide just three IDs. You're free to choose the logic by which you select the IDs. The logic could be, for example, always taking the IDs of the top three items in the search results.


Array of stringsRequired


Code Block
languagebash
themeRDark
"ids": [
  "958",
  "655",
  "358"
]


categories

Names of the categories to which the returned items belong.

The category names are relevant for strategies that use a Viewed together with recently searched categories algorithm. The platform generates the recommendation against the listed categories.

The platform matches the category names against the type attribute value tracked for an item.

Note

The platform only uses the first three categories in the list, so it's enough that you provide the names of just three categories. You're free to choose the logic by which you select the categories. The logic could be, for example, always taking the categories of the top three items in the search results.


Tip

You can also use partial category names, since the API checks whether the category names in the database start with the strings you provide here.

For example:

  • "Music" matches Music, Musical Instruments, and any other category name that starts with "Music".
  • "Books/Fiction" matches Books/Fiction/FantasyBooks/Fiction/Speculative, and any other category name that starts with "Books/Fiction".


Array of stringsRequired


"categories": [ "Books/Fiction/Fantasy", "Books/Fiction/Speculative"
Code Block
languagebash
themeRDark
themeRDark
"categories": [
  "Books/Fiction/Fantasy",
  "Books/Fiction/Speculative"
  "Books/Fiction/Scifi"
]


Examples

Code Block
languagebash
themeRDark
titleExample: Product page recommendation
collapsetrue
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/Fantasy"
        }
      }
    }


Code Block
languagebash
themeRDark
titleExample: Product page recommendation, affinity applied
collapsetrue
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item-with-affinity&
    cookieId=dsr77t.kstzihlx&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/

...

Fantasy"
        }
      }
    }


Code Block
languagebash
themeRDark
titleExample: Product page recommendation, affinity applied, custom affinity percentage
collapsetrue
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=viewed-together-with-current-item-with-affinity&
    cookieId=dsr77t.kstzihlx&
    context={
      "page": {
        "product": {
          "id": "719",
          "category": "Books/Fiction/Fantasy"
        }
      }
    }&
    affinityPercentage=30


Code Block
languagebash
themeRDark
titleExample: Category page recommendation
collapsetrue
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=bought-together-with-current-category&
    context={
      "page": {
        "category": {
          "categories": [
            "Books/Fiction/Fantasy",
            "Books/Fiction/Speculative"
          ]
        }
      }
    }

...

Code Block
languagebash
themeRDark
titleExample: Home page ("other") recommendation
collapsetrue
GET https://inpref.com/recoApi/v2?method=strategy&
    origin=shop_company_com&
    strategy=trending-on-site&
    context={}

...