Requesting a Discovery Product Ad
Discovery ads require a simple "context' to be sent to Project Agora Commerce. A "context" is a bit of code that defines the conditions under which a product is shown to a customer.
All Discovery ads use the following static filters:
"placement": "Discovery-Home"for homepage"placement": "Discovery-Category"for category/subcategory pages"placement": "Discovery-Search"for search page"placement": "Discovery-Product"for product detail page"placement": "Discovery-Checkout"for checkout page
The placement value used for Discovery ads is "discoveryproducts"
Homepage: Minimum Viable Context
Below are the minimum values needed to generate a Discovery homepage ad:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
"catalogId": "$MY_CATALOG_ID",
"productFilters": [
["placement:Discovery-Home"]
],
"placement": "discoveryproducts",
"maxNumberOfAds": number,
"sessionId": "string"
}Homepage: Minimum Exemplar Context
Here is an example of a context for requesting a Discovery homepage ad:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["placement:Discovery-Home"]
],
"placement": "discoveryproducts",
"maxNumberOfAds": 3,
"sessionId": "23dn3923-323d"
}When you successfully request an ad, you receive the following object:
HTTP/2 200
{
"ads": [
{
"id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
"gtin": "catpref--2899049P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516943179Z"
}
],
"banners": [],
"products": []
}Search Page and Checkout/Cart Page
For the "Checkout/Cart page" and the "Search page" the request and responses are exactly the same as in the case of Homepage Discovery Sponsored Listings as shown above with the only difference that the productFilters attribute changes to "placement": "Discovery-Checkout" and "placement": "Discovery-Search" respectively.
The placement attribute is the same for all Discovery ad types: "discoveryproducts"
Category Page
In the case of the Category/Subcategory pages there are two ad requests that should take place and the results that will be displayed in the page is the merge of those two requests.
1st Ad request
Specifically the first ad request should be executed like below:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
"catalogId": "$MY_CATALOG_ID",
"productFilters": [
["taxonomy:string","placement:Discovery-Category"]
],
"placement": "discoveryproducts",
"maxNumberOfAds": number,
"sessionId": "23dn3923-323d"
} The string parameter inside the productFilters attribute shall contain only the first-level parent category of the category path in which the specific category of the category page belongs and the static filter placement:Discovery-Category.
For example the ad request inside the category Cream which has the below category path: Woman>Face>Cream (the first parent category is "Woman") should be like this:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
"catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
"productFilters": [
["taxonomy:Woman","placement:Discovery-Category"]
],
"placement": "discoveryproducts",
"maxNumberOfAds": 3,
"sessionId": "23dn3923-323d"
}
When you successfully request an ad, you receive the following object:
HTTP/2 200
{
"ads": [
{
"id": "display_SEY2W7-VZzspoirbw4ANs-r-w6YyODk5MDQ5UA==",
"gtin": "catpref--2899049P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516943179Z"
},
{
"id": "display_-hPcUdg5KUQ2sxhE6r0XVN3-iLY5ODkxNTY2UA==",
"gtin": "catpref--9891566P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516948637Z"
},
{
"id": "display_aGULlK-E_yEiVZ_S_jH9qsH-KhYyOTAyNjIwUA==",
"gtin": "catpref--2902620P",
"discount": {
"amount": 0,
"minPrice": 0,
"maxPerCustomer": 0
},
"expiry": "2019-12-10T01:46:07.516953955Z"
}
],
"banners": [],
"products": []
}2nd Ad request
The second ad request should be executed like below:
POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
"catalogId": "$MY_CATALOG_ID",
"productFilters": [
["placement:Discovery-Category"]
],
"placement": "discoveryproducts",
"maxNumberOfAds": number,
"sessionId": "23dn3923-323d"
} This request as seen above will have only the placementdiscovery-category as in the case of the homepage, checkout and search page DSPL requests (with their respective placements).
Merging results
The final part is to merge the above responses in order to populate the Discovery Sponsored Product Listings positions inside the Discovery grid.
Specifically all the positions inside the Discovery Grid should be populated with the ad responses that you have get from the 1st ad request .
In case there are no ad responses for the 1st ad request, the positions of the Discovery Grid shall be populated with the responses from the 2nd ad request.
In addition if there are not enough ad responses to fill all the agreed positions( from the ad proposal) in the Discovery Grid from the 1st ad request then the rest of the positions will have to be populated with the responses from the 2nd ad request.
Please note that in case there are duplicate ad responses from the 1st and 2nd ad requests (as the 2nd request is more generic and may contain also items which are included in the 1st one too) we want to serve them only once.
Example
For example in case in the category page according to the ad proposal 8 positions should be filled with DSPL ads in the Discovery Grid, then the 1st ad request should be made and the 2nd one with maxNumberOfads:8
In case the 1st ad response will return only 3 items, then the first three items of the Discovery Grid shall be populated with the 3 items of the 1st ad response while the remaining 5 with the items returned as a response from the 2nd ad response
Product details Page
In the case of the Product details pages there are two ad requests that should take place and the results that will be displayed in the page is the merge of those two requests.
The process is exactly the same as described above in the Category/Subcategory with the only change of the productFilters sttic filter used in the request which will now be: "placement": "Discovery-Product"
Keep in mind that in the 1st ad request, the first level parent category of the category path in which this product belongs should be included in the request.
Position Attribute in response
When you receive in the response of one DSPL request the attribute position, please note that this declares the order in which this DSPL ad should be placed in the DSPL grid.
For example if in the response you get the below:
"position": 1
then you shall serve the ad coming from this response in the first position of the DSPL items.
No DSPL responses case
An important note for the cases there are no Discovery Product Listings items in response of the DSPL ad requests:
Enabling Google Analytics tracking for DSPL items
In order to start having recordings in your Google Analytics account for the DSPL items you will have to add the following utm parameter in the landing url of a DSPL item:
utm_source=pacommerce&utm_medium=dsplLast updated