Skip to content

Working with ads

Ads is one of the main data entity types in Voyado Elevate 3. Ads are used to add banners, content blocks, and static page links to pages in addition to products that is relevant in the context. Context can be different for each visitor on a site.

Ads can be used as a static ad where static data is used. Ads can also be used as a live ad where static data is used together with a number of products connected to the ad, live products. Which products a visitor is shown in the ad depends on the visitor and how popular the products in the ad are. 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.

Attributes

All ads have a set of standard attributes for basic functionality such as included products and start and end times. Additional attributes for presentation, search, and filtering can be defined to support business objectives and desired behavior. Ad attributes can not be configured for sorting. Attribute configuration is done in the Voyado Elevate manager.

Standard attributes

Name Type Description Example
ad_key string A unique key for the ad.
Required attribute. 		summer-sale-rocknroll-2017
campaign_key string A unique string for a campaign. Used to connect multiple ads to a campaign. summer-sale-2017
end_time time_point The end time of the ad. The time should be written in ISO 8601 format, including offset. Defaults to end of time (ad will never end) if omitted. 2017-08-31T12:00:00+01:00
included
Guide		 filter An expression limiting the considered product and variant set. These products are used to decide how relevant the ad is in its current context (ads by search, ads by product, ads by customer) as well as the selection of products for live products. Defaults to UNIVERSE if omitted. category:'cd' AND genre:'rocknroll'
live_products int The number of products to return when using live ads. Defaults to 0 if omitted. 5
locale string The locale of the ad. sv-SE
related
Guide		 filter An expression limiting the considered product and variant set. These products are used to decide how relevant the ad is in its current context (ads by search, ads by product). The products are not part of the ad as live products. category:'cd' AND genre:'heavymetal'
start_time time_point The start time of the ad. The time should be written in ISO 8601 format, including offset. Defaults to beginning of time (ad has always been active) if omitted. 2017-06-01T12:00:00+01:00

Common additional attributes

User-defined attribute limitations

The name for a user-defined attribute can not be more than 2 000 characters long. The value for a user-defined attribute can not be more than 2 000 000 characters long.

Name Type Description Example
ad_category string A string describing a group of ads. The attribute is commonly used to group ads based on place of use on a site, such as a start page or a shopping cart page. music dvds
campaign_url string The target URL for an ad that is not part of a live ad. /campaigns/summer-sale-2017/music/
format string A string describing the physical properties of an ad and what area of a page it may be used for. fullwidth
image_url string The image URL for an ad that is not a part of a live ad. /images/campaigns/summer-sale-rocknroll-2017.jpg
tags string A comma-separated list of tags describing the ad. dvd,music
title string A string with the presentation title of the ad. Rock n' roll DVDs

The included and related products in an ad have one main purpose - to rank how relevant an ad is. The included products have an additional purpose - to deliver the live products that are to be shown in/returned with the ad.

Ads whose products, as defined by the included and related filter attributes, have a larger overlap with the current context ranks higher than an ad with products that overlap less with the context. Context only applies for the Ads by search panel and Ads by product panel.

An ad with live products, as in the live_products attribute is greater than 0, selects products based on the included filter. The context the ad is used in and what arguments that are supplied to the panel returning the ad will also affect the ad selection. For example, when used in an Ads by search panel, the search_phrase argument affects context and the returned ads. 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.

Example with live products

A site will run a campaign for trousers from brand A and will use ads to promote these trousers. The ad setup for the campaign will show 3 live products in the ad with the best matching products. When setting up this ad, all trousers from brand A are set in the included filter. This selection will both give which products to select live products from and also help with when the ad should be visible on the site.

When a visitor browse or search for products where the included products are returned in a result this ad can come up, depending on the popularity and relevance of other ads. To further increase the visibility of the ad, all trousers from all other brands are set in the related filter. This will increase the number of contexts where this ad fit and can be visible, resulting in that the ad can be shown when other trousers are shown.

Ad configuration

Attribute Value
live_products 3
included category:'trousers' AND brand: 'A'
related category:'trousers' AND NOT brand: 'A'

Example without live products

A site selling shoes would like to show relevant content together with the products shown on the site. The content will not promote products and instead give relevant info related to the products, like care instructions for the material of the product. In this case it does not make sense to show products in the ad.

For each type of care instruction an ad is created where the included products are all products that are relevant for that specific care instruction. The live_product attribute is set to 0 to not return any products. It is also possible to add keywords to the ad to give the possibility to search for the care instruction directly in the search field.

Ad configuration

Attribute Value
live_products 0
included category:'shoes' AND material:'leather'
tags care

Imports and data structure

Ads are imported as UTF-8 formatted XML through the RESTful API. The data structure of imports of ads vary depending on the import method.

Full import example 
<?xml version='1.0' encoding='UTF-8'?>
<operations>
    <clear>
        <ad/>
    </clear>
    <add>
        <ad>
            <ad_key>ad2018011420180214</ad_key>
            <start_time>2018-01-14T08:00:00+01:00</start_time>
            <end_time>2018-02-15T24:00:00+01:00</end_time>
            <included>category:'cd' AND genre:'soul' AND genre:'rnb'</included>
            <related>category:'cd' AND genre:'jazz'</related>
            <title>Valentines day music offers</title>
            <locale>en-GB</locale>
            <tags>cd,music</tags>
            <live_products>3</live_products>
            <campaign_key>valentines2018</campaign_key>
            <campaign_url>/campaigns/valentines-2018/music/</campaign_url>
            <format>fullwidth</format>
            <image_url>/images/ads/ad2018011420180214.jpg</image_url>
            <ad_category>frontpage</ad_category>
        </ad>
        <ad>
            <ad_key>ad2018062520180625</ad_key>
            <start_time>2018-06-25T08:00:00+01:00</start_time>
            <end_time>2018-07-25T24:00:00+01:00</end_time>
            <included>category:'cd'</included>
            <related>UNIVERSE</related>
            <title>Summer CD Sale</title>
            <locale>en-GB</locale>
            <tags>cd,music</tags>
            <live_products>3</live_products>
            <campaign_key>summersalemusic2018</campaign_key>
            <campaign_url>/campaigns/summer-2018/music/</campaign_url>
            <format>fullheight</format>
            <image_url>/images/ads/ad2018062520180625.jpg</image_url>
            <ad_category>frontpage</ad_category>
        </ad>
    </add>
</operations>

Predefined ads panels

The predefined ads panels all display ads based on the parameters and incoming arguments that are sent with a panel query.

×
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