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.

Syncing Catalog & Products

A Simple Search Context

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

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_goes_here
{
    "pageType": "Search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
     "productFilters": [["placement:SponsoredProducts"]],
    "searchTerm": "Wine",
    "maxNumberOfAds": 5
}

cURL

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 \
'{
    "pageType": "Search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
     "productFilters": [["placement:SponsoredProducts"]],
    "searchTerm": "Wine",
    "maxNumberOfAds": 5
}'

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.

HTTP

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

cURL

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 \
'{
    "pageType": "Search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["RedWine", "Shiraz","placement:SponsoredProducts"]
    ],
    "maxNumberOfAds": 5
}'

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:

Syncing Catalog & Products

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:

HTTP

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

cURL

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 \
'{
    "pageType": "Category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["RedWine","placement:SponsoredProducts"]
    ],
    "maxNumberOfAds": 5
}'

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

HTTP

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

cURL

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 \
'{
    "pageType": "Category",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["RedWine", "Shiraz", "filter:Australian","placement:SponsoredProducts"]
    ],
    "maxNumberOfAds": 5
}'

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

• Contain the SPL default product filter "placement:SponsoredProducts"

• Have the catalog selected with the displayed catalogId

• Be a product with the productFilters of category:RedWine , category:Shiraz and type:Australian

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