Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Banner represents a single banner that can be displayed on an end-user facing web/app page. Banners can be either static (with fixed content) or dynamic (content derived from parameters).

project_id
string
required
name
string
required

A name for visual identification within the management UI. Does not appear towards end users.

banner_type
enum<string>
required

The type of banner that determines how content is sourced.

Available options:
BANNER_TYPE_UNSPECIFIED,
BANNER_TYPE_DEFAULT,
BANNER_TYPE_EVENT,
BANNER_TYPE_CREATIVE_WORK,
BANNER_TYPE_ENTITY
content_id
string

Single banner - it is connected to a single content item (either an event, entity, or creative work).

Important: at most one of content_id, dynamic_target may be set per request.

dynamic_target
object

Dynamic banner - it is not connected to a single content item, but derives its content from a set of filters.

Important: at most one of content_id, dynamic_target may be set per request.

background_assets
object[]

A list of assets to be shown in the background (as the main banner image). Each asset is meant for a different screen size, determined by its breakpoint_width property. E.g. if you only want a single asset for this banner, you can set breakpoint_width to 0. E.g. if you want to show a different asset for mobile vs desktop, you can set breakpoint_width to 0 for the mobile asset and 1024 for the desktop asset.

template
object

The content needed by the template that should be rendered.

environments
string[]

The environments in which this banner should be rendered. The available options are: "web", "ios", "android", "tvos", "lg", "samsung", "androidtv"

Important: this should always be a subset of the environments configured at the page-component level for the associated banner collection. For example, if a page component is configured to be "ios" only, but a banner inside that component has "web" only, that banner will never be shown.

css_classes
string[]

Web only. A list of CSS classes that should be added to the banner's container element. This can be used to apply custom styling to the banner.

visibility
enum<string>
Available options:
VISIBILITY_UNSPECIFIED,
VISIBILITY_PUBLISHED,
VISIBILITY_UNLISTED,
VISIBILITY_HIDDEN
overrides
object

A map of overrides for the banner. This is useful for scenarios where some subset of Banner instantiations should have different properties. The key is a content_id (either event ID, entity ID, or creative work ID), the value is the override to apply when that content is in context.

Note that a hit on a banner override will entirely replace the banner template and its content; it will not merge with the base banner.

geo_applicability_exempt
object

Viewers from these countries will not have this video ad shown.

Important: at most one of geo_applicability_exempt, geo_applicability_apply may be set per request.

geo_applicability_apply
object

Viewers from these countries will have this video ad shown.

Important: at most one of geo_applicability_exempt, geo_applicability_apply may be set per request.

destination_url
object

Optional. A map of localized destination URLs. The key is the language code (ISO 639 - set 1), e.g. "en", "de", "fr", etc. If you want to localize the URL for different regions of the same language, you can add the country code (ISO 3166-1 alpha-2), e.g. "en-US", "en-GB", etc. Note that this is not necessary for banners of type BANNER_TYPE_EVENT, BANNER_TYPE_CREATIVE_WORK, or BANNER_TYPE_ENTITY, as the destination URL will be derived from the connected content item in those cases.

is_preview
boolean

Indicates that this banner is a preview banner. Preview banner are not shown to end users, but can be used for testing and previewing changes. When you wish to deploy a preview banner to production (your main platform for end users), you should use CloneBanner.

source_banner_id
string

The banner ID of the production page that this preview banner is based on. This field is only relevant when "is_preview" is true. It will be set automatically when using the "CloneBanner" API method.

is_fallback
boolean

Indicates that this banner is a fallback banner. Fallback banners are shown only when there are no other banners that can be shown based on their targeting criteria in connected_content. If multiple fallback banners exist in a banner collection, only the first one in a banner collection will be used.

Response

OK

banner
object

Banner represents a single banner that can be displayed on an end-user facing web/app page. Banners can be either static (with fixed content) or dynamic (content derived from parameters).