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 catalogId
and yourapi key
.
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.1accept: application/jsoncontent-type: application/jsonAuthorization: Basic your_api_key_goes_here{"customerId": "string","sessionId": "string","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 \'{"customerId": "string","sessionId": "string","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.
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.1accept: application/jsoncontent-type: application/jsonAuthorization: Basic your_api_key_goes_here{"customerId": "wertg5432a","sessionId": "ec9-4e07-881d-3e9","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 \'{"customerId": "wertg5432a","sessionId": "ec9-4e07-881d-3e9","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 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.1accept: application/jsoncontent-type: application/jsonAuthorization: Basic your_api_key_goes_here{"customerId": "wertg5432a","sessionId": "ec9-4e07-881d-3e9","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 \'{"customerId": "wertg5432a","sessionId": "ec9-4e07-881d-3e9","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.
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.1accept: application/jsoncontent-type: application/jsonAuthorization: Basic your_api_key_goes_here{"customerId": "wertg5432a","sessionId": "ec9-4e07-881d-3e9","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 \'{"customerId": "wertg5432a","sessionId": "ec9-4e07-881d-3e9","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:
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.1accept: application/jsoncontent-type: application/jsonAuthorization: Basic your_api_key_goes_here{"pageType": "Search","catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b","customerId": "3g4e33rr45s3","sessionId": "ec9-4e07-881d-3e9","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","sessionId": "ec9-4e07-881d-3e9","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.
If you are planning on using sessionId
s 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.1accept: application/jsoncontent-type: application/jsonAuthorization: Basic your_api_key_goes_here{"pageType": "Search","catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b","customerId": "3g4e33rr45s3","searchTerm": "Wine","productFilters": [["category:RedWine", "category:Shiraz"]],"customerId": "wertg5432a","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"]],"customerId": "wertg5432a","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 sessionId
s for order attribution, see "Syncing Order Data":
Please see the below resources for requesting ads for each type of ad:
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.