Requesting brand pages

Requesting ads

When requesting for a brand page you will make two requests, one to the /generate endpoint, and one to /bannerx. This is how you will fetch the content required for you to render the page.

When requesting a brand page, you will specify a placement of "brandpage". In addition, in the productFilters, you will specify a filter of "brandpage:URL_SUFFIX". This filter is the individual identifier of the brand page. This URL is configured in the CitrusAd portal by the user, and will align with the real URL of their site.

756756

When integrating brand pages, you should automate the requesting of ads to CitrusAd via the format of your website. In the screenshot above, we have retailer.com/brand/[URL_SUFFIX]. You should automate the requesting of ads when a customer reaches your /brand/? url to request ads for anything following the /. /brand/ is only intended as an example subject to each individual retailer's site.

๐Ÿ“˜

If a brand page campaign isnโ€™t set up for your supplied suffix, you will receive a 200 and not receive the content in the response - this is expected behaviour. If you believe you should be receiving content, check that a valid and active brand page campaign is configured.

Product ads

You will send a request to the /generate endpoint, which will retrieve your page's product ads.

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "brandpage",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 15               
}

You will receive a response that mirrors the typical product ad response.

Banner x ads

You will send a request to the /bannerx endpoint, which will retrieve your page's banner x ad.

POST $BASE_URL/v1/ads/bannerx HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "brandpage",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "options": {
                             "filterMode": "AndOr"
                             },
    "contentStandardId": "fec2ab89-7a29-42b5-b58a-5675688b52d9",
    "bannerSlotIds": [
    {
      "slotId": "<SLOT_ID>",
      "maxNumberOfAds": 1
    }
    ]
}

You will receive a response that mirrors the typical banner x ad response.

Request enhancements

We advise you to consider the below enhancements to improve your user experience.

Filtering by location

If you are synchronising location filters in your catalog, you can extend your context to provide the customer's store location in the productFilters, like the example below:

POST $BASE_URL/v1/ads/generate HTTP/1.1
accept: application/json
content-type: application/json
Authorization: Basic <API_KEY>
{
    "customerId": "wertg5432a",
    "sessionId": "ec9-4e07-881d-3e9", 
    "placement": "brandpage",
    "catalogId": "628dbe95-2ec9-4e07-881d-3e9f92ab2e0b",
    "productFilters": [
         ["category:Cupboard"],["dietary:Gluten-free"],["location:Westenbury"]
    ],
    "options": {
                         "filterMode": "AndOr"
                             },
    "maxNumberOfAds": 15               
}