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:

HTTP
cURL
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",
"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",
"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.

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

HTTP
cURL
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": [
["category:RedWine"]
],
"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": [
["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.

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

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

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

Each session must have its own sessionId generated.

If the integrator expire, rotate, or lose sessionId data between ad serving and order submission, there is no way for CitrusAd to attribute orders. The sessionId submitted with orders must be identical to the sessionId sent in ad requests.

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

String

Description

Required?

your_api_key_here

Your API key

Required

catalogId

The id of the catalog the product belongs to. This is generated when you sync catalog and products.

Required

customerId

The id of the customer ads need generating for.

Optional

pageType

This field determines the type of ad that is to be returned. Home, Category, Search, and Specials fall into the display ad category which is applicable when user is browsing the website and looking for products to add to cart.

Required

searchTerm

The search term entered by the customer. This is used for filtering purposes.

Required

sessionId

A generated id that the integrator controls. It identifies a user's session. CitrusAd can use this for purchase attribution.

Optional

maxNumberOfAds

This is the maximum number of ads that CitrusAd generates. If advertisers have not provided enough requests for ad placements, the number of ads provided will not reach the number defined here. Must be greater than 0.

Required

productFilters

filters associated with the product, used to match ad generation filters

Required

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