Ads panels¶
The predefined ads panels all display ads based on the parameters and incoming arguments that are sent with a panel query.
For mandatory arguments for all panels including request URL format, see Panel query.
Ad information panel¶
The result of a query to this panel is a list of the ads that were specified in the ads argument. The ads will be ordered according to the ad keys ads argument. Ad keys that cannot be found in the data will not be listed.
The result is a list of ad elements, each specifying all presentation attributes and the list rank of that ad together with a list of products (with variants) from the included filter attribute of the ad. The number of products in the result depends on the value of the attribute live_products for each ad.
Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalized if possible.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
ads | string | A comma-separated list of ad keys of the ads that should be listed. Will return an empty result if omitted in the query. | AD1,AD3,AD2 |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Presentation attributes for ads may also be specified. Default presentation attributes are used if omitted in the query. | product_name,image_url |
variants_per_product | int | The maximum number of variants per product to include in the result. No maximum limit. | 10 |
Example panel content¶
The following example will use the panel arguments ads=beachwear to return ad information.
JSON
{
"adInformation": [
{
"name": "ad-information",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjsjOyM7IzsjOyM7IzsjOw",
"path": "/ad-information",
"description": "Displays information for one or more specified ads.",
"displayName": "Ad Information",
"attributes": {},
"resultType": "ads",
"ads": [
{
"key": "beachwear",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7IzsjOyM7IzsjOyM7",
"attributes": {
"ad_type": [
"banner"
],
"title": [
"Beachwear"
]
},
"products": [
{
"key": "0738761_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDczODc2MV9lbi1VUzswNzM4NzYxMDAyX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0738761002_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDczODc2MV9lbi1VUzswNzM4NzYxMDAyX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Silk-blend Kaftan"
]
}
},
{
"key": "0747444_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0NzQ0NF9lbi1VUzswNzQ3NDQ0MDAyX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0747444002_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0NzQ0NF9lbi1VUzswNzQ3NDQ0MDAyX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"4-in-1 Scarf"
]
}
},
{
"key": "0748030_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODAzMF9lbi1VUzswNzQ4MDMwMDAyX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0748030002_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODAzMF9lbi1VUzswNzQ4MDMwMDAyX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Satin Sarong"
]
}
},
{
"key": "0659854_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDY1OTg1NF9lbi1VUzswNjU5ODU0MDA4X2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0659854008_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDY1OTg1NF9lbi1VUzswNjU5ODU0MDA4X2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Kaftan with Tie Belt"
]
}
},
{
"key": "0524416_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDUyNDQxNl9lbi1VUzswNTI0NDE2MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0524416001_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDUyNDQxNl9lbi1VUzswNTI0NDE2MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Hooded bath sheet"
]
}
},
{
"key": "0519169_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDUxOTE2OV9lbi1VUzswNTE5MTY5MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0519169001_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDUxOTE2OV9lbi1VUzswNTE5MTY5MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Beach Towel"
]
}
},
{
"key": "0748579_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODU3OV9lbi1VUzswNzQ4NTc5MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0748579001_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODU3OV9lbi1VUzswNzQ4NTc5MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Beach Dress"
]
}
},
{
"key": "0748033_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODAzM19lbi1VUzswNzQ4MDMzMDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0748033001_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODAzM19lbi1VUzswNzQ4MDMzMDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Chiffon Beach Dress"
]
}
},
{
"key": "0748582_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODU4Ml9lbi1VUzswNzQ4NTgyMDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0748582001_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODU4Ml9lbi1VUzswNzQ4NTgyMDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Cotton Beach Dress"
]
}
},
{
"key": "0748031_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODAzMV9lbi1VUzswNzQ4MDMxMDAzX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [
{
"key": "0748031003_en-US",
"ticket": "Oy9hZC1pbmZvcm1hdGlvbjtiZWFjaHdlYXI7cHJvZHVjdF9rZXk7MDc0ODAzMV9lbi1VUzswNzQ4MDMxMDAzX2VuLVVTOztOT05FOk5PTkU7OTs",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Sarong"
]
}
}
]
}
]
}
]
}
Ads by customer panel¶
The result of a query to this panel is a list of ads based on the history of clicks, purchases, and the current cart of a visitor. If several ads are considered equally relevant to the visitor, or if no such history is present, the ads will be ranked based on their general performance, see the Top ads panel.
Personalized products
Only ads that have set the included filter attribute can be included in the personalized ranking. The filter must include products that are somehow related to the visitor's history. Ads without an included filter can be included in the backfill ranking.
Ads will only be included in the result if the following two requirements are met:
- The ad matches the
ad_filterargument. - The
timeargument is in between the values for the for thestart_timeandend_timeattributes for the ad.
The result is a list of ads, each specifying all presentation attributes and the rank of that ad, together with a list of products (with variants) from the included filter attribute of the ad. The number of products in each ad in the result depends on the value of the attribute live_products for that ad.
Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalized if possible.
The argument max_ads must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
ad_filter Guide | filter | An expression defining the set of ads to consider. Defaults to UNIVERSE if omitted in the query. | campaign_key:'summer-sale' |
max_ads | int | The number of ads to return in the result. Required argument. | 3 |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Presentation attributes for ads may also be specified. Default presentation attributes are used if omitted in the query. | product_name,image_url |
time | time_point | A time to get ads for. The time should be written in ISO 8601 format, including offset. Defaults to server time if omitted in the query. | 2017-10-14T12:00:00+01:00 |
Example panel content¶
The following example will use the panel argument max_ads=1 to return ads by customer.
JSON
{
"adsByCustomer": [
{
"name": "ads-by-customer",
"ticket": "Oy9hZHMtYnktY3VzdG9tZXI7IzsjOyM7IzsjOyM7Izs",
"path": "/ads-by-customer",
"description": "The most relevant ads for a specific customer.",
"displayName": "Ads By Customer",
"attributes": {},
"resultType": "ads",
"ads": [
{
"key": "shoes",
"ticket": "Oy9hZHMtYnktY3VzdG9tZXI7c2hvZXM7IzsjOyM7IzsjOyM7",
"attributes": {
"ad_type": [
"banner",
"small_banner"
],
"title": [
"Dress shoes"
]
},
"products": [
{
"key": "0523589_en-US",
"ticket": "Oy9hZHMtYnktY3VzdG9tZXI7c2hvZXM7cHJvZHVjdF9rZXk7MDUyMzU4OV9lbi1VUzswNTIzNTg5MDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [],
"attributes": {
"product_name": [
"Leather Shoes"
]
}
},
{
"key": "0226964_en-US",
"ticket": "Oy9hZHMtYnktY3VzdG9tZXI7c2hvZXM7cHJvZHVjdF9rZXk7MDIyNjk2NF9lbi1VUzswMjI2OTY0MDEzX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [],
"attributes": {
"product_name": [
"Derby Shoes"
]
}
},
{
"key": "0459090_en-US",
"ticket": "Oy9hZHMtYnktY3VzdG9tZXI7c2hvZXM7cHJvZHVjdF9rZXk7MDQ1OTA5MF9lbi1VUzswNDU5MDkwMDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [],
"attributes": {
"product_name": [
"Derby Shoes"
]
}
},
{
"key": "0504130_en-US",
"ticket": "Oy9hZHMtYnktY3VzdG9tZXI7c2hvZXM7cHJvZHVjdF9rZXk7MDUwNDEzMF9lbi1VUzswNTA0MTMwMDAxX2VuLVVTOztOT05FOk5PTkU7OTs",
"variants": [],
"attributes": {
"product_name": [
"Leather Derby shoes"
]
}
}
]
}
]
}
]
}
Ads by product panel¶
The result of a query to this panel is a ranked list of ads based on product keys supplied in the products argument.
Ads will only be included in the result if the following two requirements are met:
- The ad matches the
ad_filterargument. - The
timeargument is in between the values for the for thestart_timeandend_timeattributes for the ad.
The result is a list of ads, each specifying all presentation attributes and the rank of that ad, together with a list of products (with variants) from the included filter attribute of the ad.
The number of products in each ad in the result depends on the value of the attribute live_products for that ad. The rank of the ads are based on the argument products together with the included filter, the related filter, products bought by the same visitor simultaneously with the products defined in products, and the measured performance of the different ads, see the Top ads panel.
Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalized if possible.
The arguments max_ads and products must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
ad_filter Guide | filter | An expression defining the set of ads to consider. Defaults to UNIVERSE if omitted in the query. | campaign_key:'summer-sale' |
max_ads | int | The number of ads to return in the result. Required argument. | 3 |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Presentation attributes for ads may also be specified. Default presentation attributes are used if omitted in the query. | product_name,image_url |
products | string | A comma-separated list of product keys. Required argument. | P1,P2,P3 |
time | time_point | A time to get ads for. The time should be written in ISO 8601 format, including offset. Defaults to server time if omitted in the query. | 2017-10-14T12:00:00+01:00 |
variants_per_product | int | The maximum number of variants per product to include in the result. No maximum limit. | 10 |
Example panel content¶
The following example will use the panel arguments products=0633225_en-US,0659854_en-US and max_ads=1 to return ads by product.
JSON
{
"adsByProducts": [
{
"name": "ads-by-products",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7IzsjOyM7IzsjOyM7Izs",
"path": "/ads-by-products",
"description": "Ads associated with the specified products.",
"displayName": "Ads by Products",
"attributes": {},
"resultType": "ads",
"ads": [
{
"key": "beachwear",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyOyM7IzsjOyM7IzsjOw",
"attributes": {
"ad_type": [
"banner"
],
"title": [
"Beachwear"
]
},
"products": [
{
"key": "0738761_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3Mzg3NjFfZW4tVVM7MDczODc2MTAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0738761002_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3Mzg3NjFfZW4tVVM7MDczODc2MTAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Silk-blend Kaftan"
]
}
},
{
"key": "0747444_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDc0NDRfZW4tVVM7MDc0NzQ0NDAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0747444002_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDc0NDRfZW4tVVM7MDc0NzQ0NDAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"4-in-1 Scarf"
]
}
},
{
"key": "0748030_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDgwMzBfZW4tVVM7MDc0ODAzMDAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0748030002_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDgwMzBfZW4tVVM7MDc0ODAzMDAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Satin Sarong"
]
}
},
{
"key": "0659854_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA2NTk4NTRfZW4tVVM7MDY1OTg1NDAwOF9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0659854008_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA2NTk4NTRfZW4tVVM7MDY1OTg1NDAwOF9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Kaftan with Tie Belt"
]
}
},
{
"key": "0524416_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA1MjQ0MTZfZW4tVVM7MDUyNDQxNjAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0524416001_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA1MjQ0MTZfZW4tVVM7MDUyNDQxNjAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Hooded bath sheet"
]
}
},
{
"key": "0519169_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA1MTkxNjlfZW4tVVM7MDUxOTE2OTAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0519169001_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA1MTkxNjlfZW4tVVM7MDUxOTE2OTAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Beach Towel"
]
}
},
{
"key": "0748579_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDg1NzlfZW4tVVM7MDc0ODU3OTAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0748579001_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDg1NzlfZW4tVVM7MDc0ODU3OTAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Beach Dress"
]
}
},
{
"key": "0748033_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDgwMzNfZW4tVVM7MDc0ODAzMzAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0748033001_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDgwMzNfZW4tVVM7MDc0ODAzMzAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Chiffon Beach Dress"
]
}
},
{
"key": "0748582_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDg1ODJfZW4tVVM7MDc0ODU4MjAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0748582001_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDg1ODJfZW4tVVM7MDc0ODU4MjAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Cotton Beach Dress"
]
}
},
{
"key": "0748031_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDgwMzFfZW4tVVM7MDc0ODAzMTAwM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0748031003_en-US",
"ticket": "Oy9hZHMtYnktcHJvZHVjdHM7YmVhY2h3ZWFyO3Byb2R1Y3Rfa2V5OzA3NDgwMzFfZW4tVVM7MDc0ODAzMTAwM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Sarong"
]
}
}
]
}
]
}
]
}
Ads by search panel¶
The result of a query to this panel is a ranked list of ads relevant in combination with a specific search result.
Ads will only be included in the result if the following two requirements are met:
- The ad matches the
ad_filterargument. - The
timeargument is in between the values for the for thestart_timeandend_timeattributes for the ad.
The result is a list of ads, each specifying all presentation attributes and the rank of that ad, together with a list of products (with variants) from the included filter attribute of the ad.
The number of products in each ad in the result depends on the value of the attribute live_products for that ad. The rank of the ads are based on the arguments filter, facets, selected_category, search_attributes, and search_phrase together with the included filter, the related filter, and the measured performance of the different ads, see the Top ads panel.
Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalized if possible.
The argument max_ads must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
ad_filter Guide | filter | An expression defining the set of ads to consider. Defaults to UNIVERSE if omitted in the query. | campaign_key:'summer-sale' |
facets Guide | facets | A pipe-separated list of selected facet values used as facets argument for the corresponding Search hits panel. Ignored with no impact on the result if omitted in the query. | color:red|blue,size:6 |
filter Guide | filter | The filter expression used as filter argument for the corresponding Search hits panel. Defaults to UNIVERSE if omitted in the query. | color:'red' OR color:'blue' AND in_stock:'true' |
max_ads | int | The number of ads to return in the result. Required argument. | 3 |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Presentation attributes for ads may also be specified. Default presentation attributes are used if omitted in the query. | product_name,image_url |
search_attributes Guide | string | A comma-separated list of the product attributes used as search_attributes argument for the corresponding Search hits panel. Rank order will not be based on search if omitted in the query. | name,brand |
search_phrase | string | The search phrase used as search_phrase argument for the corresponding Search hits panel. Rank order will not be based on search if omitted in the query. | red dress |
time | time_point | A time to get ads for. The time should be written in ISO 8601 format, including offset. Defaults to server time if omitted in the query. | 2017-10-14T12:00:00+01:00 |
variants_per_product | int | The maximum number of variants per product to include in the result. No maximum limit. | 10 |
selected_category Guide | category | A selected category on the form: <tree name>:'<category key>'. Only products from this category and its sub-categories will be included in the result. Products from all categories are considered if omitted in the query. | category:'Ladies' |
Example panel content¶
The following example will use the panel arguments search_attributes=product_name, search_phrase=bikini, and max_ads=1 to return ads by search.
JSON
{
"adsBySearch": [
{
"name": "ads-by-search",
"ticket": "Oy9hZHMtYnktc2VhcmNoOyM7IzsjOyM7IzsjOyM7",
"path": "/ads-by-search",
"description": "Ads associated with the specified search phrase.",
"displayName": "Ads by Search",
"attributes": {},
"resultType": "ads",
"ads": [
{
"key": "stay_fit",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0OyM7IzsjOyM7IzsjOw",
"attributes": {
"ad_type": [
"banner"
],
"title": [
"Stay fit"
]
},
"products": [
{
"key": "0399248_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzAzOTkyNDhfZW4tVVM7MDM5OTI0ODAwM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0399248003_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzAzOTkyNDhfZW4tVVM7MDM5OTI0ODAwM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Sports Bra Medium support"
]
}
},
{
"key": "0493420_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0OTM0MjBfZW4tVVM7MDQ5MzQyMDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0493420001_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0OTM0MjBfZW4tVVM7MDQ5MzQyMDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Sports Bra Medium support"
]
}
},
{
"key": "0645970_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA2NDU5NzBfZW4tVVM7MDY0NTk3MDAwM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0645970003_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA2NDU5NzBfZW4tVVM7MDY0NTk3MDAwM19lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Triangle Bikini Top"
]
}
},
{
"key": "0413944_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0MTM5NDRfZW4tVVM7MDQxMzk0NDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0413944001_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0MTM5NDRfZW4tVVM7MDQxMzk0NDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Short Running Tights"
]
}
},
{
"key": "0405712_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0MDU3MTJfZW4tVVM7MDQwNTcxMjAwNF9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0405712004_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0MDU3MTJfZW4tVVM7MDQwNTcxMjAwNF9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Padded Vest with Hood"
]
}
},
{
"key": "0395924_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzAzOTU5MjRfZW4tVVM7MDM5NTkyNDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0395924001_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzAzOTU5MjRfZW4tVVM7MDM5NTkyNDAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"3/4-length sports tights"
]
}
},
{
"key": "0701354_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA3MDEzNTRfZW4tVVM7MDcwMTM1NDAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0701354002_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA3MDEzNTRfZW4tVVM7MDcwMTM1NDAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Padded Outdoor Vest"
]
}
},
{
"key": "0498621_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0OTg2MjFfZW4tVVM7MDQ5ODYyMTAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0498621002_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0OTg2MjFfZW4tVVM7MDQ5ODYyMTAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Padded Outdoor Vest"
]
}
},
{
"key": "0391449_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzAzOTE0NDlfZW4tVVM7MDM5MTQ0OTAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0391449002_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzAzOTE0NDlfZW4tVVM7MDM5MTQ0OTAwMl9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Sports Bra Medium support"
]
}
},
{
"key": "0439326_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0MzkzMjZfZW4tVVM7MDQzOTMyNjAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"variants": [
{
"key": "0439326001_en-US",
"ticket": "Oy9hZHMtYnktc2VhcmNoO3N0YXlfZml0O3Byb2R1Y3Rfa2V5OzA0MzkzMjZfZW4tVVM7MDQzOTMyNjAwMV9lbi1VUzs7Tk9ORTpOT05FOzk7",
"attributes": {}
}
],
"attributes": {
"product_name": [
"Sports Tights"
]
}
}
]
}
]
}
]
}
Top ads panel¶
The result of a query to this panel is a list of the ads that are performing best at the moment according to Voyado Elevate. The performance of an ad is based on how much revenue an ad has generated, how often the ad has been displayed, and the click-through-rate of the ad.
Ads will only be included in the result if the following two requirements are met:
- The ad matches the
ad_filterargument. - The
timeargument is in between the values for the for thestart_timeandend_timeattributes for the ad.
The result is a list of ads, each specifying all presentation attributes and the rank of that ad, together with a list of products (with variants) from the included filter attribute of the ad.
The number of products in each ad in the result depends on the value of the attribute live_products for that ad. Products in a live ad will be internally ranked based on the active exposure strategy as set in the Business app, and will be personalized if possible.
The argument max_ads must be included in a query to this panel.
Panel arguments¶
| Name | Type | Description | Example |
|---|---|---|---|
ad_filter Guide | filter | An expression defining the set of ads to consider. Defaults to UNIVERSE if omitted in the query. | campaign_key:'summer-sale' |
max_ads | int | The number of ads to return in the result. Required argument. | 3 |
presentation_attributes Guide | string | A comma-separated list of the attributes in the product data to present. Presentation attributes for ads may also be specified. Default presentation attributes are used if omitted in the query. | product_name,image_url |
time | time_point | A time to get ads for. The time should be written in ISO 8601 format, including offset. Defaults to server time if omitted by the query. | 2017-10-14T12:00:00+01:00 |
Example panel content¶
The following example will use the panel argument max_ads=1 to return top ads.
JSON
{
"topAds": [
{
"name": "top-ads",
"ticket": "Oy90b3AtYWRzOyM7IzsjOyM7IzsjOyM7",
"path": "/top-ads",
"description": "Lists the top performing ads right now.",
"displayName": "Top Ads",
"attributes": {},
"resultType": "ads",
"ads": [
{
"key": "beachwear",
"ticket": "Oy90b3AtYWRzO2JlYWNod2VhcjsjOyM7IzsjOyM7Izs",
"attributes": {
"ad_type": [
"banner"
],
"title": [
"Beachwear"
]
},
"products": [
{
"key": "0738761_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzM4NzYxX2VuLVVTOzA3Mzg3NjEwMDJfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Silk-blend Kaftan"
]
}
},
{
"key": "0747444_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzQ3NDQ0X2VuLVVTOzA3NDc0NDQwMDJfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"4-in-1 Scarf"
]
}
},
{
"key": "0748030_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzQ4MDMwX2VuLVVTOzA3NDgwMzAwMDJfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Satin Sarong"
]
}
},
{
"key": "0659854_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNjU5ODU0X2VuLVVTOzA2NTk4NTQwMDhfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Kaftan with Tie Belt"
]
}
},
{
"key": "0524416_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNTI0NDE2X2VuLVVTOzA1MjQ0MTYwMDFfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Hooded bath sheet"
]
}
},
{
"key": "0519169_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNTE5MTY5X2VuLVVTOzA1MTkxNjkwMDFfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Beach Towel"
]
}
},
{
"key": "0748579_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzQ4NTc5X2VuLVVTOzA3NDg1NzkwMDFfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Beach Dress"
]
}
},
{
"key": "0748033_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzQ4MDMzX2VuLVVTOzA3NDgwMzMwMDFfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Chiffon Beach Dress"
]
}
},
{
"key": "0748582_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzQ4NTgyX2VuLVVTOzA3NDg1ODIwMDFfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Cotton Beach Dress"
]
}
},
{
"key": "0748031_en-US",
"ticket": "Oy90b3AtYWRzO2JlYWNod2Vhcjtwcm9kdWN0X2tleTswNzQ4MDMxX2VuLVVTOzA3NDgwMzEwMDNfZW4tVVM7O05PTkU6Tk9ORTs5Ow",
"variants": [],
"attributes": {
"product_name": [
"Sarong"
]
}
}
]
}
]
}
]
}