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:
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:
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:
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 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 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:
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. It is also important to make a check to your organic items and not show any out of stock products inside the grid
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=dspl
sessionId is needed to be included in the ad request as it will be used later in order reporting. For more information please check the "Syncing Order Data" page
