Requesting a Search Term Product Ad

Search term ads are typically the easiest to request. They 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 search term ad:

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic your_api_key_here
{
    "pageType": "Search",
    "catalogId": "$MY_CATALOG_ID",
    "productFilters": [["placement:SponsoredProducts"]],
    "searchTerm": "string",
    "maxNumberOfAds": number
}

cURL

Exemplar Context

Here is an example of a context for the pageType "Search":

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "pageType": "Search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
     "productFilters": [["placement:SponsoredProducts"]],
    "searchTerm": "Wine",
    "maxNumberOfAds": 3
}

cURL

What Happens when an Ad Is Successfully Requested

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

HTTP

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

cURL

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

In order to properly integrate the Search Term Product Listing ad request the searchTerm value shall contain a variable which is used in the search bar of the website's search page and is filled by user input.

This ensures that the ad request is being executed in every case with the value that users enters in the search bar, so that relative ads will show up.

The discount and products fields are legacy and can be ignored

The static filterplacement:SponsoredProducts 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--SKU

Filtered Searches

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 "Shiraz" Red Wines. 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.

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "pageType": "Search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
      ["RedWine", "Shiraz","placement:SponsoredProducts"]
    ],
    "maxNumberOfAds": 3
}

cURL

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

HTTP

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic 4ww25f70-b52s-40de-8f29-07b139b5cdc8
{
    "pageType": "Search",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "searchTerm": "Wine",
        "productFilters": [
       ["RedWine", "Shiraz", "Type:Australia", "delivery:DeliveryOnly", "pricerange:$25-$50","placement:SponsoredProducts"]
    ],
    "maxNumberOfAds": 5
}

cURL

What Happens when an Ad Is Successfully Requested

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

HTTP

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

cURL

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