Requesting Ads (the "Context" and its Parts)

What Is A Context?

In order to request ads, you must provide a context. A context is a set of filters that ad campaigns must be eligible for before they are shown.

A Context is what ensures ads remain relevant, this is because ads must meet each of the defined filters of the context before being shown.

On this page, contexts for Product Ads are displayed.

Before you request ads, you will need your catalogIdand yourapi key.

A Simple Search Context

A simple context can be used as an example. Below is a simple context for a search page:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}'

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Target the search term Wine

Each context is made of various relevant parts, each of the above can be viewed in the page reference at the end of the page.

A Filtered Search Context

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

In this example, the user has navigated to the Red Wine category within their search, and filtered their browsing to to "Shiraz" Red Wines. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["taxonomy:RedWine>Shiraz"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Target the search term Wine
Be a product with the productFilters of category:RedWine and category:Shiraz

For more information on product filters, see the "Syncing Catalog & Products" page:

A Simple Category Context

A simple context can be used as an example. Category pages use productFilters to match product properties to each page. Below is a simple context for a category page:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}'

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Be a product with the productFilters of the category Redwine

Each context is made of various relevant parts, each of the above can be viewed in the page reference at the end of the page.

A Further Filtered Category Context

When a user filters their browsing deeper, you are able to serve ads relevant to their filters using productFilters in the context.

In this example, the user has entered the Red Wine category, filtered their browsing to to "Shiraz" Red Wines and selected the "Australian" type. This is a new request and considered by Project Agora Commerce as a new page, and new set of ads. Even in the rare event the ads served are identical to the unfiltered results.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine>Shiraz", "filter:Australian"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}

curl -iX POST "$BASE_URL/v1/ads/generate" \ 
-H "accept: application/json" \
-H "content-type: application/json" \
-H "Authorization: Basic your_api_key_goes_here" \
-d \
'{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:RedWine>Shiraz", "filter:Australian"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 5,
    "sessionId": "23dn3923-323d"
}'

For an ad to be eligible for this context, it must:

Have the catalog selected with the displayed catalogId
Be a product with the productFilters of categories Redwine and subcategory Shiraz and type:Australian

For more information on product filters, see the "Syncing Catalog & Products" page

sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page

PreviousReference NextProduct Listing Ad Integration Guide

Last updated 3 years ago