Skip to content

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:

  1. The ad matches the ad_filter argument.
  2. The time argument is in between the values for the for the start_time and end_time attributes 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:

  1. The ad matches the ad_filter argument.
  2. The time argument is in between the values for the for the start_time and end_time attributes 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:

  1. The ad matches the ad_filter argument.
  2. The time argument is in between the values for the for the start_time and end_time attributes 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:

  1. The ad matches the ad_filter argument.
  2. The time argument is in between the values for the for the start_time and end_time attributes 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"
                                  ]
                              }
                          }
                      ]
                  }
              ]
          }
      ]
  }
×
Copyright

This online publication is intellectual property of Voyado Lund AB. Its contents can be duplicated in part or whole, provided that a copyright label is visibly located on each copy and the copy is used in conjunction with the product described within this document.

All information found in these documents has been compiled with utmost attention to detail. However, this does not guarantee complete accuracy. Neither Voyado Lund AB nor the authors shall be held liable for possible errors or the consequences thereof.

Software and hardware descriptions cited in these documents might be registered trademarks. All trade names are subject to copyright restrictions and may be registered trademarks. Voyado Lund AB essentially adheres to the manufacturer’s spelling. Names of products and trademarks appearing in this document, with or without specific notation, are likewise subject to trademark and trade protection laws and may thus fall under copyright restrictions.

CLOSE