Brand page endpoint
The brand pages platform uses standalone URL's and path's to the ad generation endpoints. You Technical Account Manager will provide your base URL for sandbox and production environments.
Authorization
Authorization for the brand pages tool is bearer authentication. Your Technical Account Manager will be able to provide your bearer token for sandbox and production environments.
You will need to send the token in the header's as header 'Authorization: Bearer ${apiKey}
Request
To request a brand page, you will send a GET request to CitrusAd's brand-page
endpoint with the URL you are requesting for
curl --location --request GET '${URL}/api/v1/brand-page:static?url=${url}&retailer=${retailer}' \
--header 'Authorization: Bearer ${apiKey}
Sanitise URL query parameters
When requesting ads, you will need to remove any query parameters relevant to your site from the parameters sent to CitrusAd.
Inside the CitrusAd platform, we use this URL to fetch the exact page URL being requested. We will match
https\:www.retailer.com/brand/lollipops-brand
, but not if additional query parameters are specified.
Response
Depending on your brand page configuration, the segment responses will vary due to the both the segments integrated, and the brand page's template.
If you'd like to review the customisation capabilities, review the High level structure page.
Response Components
Container
The container serves the information for the entire brand page response, it also has a data array of objects, wherein the segment responses are held.
{
"id": "string",
"brandPageId": "string",
"brandPageTemplateId": "string",
"data": [
]
}
The data
array will be populated with segments, subject to the brand page's configuration, the format of segments is detailed below.
Segments
Due to the customisation possibilities in the brand pages product, the exact response you receive will be subject to your configuration. Every segment will have an id
and a name
, in addition to the segment specific properties.
Banner segments
Inside of the data
array, each segment is an object, like the below:
Banner x specific attributes in the response are example only. The values in the response are configured per template and can be customised such as
backgroundImage
,brandLogo
, or as you require.
{
"id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
"name": "primary-content",
"headingText": "Banner For MasterFoods Beef Stroganoff with Shop Now button",
"bannerText": "<strong>The Perfect Mid-Week Dinner</strong>",
"bannerTextColour": "#fff",
"heroImage": "https://storage.googleapis.com/assets-images/coke/2853856c8644",
"heroImageAltText": "<i>Picture of the Dolmio Pasta Sauce</i>",
"secondaryHeroImage": "https://assets.imageurl.io/s/85d2d333-eed5-44d7-b131-8m435c34r",
"secondaryHeroImageAltText": "Milo Logo",
"secondaryHeroMode": "landscape",
"backgroundColour": "895b5b",
"backgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada",
"backgroundImagePosition": "FILL",
"secondaryBackgroundImage": "https://assets.flavedo.io/s/9c6fa248-c5ff-4341-9833-7e2b08464ada"
}
For more information on what's possible with banner segments, see High level structure.
Content segments
Inside of the data
array, each segment is an object, like the below:
heroText
,heroTextColour
, andheroSubText
are examples for our example retailer. Each field can be named to your relevant field type such asparagraphText
.
{
"id": "26f6117c-147b-4447-86aa-992e9ddb0daa",
"name": "primary-content",
"heroText": "<i>What a way to start your week</i>",
"heroTextColour": "#000000",
"heroSubText": "<i>What a way to start your week</i>",
}
For more information on what's possible with content segments, see High level structure.
Product segments
Inside of the data
array, each segment is an object, like the below:
This response format is fixed and not subject to customisation
{
"id": "988dc393-a37a-421c-9b08-25f0f9e575f8",
"name": "my-products",
"productSelection": [
{
"catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
"position": 3,
"productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
"sellerId": "123"
},
{
"catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
"position": 2,
"productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
"sellerId": "123"
},
{
"catalogId": "1b5a2521-9e79-4b95-99b0-4deffc586d81",
"position": 1,
"productCode": "f069585b-a364-4795-9eb3-6a978c513ba4",
"sellerId": "123"
}
]
}
Product information
Much like the standard product ad integration, CitrusAd does not serve product attributes such as name, pricing, and image. This will need to be fetched from an internal product information server (or similar) on the retailer's infrastructure.
Whilst this is additional integration effort, this ensures there is no dependency on Citrus when updating and changing pricing information, as well as any automated graphics such as on special, 20% off, or similar content being dependent on CitrusAd.
For more information on what's possible with product segments, see High level structure.
Interpreting the response
In the response, each segment has an id
and a name
. These will be unique to a segment within a template. You can use these to identify different types of components, such as the type of banner, or the type of content and align it to where you inject it.
Example response
Here's an example of a brand page response for a template with one banner, one content, and one product segment would appear like.
CUSTOM_ID_N
is an example for a retailer defined ID such asparagraphText
.
Response
{
"id": "string",
"brandPageId": "string",
"brandPageTemplateId": "string",
"data": [
{
"id": "string",
"name": "string",
"CUSTOM_ID_1": "string",
"CUSTOM_ID_2": "string",
"CUSTOM_ID_3": "string"
},
{
"id": "string",
"name": "string",
"productSelection": [
{
"catalogId": "string",
"position": integer,
"productCode": "string",
"sellerId": "string"
},
{
"catalogId": "string",
"position": integer,
"productCode": "string",
"sellerId": "string"
},
{
"catalogId": "string",
"position": integer,
"productCode": "string",
"sellerId": "string"
}
]
},
{
"id": "string",
"name": "string",
"CUSTOM_TEXT_FIELD_ID_1": "VALUE",
"CUSTOM_COLOUR_FIELD_ID_1": "VALUE",
"CUSTOM_TEXT_FIELD_ID_2": "VALUE",
}
]
}
Interested to see other templates and examples? View Example brand page templates.