Requesting a Category Product Ad

Page Category 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.

Minimum Viable Context:

Below are the minimum values needed to generate a category 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": [
      ["taxonomy:string"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": number,
    "sessionId": "string"
}

Exemplar Context

Here is an example of a context:

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:computers"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

What Happens when an Ad Is Successfully Requested

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": []
}

No customer information or cart items are necessary in this simple context. The simple context consists only of necessary filters.

In each category page the SPL requests should include in one filter the whole category path leading to this page as described also in the taxonomy attribute of the product feed. For instance if category C belongs to category B and B belongs to A, the category path is A > B > C, then the SPL request for the page C should have this filtering:

"productFilters": [
      ["taxonomy:A>B>C"]
    ],

The SPL for category page B would be:

"productFilters": [
      ["taxonomy:A>B"]
    ],

The discount and products fields are legacy and can be ignored

The placementsponsoredproducts should be included in all SPL requests

In gtin field of the above responses you will get the pa_id as in the product feed for the product to be displayed.

Reminder: the pa_id is the concatenation of the catalog prefix and each product SKU, so to identify which SKU to display on your side you may need to remove the catalog prefix and the symbols "--"

pa_id= catprefix

Position Attribute in response

When you receive in the response of one SPL request the attribute position, please note that this declares the order in which this SPL ad should be placed in the SPL 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 SPL items.

Filtered Browsing

When a user filters browsing deeper into subcategories, you are able to serve ads relevant to their filters using more productFilters in the context.

In this example, the user has navigated to the Computers category, and browsed further to "Laptops" and "Windows" categories. This is a new request and considered by Project Agora Commerce 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.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
      ["taxonomy:computers>Laptops>Windows"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

As your customers filter deeper in their searches, your request will include more product filters

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:computers>Laptops>Windows", "delivery:DeliveryOnly", "pricerange:$250-$500"]
    ],
    "placement": "sponsoredproducts",
    "maxNumberOfAds": 3,
    "sessionId": "23dn3923-323d"
}

What Happens when an Ad Is Successfully Requested

When you successfully request an ad, you receive the following object:

HTTP/2 200
{
    "ads": [
       {
            "id": "display_ZFwfo0Mi2AhFBxUBHpXnICvV2j8zNTcxNzExUA==",
            "gtin": "catpref--3571711P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936105529Z"
        },
        {
            "id": "display_VpFfnPOnaG4MZh43ckQjufmGAzwzNTcxOTkyUA==",
            "gtin": "catpref--3571992P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936111787Z"
        },
        {
            "id": "display_vRHRnkTXbbssVwiem8jDrmOp2FM2Mzg3NTkyUA==",
            "gtin": "catpref--6387592P",
            "discount": {
                "amount": 0,
                "minPrice": 0,
                "maxPerCustomer": 0
            },
            "expiry": "2019-12-10T01:51:07.936117921Z"
        },
    ],
    "banners": [],
    "products": []
}

The most common case of a filtered request concerns the brand filter.

Specifically when a user navigates to a category page and chooses a brand filter (usually from a left menu), then a new ad request shall take place as above while the SPL items from the category request before choosing the filter shall be hidden.

For example in case the user navigates to the category Computers>Laptops then the new ad request after the user chooses the filter Topbrand shall have the following productFilters:

"productFilters": [
      ["taxonomy:Computers>Laptops",brand:Topbrand"]
    ],

Brand page Request

Kindly note that the process for requesting an SPL ad inside a brand/vendor page is exactly the same except from the Product Filtering which changes like this:

"productFilters": [
      ["brand:brand_name","placement:Brand-Page"]
    ],

where brand_name is the exact name of the brand as indicated in the product feed.

In case there is a category filtering menu on a brand page, then when a user chooses a certain category as a filter, the respective category shall be added in the ad request.

For example if the category "Face" which is a subcategory of "Woman" is chosen by a user then the ad request in this brand page will contain the following product filter:

"productFilters": [
      ["brand:brand_name","taxonomy:Woman>Face","placement:Brand-Page"]
    ],

Multiple Brand Filters in Category Pages

When a brand menu is available as a filtering option in the category pages of the website, then the SPL requests shall respond according to the user input (the option that he will choose from the menu) and the rendering of the SPL grid should be handled by new SPL requests.

If multiple options are selected from the menu then the request shall be handled as in the below example.

In this example the user is navigating in the category page Woman > Face and he chooses as a filter the brands "brand1" and "brand2"

"productFilters": [
      ["brand:brand1","taxonomy:Woman>Face","placement:Brand-Page"],["brand:brand2","taxonomy:Woman>Face","placement:Brand-Page"]
    ],

Please note that two attributes separated with the "," character inside brackets [], are handled with an OR logic while the character "," outside the brackets, is connected among different objects with the AND logic.

In the above example, the request translates as: render an SPL item belonging in the category Woman > Face and with brand1 OR render an SPL item belonging in the category Woman > Face and with brand2

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

If you are unsure of the strings displayed on this page. Take a look at the Reference page.

SPL items when Sorting is used

Please note that when the user chooses the option to sort the products on the website, the page should be rendered without showing any SPL item so that there won't be any disruption on the sorting functionality and user experience

Enabling Google Analytics tracking for SPL items

In order to start having recordings in your Google Analytics account for the SPL items you will have to add the following utm parameter in the landing url of an SPL item:

utm_source=pacommerce&utm_medium=spl

PreviousProduct Listing Ad Integration GuideNextRequesting a Search Term Product Ad

Last updated