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

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

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": [
      ["category:RedWine", "category:Shiraz"]
    ],
    "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:

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

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

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": [
      ["category:RedWine", "category:Shiraz", "filter:Australian"]
    ],
    "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 , category:Shiraz and type:Australian

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

Using Customer Data in Ad Generation

By sending a customerId in your ad generation request, CitrusAd can generate more relevant ads to each individual customerId. An example can be seen below:

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",
    "customerId": "3g4e33rr45s3",
    "searchTerm": "Wine",
        "productFilters": [
      ["category:RedWine", "category:Shiraz"]
    ],
    "maxNumberOfAds": 5
}

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",
    "customerId": "3g4e33rr45s3",
    "searchTerm": "Wine",
        "productFilters": [
      ["category:RedWine", "category:Shiraz"]
    ],
    "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

• Be relevant to the customerId

To utilise this, you will need to be syncing customer data.

Using Session Ids for Order Attribution

If you are planning on using sessionIds as your method of order attribution, you will need to send a sessionId in your ad generation requests:

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": [
      ["category:RedWine", "category:Shiraz"]
    ],
    "sessionId": "23dn3923-323d" 
    "maxNumberOfAds": 5
}

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": [
      ["category:RedWine", "category:Shiraz"]
    ],
    "sessionId": "23dn3923-323d" 
    "maxNumberOfAds": 5
}'

For more information on using sessionIds for order attribution, see "Syncing Order Data":

Requesting Ads

Please see the below resources for requesting ads for each type of ad:

Reference

Relevant Context Fields

For a glossary of all terms in the documentation, see the reference.