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 thepageType "Category" and product filters:
productFilters: "placement:Discovery-Home" for homepage
productFilters: "placement:Discovery-Category" for category/subcategory pages
productFilters: "placement:Discovery-Search" for search page
productFilters: "placement:Discovery-Product" for product detail page
productFilters: "placement:Discovery-Checkout" for checkout page
Homepage: Minimum Viable Context
Below are the minimum values needed to generate a Discovery homepage ad:
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.
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:
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.
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:
This request as seen above will have only the static filter placement:Discovery-Category as in the case of the homepage, checkout and search page DSPL requests.
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 examplein 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 static filter 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.
No DSPL responses case
An important note for the cases there are no Discovery Product Listings items in response of the DSPL ad requests:
For the cases when there is no discovery sponsored listing ad to serve (because of no active campaigns), you will have to fill the positions in the discovery grid with organic items and remove the sponsored labeling.
