Skip to content

Working with Ads

Ads is one of the main data entity types in Apptus eSales. Ads are most often used as banners to promote campaigns and product offers.

There are two types of ads: static ads and live ads. The type of ad is determined by the value of the live_products attribute of the ad. A static ad has no live_products and is presented as a banner that most often lead to the landing page of a campaign.

A live ad includes a number of products in the ad. The included attribute defines the set of products and variants to be used with the ad. The products in a live ad will be internally ranked based on sales and sorted by the personal sort order.

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 behaviour. Ad attributes can not be configured for sorting.

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. The included filter is used by the ad ranking algorithms. 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 related to the ad. The related filter is used by the ad ranking algorithms. 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 products in the included and related filter attributes are used by the ad ranking algorithms for the Ads by search panel and the Ads by products panel. What ad is shown is based on the products that are defined by both the included and related filter attributes, as well as what context the products are present in, i.e. in a search result for Ads by search or a product set for Ads by product.

Ads whose products (as defined by the included and related filters) have a larger overlap with the context will receive a higher rank. An ad that has products that overlap more with the context ranks higher than an ad with products that overlap less with the context.

A live ad select products to return primarily based on the included filter. The context the ad is used in and what that arguments are supplied to the panel returning the ad also affect product selection. For example, when used in an Ads by search panel, the search_phrase argument affects context and the returned products. Products returned for a live ad are sorted by the personal sort order.

The most common use case for the included products filter is when the ad is a static ad (the live_products attribute value is 0), but there is a need for products to affect the ad ranking without the products being shown.

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>

Pre-defined ads panels

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

×