Skip to content

Latest commit

 

History

History
5108 lines (4629 loc) · 191 KB

AdCOM v1.0 FINAL.md

File metadata and controls

5108 lines (4629 loc) · 191 KB

IAB Tech Lab

AdCOM Specification v1.0

March 2022

About the IAB Technology Lab

Established in 2014, the IAB Technology Laboratory (Tech Lab) is a non-profit consortium that engages a member community globally to develop foundational technology and standards that enable growth and trust in the digital media ecosystem. Comprised of digital publishers, ad technology firms, agencies, marketers, and other member companies, IAB Tech Lab focuses on solutions for brand safety and ad fraud; identity, data, and consumer privacy; ad experiences and measurement; and programmatic effectiveness. Its work includes the OpenRTB real-time bidding protocol, ads.txt anti-fraud specification, Open Measurement SDK for viewability and verification, VAST video specification and Project Rearc for identity addressability, data accountability and consumer privacy. Board members/companies are listed at www.iabtechlab.com/about-the-iab-tech-lab/tech-lab-leadership .

Learn more about IAB Tech Lab here: www.iabtechlab.com

License

OpenRTB Specification the IAB Tech Lab is licensed under a Creative Commons Attribution 3.0 License. To view a copy of this license, visit creativecommons.org/licenses/by/3.0/ or write to Creative Commons, 171 Second Street, Suite 300, San Francisco, CA 94105, USA.

Table of Contents

OVERVIEW

OpenMedia Mission

The mission of the OpenMedia project is to spur growth in programmatic marketplaces by providing open industry standards for communication between buyers of advertising and sellers of publisher inventory. There are several aspects to these standards including but not limited to real-time bidding, ad and creative management, information taxonomies, and many more.

Over recent years, multiple IAB standards have reached considerable levels of success in the industry. OpenMedia is the umbrella that pulls these standards into a coherent landscape and in doing so, it has become clear that there are many core concepts that are overlapping from these multiple specifications. This document presents a standard that formalizes these common concepts for reuse by other standards so that they can focus on their distinctiveness and practitioners can find it easier to build systems that use multiple aspects of OpenMedia.

AdCOM Executive Summary

One of the most successful IAB standards is OpenRTB. This protocol for conducting real-time auctions among sell-side exchanges and demand-side bidders first launched as OpenRTB v1.0 Mobile in February 2011. Later that year, OpenRTB v2.0 was released, which provided a unified protocol for mobile, display, and video. Due to widespread industry adoption, OpenRTB was established as an IAB standard in January 2012 with the release of version v2.1 although governance over technical content remained with the OpenRTB community. Since then and true to its initial objective, OpenRTB has become the lingua franca of real-time programmatic advertising and entered 2018 as v2.5.

During these years, programmatic advertising has become a dominant force in the industry. However, this has also led to an increasingly complex supply chain which may increase fraud rates and other risks. This is one of the key motivators driving OpenRTB v3.0 since the level of change needed to meet the challenges of programmatic currently and going forward could not be accomplished in a backward compatible manner (i.e., as an additional v2.x release).

Combined with the OpenMedia goal of rationalizing the IAB standards portfolio, this has led to a layered approach, where OpenRTB will focus on the actual media commerce transaction (e.g., auction parameters, deals, bids, etc.) while the concepts in common with other specifications (e.g., ads, placements, users, devices, sites, publishers, etc.) will be factored into its own reusable specification. Thus the genesis of the Advertising Common Object Model or AdCOM.

In addition to providing the modularity to benefit specifications in addition to OpenRTB, AdCOM seeks to address other business challenges of programmatic advertising. For example, publishers currently have limited ability to control the types of creatives they run on their properties due to the opaque nature in which traditional display ads are conveyed. Many types of undesirable creatives make their way to publisher content such as overly heavy payloads, those lacking of brand safety, excessive pixel fires, and JavaScript that launches malware.

These and other problematic behaviors result in poor and potentially damaging user experiences, diminished user trust, installation of ad blockers, erosion of publisher monetization, and the increased challenge for good actors on the advertiser side to reach their intended audience. AdCOM attempts to address these challenges by supporting new and safer structured ad formats.

Reusability by multiple IAB specifications positions AdCOM to leverage solutions such as this across a range of industry applications.

ARCHITECTURE

This section describes the OpenMedia specification landscape, the role AdCOM plays, its overall structure, and the principles that guide the usage and extensibility of the AdCOM specification.

OpenMedia Layers

To assist in reuse of objects across different specifications and to enable specifications to evolve at different paces, a layered approach is being adopted. Expressed informally, Layer-1 moves bytes among parties, Layer-2 expresses the language of these bytes, Layer-3 specifies a transaction using this language, and Layer-4 describes the concepts being transacted.

Given this layered concept, the IAB Tech Lab has defined an overall organization of related specifications as "OpenMedia". The landscape of these specifications and how they may be organized into protocol layers is illustrated as follows.

There are a number of objects that are common to multiple transaction specifications. For example, both OpenRTB and OpenDirect share a common concept of a “site”, a “placement”, an “ad”, and other so-called domain objects. These objects describe the subject of a transaction; those concepts upon which the transaction operates. Factoring them into their own model enables multiple transaction protocol specifications to reuse these common objects rather than each of them redefining similar but needlessly different versions of core concepts.

AdCOM Principles

The following points define the guiding principles underlying the AdCOM specification, some of its basic rules, and its evolution.

  • AdCOM is a living specification. New objects and attributes may be added and enumerated lists may be extended at any time and thus implementers must accept these types of changes without breakage within a version number. See Appendix E: Versioning Policy

  • Object and attribute names have been made intentionally compact while still trying to balance readability. The reason for this is that in applications like OpenRTB where JSON is still widely used, these names may be transmitted in plain text extremely frequently.

  • When using AdCOM, transaction specifications (e.g. OpenRTB) must indicate the version of AdCOM in use and specify where and how it interfaces with AdCOM objects.

  • AdCOM imposes no specific representation on its objects. This document uses JSON for illustration purposes, but this is not intended to imply any representational requirement or language binding.

  • All AdCOM objects may be extended as needed for vendor-specific applications. Extension fields for an AdCOM object must always be placed within a subordinate “ext” object. Most enumerated lists when indicated can also be extended to include vendor-specific codes typically starting at 500.

  • The typical process of promoting a new AdCOM object, attribute, or list value into future specification versions is either when a substantial concept is discovered that is applicable to multiple transaction specifications or when vendor-specific extensions become widely adopted.

REGULATORY GUIDANCE

AdCOM implementations are expected to ensure compliance on every transaction with all applicable regional legislation.

SPECIFICATION

This section contains the detailed AdCOM domain layer specification. Unless explicitly specified otherwise, annotated as optional, or called out as a best practice, all material aspects of this section are required for AdCOM compliance.

Throughout the object specifications, attributes may be indicated as “Required” or “Recommended”. Attributes are deemed required only if their omission would break the technical meaning of the object and is not necessarily an indicator of business value otherwise. Attributes are recommended when their omission would not break the object, but would dramatically diminish its value. Transaction layers in which AdCOM is used may provide additional required and/or recommended guidance specific to the application.

From a specification compliance perspective, any attribute not denoted required is optional, whether recommended or not. An optional attribute may have a default value to be assumed if omitted. If no default is indicated, then by convention its absence should be interpreted as unknown, unless otherwise specified. Empty strings or null values should be interpreted the same as omitted (i.e., the default if one is specified or unknown otherwise).

AdCOM is a collection of object classes with various relationships among them. However, there are distinct groups into which these classes are partitioned. The figure below identifies these groups as Media, Placement, and Context. This is purely a means of organization; no technical distinctions or restrictions are implied.

The Media group comprises objects that define an actual ad, including reference to its creative and metadata to enable proper rendering, restrictions compliance, event tracking, and quality auditing.

The Placement group comprises objects that define the set of allowed ads and behaviors for a given placement. This might include mechanical information (e.g., sizes, supported mime types, and other rendering options), placement details and positioning, and various restrictions lists.

Finally, the Context group comprises objects that represent concepts that are interacting, presenting, enclosing, or are otherwise relating to the world in which impressions live. These include the user, their device, their location, the ad distribution channel (e.g., site, app, digital out-of-home) with which they are interacting, the channel's publisher, its content, and any regulations that are in effect.

Note: As a convention in this document, objects being defined are denoted with uppercase first letter in deference to the common convention for class names in programming languages such as Java, whereas actual instances of objects and references thereto are lowercase.

Media Objects

The Media group of objects defines an actual ad including reference to its creative and metadata to enable proper rendering, restrictions compliance, event tracking, and quality auditing.

The following figure presents the objects and interrelationships in this group. The objects are defined in the subsections thereafter.

Object: Ad

This object is the root of a structure that defines in instance of advertising media. It includes metadata about the ad overall and sub-objects that provide additional detail specific to the type of media comprising the creative.

Attribute         Type                     Definition
id string; required ID of the creative; unique at least throughout the scope of a vendor (e.g., an exchange or buying platform). Note that multiple instances of the same ad when used in transactions must have the same ID.
adomain string array; recommended Advertiser domain; top two levels only (e.g., “ford.com”). This can be an array for the case of rotating creatives.
bundle string array When the product of the ad is an app, the unique ID of that app as a bundle or package name (e.g., “com.foo.mygame”). This should NOT be an app store ID (e.g., no iTunes store IDs). This can be an array of for the case of rotating creatives.
iurl string URL without cache-busting to an image that is representative of the ad content for cursory level ad quality checking.
cat string array Array of content categories describing the ad using IDs from the taxonomy indicated in cattax. Implementer should ensure compliance with regional legislation around data usage and sharing.
cattax integer;
default 2
The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies.
lang string Language of the creative using ISO-639-1-alpha-2. In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated beforehand. The non-standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).
attr integer array Set of attributes describing the creative. Refer to List: Creative Attributes.
secure integer Flag to indicate if the creative is secure (i.e., uses HTTPS for all assets and markup), where 0 = no, 1 = yes. There is no default and thus if omitted, the secure state is unknown. However, as a practical matter, the safe assumption is to treat unknown as non-secure.
mrating integer Media rating per IQG guidelines. Refer to List: Media Ratings.
init integer Timestamp of the original instantiation of this ad (i.e., this object or any of its children) in Unix format (i.e., milliseconds since the epoch).
lastmod integer Timestamp of most recent modification to this ad (i.e., this object or any of its children other than the Audit object) in Unix format (i.e., milliseconds since the epoch).
display Object; required * Media Subtype Object that indicates this is a display ad and provides additional detail as such. Refer to Object: Display.
* Required if no other media subtype object is specified.
video object; required * Media Subtype Object that indicates this is a video ad and provides additional detail as such. Refer to Object: Video.
* Required if no other media subtype object is specified.
audio object; required * Media Subtype Object that indicates this is an audio ad and provides additional detail as such. Refer to Object: Audio.
* Required if no other media subtype object is specified.
audit object An object depicting the audit status of the ad; typically part of a quality/safety review process. Refer to Object: Audit.
ext object Optional vendor-specific extensions.

Object: Display

This object provides additional detail about an ad specifically for display ads. There are multiple attributes for specifying creative details: banner for simple banner images native for native ads, adm for including general markup, and curl for referencing general markup via URL. In any given Display object, only one of these attributes should be used to avoid confusion. To the extent feasible, structured objects should be favored over general markup for quality and safety issues.

Attribute         Type                     Definition
mime string Mime type of the ad (e.g., “image/jpeg”).
api integer array API required by the ad if applicable. Refer to List: API Frameworks.
ctype integer Subtype of display creative. Refer to List: Creative Subtypes - Display.
w integer Absolute width of the creative in device independent pixels (DIPS), typically for non-native ads.
Note that mixing absolute and relative sizes is not recommended.
h integer Absolute height of the creative in device independent pixels (DIPS), typically for non-native ads.
Note that mixing absolute and relative sizes is not recommended.
wratio integer Relative width of the creative when expressing size as a ratio, typically for non-native ads.
Note that mixing absolute and relative sizes is not recommended.
hratio integer Relative height of the creative when expressing size as a ratio, typically for non-native ads.
Note that mixing absolute and relative sizes is not recommended.
priv string URL of a page informing the user about a buyer's targeting activity.
adm string General display markup (e.g., HTML, AMPHTML) if not using a structured alternative (e.g., banner, native).
Note that including both adm and curl is not recommended.
curl string Optional means of retrieving display markup by reference; a URL that can return HTML, AMPHTML, or a collection native Asset object and their subordinates). If this ad is matched to a Placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported.
Note that including both adm and curl is not recommended.
banner object Structured banner image object, recommended for simple banner creatives. Refer to Object: Banner.
native object Structured native object, recommended for native ads. Refer to Object: Native.
event object array Array of events that the advertiser or buying platform wants to track. Refer to Object: Event.
ext object Optional vendor-specific extensions.

Object: Banner

This object describes a basic banner creative. It is intended for display scenarios that require a simple, structured image/link pair and is more secure than allowing arbitrary HTML or JavaScript code.

Attribute         Type                     Definition
img string; required A URL that will return the image.
link object Destination link if the image is activated (e.g., clicked); not applicable in some contexts (e.g., DOOH) and its inclusion does not guarantee it will be supported. Refer to Object: LinkAsset.
ext object Optional vendor-specific extensions.

Object: Native

This object is the root of a structure that defines a native display ad.

Attribute         Type                     Definition
link object Default destination link for the native ad overall; used if an asset is activated (e.g., clicked) that doesn't specify it's own destination link. Refer to Object: LinkAsset.
asset object array Array of assets that comprise the native ad. Refer to Object: Asset.
ext object Optional vendor-specific extensions.

Object: Asset

This object is the container for each asset comprising a native ad. Each asset is of a specific type and to reflect this, one and only one of the subtype objects (i.e., title, img, video, data) must be present; all others should be omitted.

Attribute         Type                     Definition
id integer The value of AssetFormat.id if this ad references a specific native placement defined by a Placement object and its structure.
req integer;
default 0
Indicates if the asset is required to be displayed, where 0 = no, 1 = yes.
title object; required * Asset Subtype Object that indicates this is a title asset and provides additional detail as such. Refer to Object: TitleAsset.
* Required if no other asset subtype object is specified.
image object; required * Asset Subtype Object that indicates this is an image asset and provides additional detail as such. Refer to Object: ImageAsset.
* Required if no other asset subtype object is specified.
video object; required * Asset Subtype Object that indicates this is a video asset and provides additional detail as such. Refer to Object: VideoAsset.
* Required if no other asset subtype object is specified.
data object; required * Asset Subtype Object that indicates this is a data asset and provides additional detail as such. Refer to Object: DataAsset.
* Required if no other asset subtype object is specified.
link object; required * Asset Subtype Object that indicates this is a link asset and provides additional detail as such. Refer to Object: LinkAsset.
* Required if no other asset subtype object is specified.
ext object Optional vendor-specific extensions.

Object: LinkAsset

This object identifies the native asset as a link asset and is used to define navigation for call-to-action or other activations (i.e., clicks). A link asset can be independent or associated with the overall native ad (i.e., a default for all assets).

Attribute         Type                     Definition
url string; required Landing URL of the clickable link.
urlfb string Fallback URL for deep-link to be used if the URL specified in url is not supported by the device.
trkr string array List of third-party tracker URLs to be fired on click.
ext object Optional vendor-specific extensions.

Object: TitleAsset

This object identifies the native asset as a title asset, which is essentially just a plain text string with specified length.

Attribute         Type                     Definition
text string; required The text content of the text element.
len integer The length of the contents of the text attribute.
ext object Optional vendor-specific extensions.

Object: ImageAsset

This object identifies the native asset as a image asset. Image assets are use for such elements as the actual creative images and icons.

Attribute         Type                     Definition
url string; required A URL that returns the image for the asset.
w integer; recommended Width of the image asset in device independent pixels (DIPS).
h integer; recommended Height of the image asset in device independent pixels (DIPS).
type integer The type of image represented by this asset. Refer to List: Native Image Asset Types.
ext object Optional vendor-specific extensions.

Object: VideoAsset

This object identifies the native asset as a video asset. Video markup (e.g., VAST) must be either included or referenced.

Attribute         Type                     Definition
adm string; required * Video markup (e.g., VAST document) for the asset.
* Exactly one of adm and curl is required. Including both is not recommended.
curl string; required * A URL that returns the video markup (e.g., VAST document) for the asset. If this ad is matched to a placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported.
* Exactly one of adm and curl is required. Including both is not recommended.
ext object Optional vendor-specific extensions.

Object: DataAsset

This object identifies the native asset as a data asset. A data asset is used for all miscellaneous elements such as brand name, ratings, stars, review count, downloads, price, counts, etc. It is purposefully generic to support native elements not currently contemplated by this specification.

Attribute         Type                     Definition
value string; required A formatted string of data to be displayed (e.g., “5 stars”, “3.4 stars out of 5”, “$10”, etc.).
len integer The length of the value contents. This length should conform to recommendations provided in List: Native Data Asset Types
type integer The type of data represented by this asset. Refer to List: Native Data Asset Types.
ext object Optional vendor-specific extensions.

Object: Event

This object specifies a type of event that the advertiser or buying platform wants to track along with the information required to do so.

Attribute         Type                     Definition
type integer; required Type of event to track. Refer to List: Event Types.
method integer; required Method of tracking requested. Refer to List: Event Tracking Methods.
api integer array The APIs being used by the tracker; only relevant when the tracking method is JavaScript. Refer to List: API Frameworks.
url string; required * The URL of the tracking pixel or JavaScript tag, respectively.
* Required for Image-Pixel or JavaScript methods.
cdata object (Map) An array of key-value pairs to support vendor-specific data required for custom tracking. For example, the account number of a buyer with a tracking company might be represented as: {"acct": "123"}.
ext object Optional vendor-specific extensions.

Object: Video

This object provides additional detail about an ad specifically for video ads.

Attribute         Type                     Definition
mime string array Mime type(s) of the ad creative(s) (e.g., “video/mp4”).
api integer array API required by the ad if applicable. Refer to List: API Frameworks.
ctype integer Subtype of video creative. Refer to List: Creative Subtypes - Audio/Video.
dur integer Duration of the video creative in seconds.
adm string Video markup (e.g., VAST).
Note that including both adm and curl is not recommended.
curl string Optional means of retrieving markup by reference; a URL that returns video markup (e.g., VAST). If this ad is matched to a Placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported.
Note that including both adm and curl is not recommended.
ext object Optional vendor-specific extensions.

Object: Audio

This object provides additional detail about an ad specifically for audio ads.

Attribute         Type                     Definition
mime string array Mime type(s) of the ad creative(s) (e.g., “audio/mp4”).
api integer array API required by the ad if applicable. Refer to List: API Frameworks.
ctype integer Subtype of audio creative. Refer to List: Creative Subtypes - Audio/Video.
dur integer Duration of the audio creative in seconds.
adm string Audio markup (e.g., DAAST).
Note that including both adm and curl is not recommended.
curl string Optional means of retrieving markup by reference; a URL that returns audio markup (e.g., DAAST). If this ad is matched to a Placement specification, the Placement.curlx attribute indicates if this markup retrieval option is supported.
Note that including both adm and curl is not recommended.
ext object Optional vendor-specific extensions.

Object: Audit

This objects represents the outcome of some form of review of the ad. This is typical, for example, when scanning for malware or otherwise performing ad quality reviews.

Attribute         Type                     Definition
status integer The audit status of the ad. Refer to List: Audit Status Codes.
feedback string array One or more human-readable explanations as to reasons for rejection or any changes to fields for ad quality reasons (e.g., adomain, cat, attr, etc.).
init integer Timestamp of the original instantiation of this object in Unix format (i.e., milliseconds since the epoch).
lastmod integer Timestamp of most recent modification to this object in Unix format (i.e., milliseconds since the epoch).
corr object Correction object wherein the auditor can specify changes to attributes of the Ad object or its children they believe to be proper. For example, if the original Ad indicated a category of “IAB3”, but the auditor deems the correct category to be “IAB13”, then corr could include a sparse Ad object including just the cat array indicating “IAB13”.
ext object Optional vendor-specific extensions.

Placement Objects

The Placement group includes objects that define the set of allowed ads for a given impression. This can include mechanical information (e.g., sizes, supported mime types and other rendering options), placement details and positioning, various restrictions lists (e.g., advertiser domains, content categories), and more.

The following figure presents the objects and interrelationships in this group. The objects are defined in the subsections thereafter.

Object: Placement

This object represents the properties of a placement and the characteristics of ads permitted to be rendering within them. Placements of all types begin with this object as their root. It contains one or more subtype objects (i.e., display, video, audio) that define the kinds of media permitted as well as media specific placement behaviors.

The other attributes in this object apply to all aspects and substructures of the placement (i.e., the same language, secure status, etc. apply to all media types and native assets as applicable).

Attribute         Type                     Definition
tagid string Identifier for specific ad placement or ad tag; unique within a distribution channel.
ssai Integer;
default 0
Indicates if server-side ad insertion (e.g., stitching an ad into an audio or video stream) is in use and the impact of this on asset and tracker retrieval, where 0 = status unknown, 1 = all client-side (i.e., not server-side), 2 = assets stitched server-side but tracking pixels fired client-side, 3 = all server-side.
sdk string Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video, audio, or mobile); used by some ad servers to customize ad code by partner.
sdkver string Version of the SDK specified in the sdk attribute.
reward integer;
default 0
Indicates whether the user recieves a reward for viewing the ad, where 0 = no, 1 = yes. Typcially video ad implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed.
wlang string array Allow list of permitted languages of the creative using ISO-639-1-alpha-2. In practice, vendors using this object may elect an alternate standard (e.g., BCP-47) in which case this must be communicated beforehand. Omission of this attribute indicates there are no restrictions.
secure integer Flag to indicate if the creative is secure (i.e., uses HTTPS for all assets and markup), where 0 = no, 1 = yes. There is no default and thus if omitted, the secure state is unknown. However, as a practical matter, the safe assumption is to treat unknown as non-secure.
admx integer Indicates if including markup is supported (i.e., the various adm attributes throughout the Placement structure), where 0 = no, 1 = yes.
curlx integer Indicates if retrieving markup via URL reference is supported (i.e., the various curl attributes throughout the Placement structure), where 0 = no, 1 = yes.
display object; required * Placement Subtype Object that indicates that this may be a display placement and provides additional detail related thereto. Refer to Object: DisplayPlacement.
* At least one placement subtype object is required.
video object; required * Placement Subtype Object that indicates that this may be a video placement and provides additional detail related thereto. Refer to Object: VideoPlacement.
* At least one placement subtype object is required.
audio object; required * Placement Subtype Object that indicates that this may be an audio placement and provides additional detail related thereto. Refer to Object: AudioPlacement.
* At least one placement subtype object is required.
ext object Optional vendor-specific extensions.

Object: DisplayPlacement

This object signals that the placement may be a display placement. It provides additional detail about permitted display ads including simple banners, AMPHTML (i.e., Accelerated Mobile Pages), and native.

Attribute         Type                     Definition
pos integer Placement position on screen. Refer to List: Placement Positions.
instl integer; default 0 Indicates if this is an interstitial placement, where 0 = no, 1 = yes.
topframe integer Indicates if the placement will be loaded into an iframe or not, where 0 = unfriendly iframe or unknown, 1 = top frame, friendly iframe, or SafeFrame. A value of "1" can be understood to mean that expandable ads are technically capable of being delivered.
ifrbust string array Array of iframe busters supported by this placement. The meaning of strings in this attribute must be coordinated beforehand among vendors.
clktype integer;
default 1
Indicates the click type of this placement. Refer to List: Click Types.
ampren integer AMPHTML rendering treatment for AMP ads in this placement, where 1 = early loading, 2 = standard loading.
ptype Integer; recommended The display placement type. Refer to List: Display Placement Types.
context integer; recommended The context of the placement. Refer to List: Display Context Types.
mime string array Array of supported mime types (e.g., “image/jpeg”, “image/gif”). If omitted, all types are assumed.
api integer array List of supported APIs. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks.
ctype integer array Creative subtypes permitted. Refer to List: Creative Subtypes - Display.
w integer Width of the placement in units specified by unit. Note that this size applies to the placement itself; permitted creative sizes are specified elsewhere (e.g., DisplayFormat, ImageAssetFormat, etc.).
h integer Width of the placement in units specified by unit. Note that this size applies to the placement itself; permitted creative sizes are specified elsewhere (e.g., DisplayFormat, ImageAssetFormat, etc.).
unit integer;
default 1
Unit of size used for placement size (i.e., w and h attributes). Refer to List: Size Units.
priv integer;
default 0
Indicator of whether or not the placement supports a buyer-specific privacy notice URL, where 0 = no, 1 = yes.
displayfmt object array Array of objects that govern the attributes (e.g., sizes) of a banner display placement. Refer to Object: DisplayFormat.
nativefmt object This object specified the required and permitted assets and attributes of a native display placement. Refer to Object: NativeFormat.
event object array Array of supported ad tracking events. Refer to Object: EventSpec.
ext object Optional vendor-specific extensions.

Object: DisplayFormat

This object represents an allowed set of parameters for a banner display ad and often appears as an array when multiple sizes are permitted.

Attribute         Type                     Definition
w integer Absolute width of the creative in units specified by DisplayPlacement.unit. Note that mixing absolute and relative sizes is not recommended.
h integer Absolute height of the creative in units specified by DisplayPlacement.unit. Note that mixing absolute and relative sizes is not recommended.
wratio integer Relative width of the creative when expressing size as a ratio. Note that mixing absolute and relative sizes is not recommended.
hratio integer Relative height of the creative when expressing size as a ratio. Note that mixing absolute and relative sizes is not recommended.
expdir integer array Directions in which the creative is permitted to expand. Refer to List: Expandable Directions.
ext object Optional vendor-specific extensions.

Object: NativeFormat

This object refines a display placement to be specifically a native display placement. It serves as the root of a structure that includes the specifications for each of the assets that comprise the native placement.

Attribute         Type                     Definition
asset object array; required Array of objects that specify the set of native assets and their permitted formats. Refer to Object: AssetFormat.
ext object Optional vendor-specific extensions.

Object: AssetFormat

This object represents the permitted specifications of a single asset of a native ad. Along with its own attributes, exactly one of the asset subtype objects must be included. All others must be omitted.

Attribute         Type                     Definition
id integer; required Asset ID, unique within the scope of this placement specification.
req integer;
default 0
Indicator of whether or not this asset is required, where 0 = no, 1 = yes.
title object; required * Asset Format Subtype Object that indicates this is specifying a title asset and provides additional detail as such. Refer to Object: TitleAssetFormat.
* Required if no other asset format subtype object is specified.
img object; required * Asset Format Subtype Object that indicates this is specifying an image asset and provides additional detail as such. Refer to Object: ImageAssetFormat.
* Required if no other asset format subtype object is specified.
video object; required * Asset Format Subtype Object, which leverages the VideoPlacement object, that indicates this is specifying a video asset and provides additional detail as such. Refer to Object: VideoPlacement.
* Required if no other asset format subtype object is specified.
data object; required * Asset Format Subtype Object that indicates this is specifying a data asset and provides additional detail as such. Refer to Object: DataAssetFormat.
* Required if no other asset format subtype object is specified.
ext object Optional vendor-specific extensions.

Object: TitleAssetFormat

This object is used to provide native asset format specifications for a title element. Title elements are simple strings.

Attribute         Type                     Definition
len integer; required The maximum allowed length of the title value. Recommended lengths are 25, 90, or 140.
ext object Optional vendor-specific extensions.

Object: ImageAssetFormat

This object is used to provide native asset format specifications for an image element. Image elements are typically used for the actual creative image and icons.

Attribute         Type                     Definition
type integer The type of image asset supported. Refer to List: Native Image Asset Types.
mime string array Array of supported mime types (e.g., “image/jpeg”, “image/gif”). If omitted, all types are assumed.
w integer Absolute width of the image asset in device independent pixels (DIPS).
Note that mixing absolute and relative sizes is not recommended.
h integer Absolute height of the image asset in device independent pixels (DIPS).
Note that mixing absolute and relative sizes is not recommended.
wmin integer The minimum requested absolute width of the image in device independent pixels (DIPS). This option should be used for any scaling of images by the client.
hmin integer The minimum requested absolute height of the image in device independent pixels (DIPS). This option should be used for any scaling of images by the client.
wratio integer Relative width of the image asset when expressing size as a ratio.
Note that mixing absolute and relative sizes is not recommended.
hratio integer Relative height of the image asset when expressing size as a ratio.
Note that mixing absolute and relative sizes is not recommended.
ext object Optional vendor-specific extensions.

Object: DataAssetFormat

This object is used to provide native asset format specifications for a data element. A data asset is used for all miscellaneous elements such as brand name, ratings, stars, review count, downloads, prices, etc. It is purposefully generic to support native elements not currently contemplated by this specification.

Attribute         Type                     Definition
type integer; required The type of data asset supported. Refer to List: Native Data Asset Types.
len integer The maximum allowed length of the data value.
ext object Optional vendor-specific extensions.

Object: EventSpec

This object specifies a type of ad tracking event and which methods of tracking are available for it. This object may appear as an array for a given placement indicating various types of available tracking events.

Attribute         Type                     Definition
type integer; required Type of supported ad tracking event. Refer to List: Event Types.
method integer array Array of supported event tracking methods for this event type. Refer to List: Event Tracking Methods.
api integer array Event tracking APIs available for use; only relevant for JavaScript method trackers. Refer to List: API Frameworks.
jstrk string array Array of domains, top two levels only (e.g., “tracker.com”), that constitute a restriction list of JavaScript trackers. The sense of the restrictions is determined by wjs.
wjs integer;
default 1
Sense of the jstrk restriction list, where 0 = block list, 1 = allow list.
pxtrk string array Array of domains, top two levels only (e.g., “tracker.com”), that constitute a restriction list of pixel image trackers. The sense of the restrictions is determined by wpx.
wpx integer;
default 1
Sense of the pxtrk restriction list, where 0 = block list, 1 = allow list.
ext object Optional vendor-specific extensions.

Object: VideoPlacement

This object signals that the placement may be a video placement and provides additional detail about permitted video ads (e.g., VAST).

Attribute         Type                     Definition
ptype integer Placement subtype. Refer to List: Plcmt Subtypes - Video.
pos integer Placement position on screen. Refer to List: Placement Positions.
delay integer Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll placements. For additional generic values, refer to List: Start Delay Modes.
skip integer Indicates if the placement imposes ad skippability, where 0 = no, 1 = yes.
skipmin integer;
default 0
The placement allows creatives of total duration greater than this number of seconds to be skipped; only applicable if the ad is skippable.
skipafter integer;
default 0
Number of seconds a creative must play before the placement enables skipping; only applicable if the ad is skippable.
playmethod integer array Playback method(s) in use for this placement. Refer to List: Playback Methods.
playend integer The event that causes playback to end for this placement. Refer to List: Playback Cessation Modes.
clktype integer Indicates the click type of the placement. Refer to List: Click Types.
mime string array; required Array of supported mime types (e.g., “video/mp4”). If omitted, all types are assumed.
api integer array List of supported APIs for this placement. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks.
ctype integer array Creative subtypes permitted for this placement. Refer to List: Creative Subtypes - Audio/Video.
w integer Width of the placement in units specified by unit.
h integer Height of the placement in units specified by unit.
unit integer; default 1 Units of size used for w and h attributes. Refer to List: Size Units.
mindur integer Minimum creative duration in seconds. This field is mutually exclusive with rqddurs; only one of mindur and rqddurs may be in a bid request.
maxdur integer Maximum creative duration in seconds. This field is mutually exclusive with rqddurs; only one of maxdur and rqddurs may be in a bid request.
rqddurs integer array Precise acceptable durations for video creatives in seconds. This field specifically targets the Live TV use case where non-exact ad durations would result in undesirable 'dead air'. This field is mutually exclusive with mindur and maxdur; if rqddurs is specified, mindur and maxdur must not be specified and vice versa.
maxext integer;
default 0
Maximum extended creative duration if extension is allowed. If 0, extension is not allowed. If -1, extension is allowed and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxdur value.
minbitr integer Minimum bit rate of the creative in Kbps.
maxbitr integer Maximum bit rate of the creative in Kbps.
delivery integer array Array of supported creative delivery methods. If omitted, all can be assumed. Refer to List: Delivery Methods.
maxseq integer The maximum number of ads that can be played in an ad pod.
poddur integer Indicates the total amount of time in seconds that advertisers may fill for a “dynamic” video ad pod, or the dynamic portion of a “hybrid” ad pod. This field is required only for the dynamic portion(s) of video ad pods. This field refers to the length of the entire ad break, whereas mindur/maxdur/rqddurs are constraints relating to the slots that make up the pod.
podid integer Unique identifier indicating that an impression opportunity belongs to a video ad pod. If multiple impression opportunities within a bid request share the same podid, this indicates that those impression opportunities belong to the same video ad pod.
podseq integer; default 0 The sequence (position) of the video ad pod within a content stream. Refer to List: List: Pod Sequence for guidance on the use of this field.
slotinpod integer; default 0 For video ad pods, this value indicates that the seller can guarantee delivery against the indicated slot position in the pod. Refer to List: List: Slot Position in Pod for guidance on the use of this field.
mincpmpersec float Minimum CPM per second. This is a price floor for the “dynamic” portion of a video ad pod, relative to the duration of bids an advertiser may submit.
linear integer Indicates if the creative must be linear, nonlinear, etc. If none specified, no restrictions are assumed. Refer to List: Linearity Modes. Note that this field describes the expected VAST response and not whether a placement is in-stream, out-stream, etc. For that, see ptype.
boxing integer;
default 1
Indicates if letterboxing of 4:3 creatives into a 16:9 window is allowed, where 0 = no, 1 = yes.
comp object array Array of objects indicating that companion ads are available and providing the specifications thereof. Refer to Object: Companion.
comptype integer array Supported companion ad types; recommended if companion ads are specified in comp. Refer to List: Companion Types.
expdir integer array Directions in which the creative (video placement) is permitted to expand. Refer to List: Expandable Directions.
overlayexpdir integer array Directions in which the creative (video overlay) is permitted to expand. This is primarily used for non-linear videos. Refer to List: Expandable Directions.
ext object Optional vendor-specific extensions.

Object: AudioPlacement

This object signals that the placement may be an audio placement and provides additional detail about permitted audio ads (e.g., DAAST).

Attribute         Type                     Definition
delay integer Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll placements. For additional generic values, refer to List: Start Delay Modes.
skip integer Indicates if the placement imposes ad skippability, where 0 = no, 1 = yes.
skipmin integer;
default 0
The placement allows creatives of total duration greater than this number of seconds to be skipped; only applicable if the ad is skippable.
skipafter integer;
default 0
Number of seconds a creative must play before the placement enables skipping; only applicable if the ad is skippable.
playmethod integer array Playback method(s) in use for this placement. Refer to List: Playback Methods.
playend integer The event that causes playback to end for this placement. Refer to List: Playback Cessation Modes.
feed integer Type of audio feed of this placement. Refer to List: Feed Types.
nvol integer Volume normalization mode of this placement. Refer to List: Volume Normalization Modes.
mime string array; required Array of supported mime types (e.g., “audio/mp4”). If omitted, all types are assumed.
api integer array List of supported APIs for this placement. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks.
ctype integer array Creative subtypes permitted for this placement. Refer to List: Creative Subtypes - Audio/Video.
mindur integer Minimum creative duration in seconds. This field is mutually exclusive with rqddurs; only one of mindur and rqddurs may be in a bid request.
maxdur integer Maximum creative duration in seconds. This field is mutually exclusive with rqddurs; only one of maxdur and rqddurs may be in a bid request.
rqddurs integer array Precise acceptable durations for video creatives in seconds. This field specifically targets the Live TV use case where non-exact ad durations would result in undesirable 'dead air'. This field is mutually exclusive with mindur and maxdur; if rqddurs is specified, mindur and maxdur must not be specified and vice versa.
maxext integer Maximum extended creative duration if extension is allowed. If 0, extension is not allowed. If -1, extension is allowed and there is no time limit imposed. If greater than 0, then the value represents the number of seconds of extended play supported beyond the maxdur value.
minbitr integer Minimum bit rate of the creative in Kbps.
maxbitr integer Maximum bit rate of the creative in Kbps.
delivery integer array Array of supported creative delivery methods. If omitted, all can be assumed. Refer to List: Delivery Methods.
maxseq integer The maximum number of ads that can be played in an ad pod.
poddur integer Indicates the total amount of time in seconds that advertisers may fill for a “dynamic” video ad pod, or the dynamic portion of a “hybrid” ad pod. This field is required only for the dynamic portion(s) of video ad pods. This field refers to the length of the entire ad break, whereas mindur/maxdur/rqddurs are constraints relating to the slots that make up the pod.
podid integer Unique identifier indicating that an impression opportunity belongs to a video ad pod. If multiple impression opportunities within a bid request share the same podid, this indicates that those impression opportunities belong to the same video ad pod.
podseq integer; default 0 The sequence (position) of the video ad pod within a content stream. Refer to List: List: Pod Sequence for guidance on the use of this field.
slotinpod integer; default 0 For video ad pods, this value indicates that the seller can guarantee delivery against the indicated slot position in the pod. Refer to List: List: Slot Position in Pod for guidance on the use of this field.
mincpmpersec float Minimum CPM per second. This is a price floor for the “dynamic” portion of a video ad pod, relative to the duration of bids an advertiser may submit.
comp object array Array of objects indicating that companion ads are available and providing the specifications thereof. Refer to Object: Companion.
comptype integer array Supported companion ad types; recommended if companion ads are specified in comp. Refer to List: Companion Types.
overlayexpdir integer array Directions in which the creative (overlay) is permitted to expand. Refer to List: Expandable Directions.
ext object Optional vendor-specific extensions.

Object: Companion

This object is used in video and audio placements to specify an associated or so-called companion display ad. Video and audio placements can specify an array of companion ads.

Attribute         Type                     Definition
id string Identifier of the companion ad; unique within this placement.
vcm integer Indicates the companion ad rendering mode relative to the associated video or audio ad, where 0 = concurrent, 1 = end-card. For a given placement, typically only one companion at most should be designated as an end card.
display object Display specification object representing the companion ad. Refer to Object: DisplayPlacement.
ext object Optional vendor-specific extensions.

Context Objects

This group of objects represent concepts that are interacting, presenting, enclosing, or are otherwise relating to the world in which impressions live. These include the user, their device, their location, the channel (e.g., site, app, digital out-of-home) with which they are interacting, the channel's publisher, its content, and any regulations that are in effect (e.g., COPPA, GDPR).

The following figure presents the objects and interrelationships in this group. The objects are defined in the subsections thereafter.

Abstract Class: DistributionChannel

A distribution channel is an abstraction of the various types of entities or channels through which ads are distributed. Examples include websites, mobile apps, and digital out-of-home (DOOH) systems. This generalized class contains those attributes and relationships that are common to all distribution channels and as such, all of its attributes and relationships are inherited by each of its derived classes.

Note: As an abstract class, a DistributionChannel is never instantiated on its own. Only objects of its derived classes are actually realized.

Attribute         Type                     Definition
id string; recommended Vendor-specific unique identifier of the distribution channel.
name string Displayable name of the distribution channel.
pub object Details about the publisher of the distribution channel. Refer to Object: Publisher.
content object Details about the content within the distribution channel. Refer to Object: Content.

Object: Site

Derived from: DistributionChannel

This object is used to define an ad supported website, in contrast to a non-browser application, for example. As a derived class, a Site object inherits all DistributionChannel attributes and adds those defined below.

Attribute         Type                     Definition
domain string Domain of the site (e.g., “mysite.foo.com”).
cat string array Array of content categories describing the site using IDs from the taxonomy indicated in cattax.
sectcat string array Array of content categories describing the current section of the site using IDs from the taxonomy indicated in cattax.
pagecat string array Array of content categories describing the current page or view of the site using IDs from the taxonomy indicated in cattax.
cattax integer The taxonomy in use for the cat, sectcat and pagecat attributes. Refer to List: Category Taxonomies.
privpolicy integer Indicates if the site has a privacy policy, where 0 = no, 1 = yes.
keywords string Comma-separated list of keywords about the site. Only one of 'keywords' or 'kwarray' may be present. NOTE: this field is deprecated, use 'kwarray' instead.
kwarray string array Array of keywords about the site. Only one of 'keywords' or 'kwarray' may be present.
page string URL of the page within the site.
ref string Referrer URL that caused navigation to the current page.
search string Search string that caused navigation to the current page.
mobile integer Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0 = no, 1 = yes.
amp integer Indicates if the page is built with AMP HTML, where 0 = no, 1 = yes.
ext object Optional vendor-specific extensions.

Object: App

Derived from: DistributionChannel

This object is used to define an ad supported non-browser application, in contrast to a typical website, example. As a derived class, an App object inherits all DistributionChannel attributes and adds those defined below.

Attribute         Type                     Definition
domain string Domain of the app (e.g., “mygame.foo.com”).
cat string array Array of content categories describing the app using IDs from the taxonomy indicated in cattax.
sectcat string array Array of content categories describing the current section of the app using IDs from the taxonomy indicated in cattax.
pagecat string array Array of content categories describing the current page or view of the app using IDs from the taxonomy indicated in cattax.
cattax integer The taxonomy in use for the cat, sectcat and pagecat attributes. Refer to List: Category Taxonomies.
privpolicy integer Indicates if the app has a privacy policy, where 0 = no, 1 = yes.
keywords string Comma-separated list of keywords about the app. Only one of 'keywords' or 'kwarray' may be present. NOTE: this field is deprecated, use 'kwarray' instead.
kwarray string array Array of keywords about the app. Only one of 'keywords' or 'kwarray' may be present.
bundle string Bundle or package name of the app (e.g., “com.foo.mygame”) and should NOT be app store IDs (e.g., not iTunes store IDs).
storeid string The ID of the app in an app store (e.g., Apple iTunes, Google Play).
storeurl string App store URL for an installed app; for IQG 2.1 compliance.
ver string Application version.
paid integer;
default 0
Indicator of whether or not this is a paid app, where 0 = free, 1 = paid.
ext object Optional vendor-specific extensions.

Object: Dooh

Derived from: DistributionChannel

This object is used to define an ad supported digital out-of-home (DOOH) experience such as a public kiosk or digital billboard. As a derived class, a Dooh object inherits all DistributionChannel attributes and adds those defined below.

Attribute         Type                     Definition
venue integer The type of out-of-home venue. Refer to List: DOOH Venue TypesList: DOOH Venue Types.
fixed integer Indicates whether the DOOH placement is in a fixed location (e.g., kiosk, billboard, elevator) or is movable (e.g., taxi), where 1 = fixed, 2 = movable.
etime integer The exposure time in seconds per view that the creative will be displayed before refreshing to the next creative.
dpi integer Minimum DPI for text-based creative elements to display clearly.
ext object Optional vendor-specific extensions.

Object: Publisher

This object describes the publisher of the media in which ads will be displayed.

Attribute         Type                     Definition
id string, recommended Vendor-specific unique publisher identifier, as used in ads.txt files.
name string Displayable name of the publisher.
domain string Highest level domain of the publisher (e.g., “publisher.com”).
cat string array Array of content categories that describe the publisher using IDs from the taxonomy indicated in cattax. Implementer should ensure compliance with regional legislation around data usage and sharing.
cattax integer The taxonomy in use for the cat attribute. Refer to ![image](https://github.com/InteractiveAdvertisingBureau/AdCOM/assets/114763292/e80e72e1-e099-4aff-b466-a5e91eb9f62f).
ext object Optional vendor-specific extensions.

Object: Content

This object describes the content in which an impression can appear, which may be syndicated or non-syndicated content. This object may be useful when syndicated content contains impressions and does not necessarily match the publisher's general content. An exchange may or may not have knowledge of the page where the content is running as a result of the syndication method (e.g., a video impression embedded in an iframe on an unknown web property or device).

Attribute         Type                     Definition
id string ID uniquely identifying the content.
episode integer Episode number.
title string Content title.
Video Examples: “Search Committee” (television), “Star Wars, A New Hope” (movie), or “Endgame” (made for web).
Non-Video Example: “Why an Antarctic Glacier Is Melting So Quickly” (Time magazine article).
series string Content series.
Video Examples: “The Office” (television), “Star Wars” (movie), or “Arby 'N' The Chief” (made for web).
Non-Video Example: “Ecocentric” (Time Magazine blog).
season string Content season (e.g., “Season 3”).
artist string Artist credited with the content.
genre string Genre that best describes the content (e.g., rock, pop, etc).
album string Album to which the content belongs; typically for audio.
isrc string International Standard Recording Code conforming to ISO-3901.
url string A single URL of the content, for buy-side contextualization or review.
cat string array Array of content categories describing the content using IDs from the taxonomy indicated in cattax. Implementer should ensure compliance with regional legislation around data usage and sharing.
cattax integer The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies.
prodq integer Production quality. Refer to List: Production Qualities.
context integer Type of content (game, video, text, etc.). Refer to List: Content Contexts.
rating string Content rating (e.g., MPAA).
urating string User rating of the content (e.g., number of stars, likes, etc.).
mrating integer Media rating per IQG guidelines. Refer to List: Media Ratings.
keywords string Comma-separated list of keywords describing the content. Only one of 'keywords' or 'kwarray' may be present. NOTE: this field is deprecated, use 'kwarray' instead.
kwarray string array Array of keywords describing the content. Only one of 'keywords' or 'kwarray' may be present.
live integer Indication of live content, where 0 = not live, 1 = live (e.g., stream, live blog).
srcrel integer Source relationship, where 0 = indirect, 1 = direct.
len integer Length of content in seconds; typically for video or audio.
lang string Content language using ISO-639-1-alpha-2. Only one of lang or langb should be present.
langb string Content language using IETF BCP 47. Only one of lang or langb should be present.
embed integer Indicator of whether or not the content is embedded off-site from the the site or app described in those objects (e.g., an embedded video player), where 0 = no, 1 = yes.
producer object Details about the content producer. Refer to Object: Producer.
network object Details about the network. Refer to Object: Network.
channel object Details about the channel. Refer to Object: Channel.
data object array Additional user data. Each Data object represents a different data source. Refer to Object: Data.
ext object Optional vendor-specific extensions.

Object: Producer

This object defines the producer of the content in which ad will be displayed. This is particularly useful when the content is syndicated and may be distributed through different publishers and thus when the producer and publisher are not necessarily the same entity.

Attribute         Type                     Definition
id string, recommended Vendor-specific unique producer identifier. Useful if content is syndicated and may be posted on a site using embed tags.
name string Displayable name of the producer.
domain string Highest level domain of the producer (e.g., “producer.com”).
cat string array Array of content categories that describe the producer using IDs from the taxonomy indicated in cattax.
cattax integer The taxonomy in use for the cat attribute. Refer to List: Category Taxonomies.
ext object Optional vendor-specific extensions.

Object: Network

This object describes the network an ad will be displayed on. A Network is defined as the parent entity of the Channel object’s entity for the purposes of organizing Channels. Examples are companies that own and/or license a collection of content channels (Viacom, Discovery, CBS, WarnerMedia, Turner and others), or studio that creates such content and self-distributes content. Name is human-readable field while domain and id can be used for reporting and targeting purposes.

Attribute         Type                     Definition
id string A unique identifier assigned by the publisher. This may not be a unique identifier across all supply sources.
name string Network the content is on (e.g., a TV network like "ABC").
domain string The primary domain of the network (e.g., “abc.com” in the case of the network ABC). It is recommended to include the top private domain (PSL+1) for DSP targeting normalization purposes.
ext object Optional vendor-specific extensions.

Object: Channel

This object describes the channel an ad will be displayed on. A Channel is defined as the entity that curates a content library, or stream within a brand name for viewers. Examples are specific view selectable ‘channels’ within linear and streaming television (MTV, HGTV, CNN, BBC One, etc) or a specific stream of audio content commonly called ‘stations.’ Name is human-readable field while domain and id can be used for reporting and targeting purposes.

Attribute         Type                     Definition
id string A unique identifier assigned by the publisher. This may not be a unique identifier across all supply sources.
name string Channel the content is on (e.g., a local channel like "WABC-TV").
domain string The primary domain of the channel (e.g., “abc7ny.com” in the case of the local channel WABC-TV). It is recommended to include the top private domain (PSL+1) for DSP targeting normalization purposes.
ext object Optional vendor-specific extensions.

Object: User

This object contains information known or derived about the human user of the device (i.e., the audience for advertising). The user ID is a vendor-specific artifact and may be subject to rotation or other privacy policies. However, this user ID must be stable long enough to serve reasonably as the basis for frequency capping and retargeting.

Implementer should ensure compliance with regional legislation around data usage and sharing.

Attribute         Type                     Definition
id string; recommended Vendor-specific ID for the user. At least one of id or buyeruid is strongly recommended.
buyeruid string; recommended Buyer-specific ID for the user as mapped by an exchange for the buyer. At least one of id or buyeruid is strongly recommended.
yob integer, DEPRECATED Year of birth as a 4-digit integer.
gender string, DEPRECATED Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
keywords string Comma-separated list of keywords, interests, or intent. Only one of 'keywords' or 'kwarray' may be present. NOTE: this field is deprecated, use 'kwarray' instead.
kwarray string array Array of keywords describing the content. Only one of 'keywords' or 'kwarray' may be present.
consent string GDPR consent string if applicable, complying with the comply with the IAB standard Consent String Format in the Transparency and Consent Framework technical specifications.
geo object Location of the user's home base (i.e., not necessarily their current location). Refer to Object: Geo.
data object array Additional user data. Each Data object represents a different data source. Refer to Object: Data.
eids object array Extended (third-party) identifiers for this user. Refer to Object: Extended Identifiers.
ext object Optional vendor-specific extensions.

Object: Device

This object provides information pertaining to the device through which the user is interacting. Device information includes its hardware, platform, location, and carrier data. The device can refer to a mobile handset, a desktop computer, set top box, or other digital device.

Implementer should ensure compliance with regional legislation around data usage and sharing.

Attribute         Type                     Definition
type integer The general type of device. Refer to List: Device Types.
ua string Browser user agent string. This field represents a raw user agent string from the browser. For backwards compatibility, exchanges are recommended to always populate `ua` with the User-Agent string, when available from the end user’s device, even if an alternative representation, such as the User-Agent Client-Hints, is available and gets used to populate `sua`. No inferred or approximated user agents are expected in this field. If both `ua` and `sua` are present in the bid request, `sua` should be considered the more accurate representation of the device attributes. This is because the `ua` may contain a frozen or reduced UserAgent string.
sua UserAgent object Structured user agent information defined by a Object: UserAgent. If both `ua` and `sua` are present in the bid request, `sua` should be considered the more accurate representation of the device attributes. This is because the `ua` may contain a frozen or reduced UserAgent string.
ifa string ID sanctioned for advertiser use in the clear (i.e., not hashed).
dnt integer Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track.
lmt integer “Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
make string Device make (e.g., "Apple").
model string Device model (e.g., “iPhone10,1” when the specific device model is known, “iPhone” otherwise). The value obtained from the device O/S should be used when available.
os integer Device operating system. Refer to List: Operating Systems.
osv string Device operating system version (e.g., “3.1.2”).
hwv string Hardware version of the device (e.g., “5S” for iPhone 5S).
h integer Physical height of the screen in pixels.
w integer Physical width of the screen in pixels.
ppi integer Screen size as pixels per linear inch.
pxratio float The ratio of physical pixels to device independent pixels.
js integer Support for JavaScript, where 0 = no, 1 = yes.
lang string Browser language using ISO-639-1-alpha-2. Only one of lang or langb should be present.
langb string Browser language using IETF BCP 47. Only one of lang or langb should be present.
ip string IPv4 address closest to device.
ipv6 string IP address closest to device as IPv6.
xff string The value of the “x-forwarded-for” header.
iptr integer Indicator of truncation of any of the IP attributes (i.e., ip, ipv6, xff), where 0 = no, 1 = yes (e.g., from 1.2.3.4 to 1.2.3.0). Refer to https://tools.ietf.org/html/rfc6235#section-4.1.1 for more information on IP truncation.
carrier string Carrier or ISP (e.g., “VERIZON”) using exchange curated string names which should be published to bidders beforehand.
mccmnc string Mobile carrier as the concatenated MCC-MNC code (e.g., “310-005” identifies Verizon Wireless CDMA in the USA). Refer to https://en.wikipedia.org/wiki/Mobile_country_code for further information and references. Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity. The MCC-MNC values represent the SIM installed on the device and do not change when a device is roaming. Roaming may be inferred by a combination of the MCC-MNC, geo, IP and other data signals.
mccmncsim string MCC and MNC of the SIM card using the same format as mccmnc. When both values are available, a difference between them reveals that a user is roaming.
contype integer Network connection type. Refer to List: Connection Types.
geofetch integer Indicates if the geolocation API will be available to JavaScript code running in display ad, where 0 = no, 1 = yes.
geo object Location of the device (i.e., typically the user's current location). Refer to Object: Geo.
ext object Optional vendor-specific extensions.

Object: UserAgent

Structured user agent information provided when client supports User-Agent Client Hints. If both device.ua and device.sua are present in the bid request, device.sua should be considered the more accurate representation of the device attributes. This is because the device.ua may contain a frozen or reduced UserAgent string.

Attribute         Type                     Definition
browsers array of BrandVersion objects; recommended Each BrandVersion object identifies a browser or similar software component. Refer to Object: BrandVersion. Implementers should send brands and versions derived from the Sec-CH-UA-Full-Version-List header*.
platform BrandVersion object; recommended Refer to Object: BrandVersion that identifies the user agent’s execution platform / OS. Implementers should send a brand derived from the Sec-CH-UA-Platform header, and version derived from the Sec-CH-UA-Platform-Version header *.
mobile integer 1 if the agent prefers a “mobile” version of the content, if available, i.e. optimized for small screens or touch input. 0 if the agent prefers the “desktop” or “full” content. Implementers should derive this value from the Sec-CH-UA-Mobile header *.
architecture string Device’s major binary architecture, e.g. “x86” or “arm”. Implementers should retrieve this value from the Sec-CH-UA-Arch header*.
bitness string Device’s bitness, e.g. “64” for 64-bit architecture. Implementers should retrieve this value from the Sec-CH-UA-Bitness header *.
model string Device model. Implementers should retrieve this value from the Sec-CH-UA-Model header *.
source integer; default 0 The source of data used to create this object. Refer to List: User-Agent Source
ext object Optional vendor-specific extensions.

*or an equivalent JavaScript accessor from NavigatorUAData interface. This header or accessor are only available for browsers that support User-Agent Client Hints. For browsers that don’t support User-Agent Client Hints, implementers may choose to populate this field by parsing the raw User-Agent string.

Object: BrandVersion

Further identification based on User-Agent Client Hints, the BrandVersion object is used to identify a device’s browser or similar software component, and the user agent’s execution platform or operating system.

Attribute         Type                     Definition
brand string; recommended A brand identifier, for example, “Chrome” or “Windows”. The value may be sourced from the User-Agent Client Hints headers, representing either the user agent brand (from the Sec-CH-UA-Full-Version header) or the platform brand (from the Sec-CH-UA-Platform header).
version array of string A sequence of version components, in descending hierarchical order (major, minor, micro, …)
ext object Optional vendor-specific extensions.

Object: Geo

This object encapsulates various methods for specifying a geographic location. When subordinate to a Device object, it indicates the location of the device which can also be interpreted as the user's current location. When subordinate to a User object, it indicates the location of the user's home base (i.e., not necessarily their current location).

The lat and lon attributes should only be passed if they conform to the accuracy depicted in the type attribute. For example, the centroid of a large region (e.g., postal code) should not be passed.

Attribute         Type                     Definition
type integer Source of location data; recommended when passing lat/lon. Refer to List: Location Types.
lat float Latitude from -90.0 to +90.0, where negative is south.
lon float Longitude from -180.0 to +180.0, where negative is west.
accur integer Estimated location accuracy in meters; recommended when lat/lon are specified and derived from a device's location services (i.e., type = 1). Note that this is the accuracy as reported from the device. Consult OS specific documentation (e.g., Android, iOS) for exact interpretation.
lastfix integer Number of seconds since this geolocation fix was established. Note that devices may cache location data across multiple fetches. Ideally, this value should be from the time the actual fix was taken.
ipserv integer Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2). Refer to List: IP Location Services.
country string Country code using ISO-3166-1-alpha-2.
Note that alpha-3 codes may be encountered and vendors are encouraged to be tolerant of them.
region string Region code using ISO-3166-2; 2-letter state code if USA.
metro string Regional marketing areas such as Nielsen's DMA codes or other similar taxonomy to be agreed among vendors prior to use.
Note that DMA is a trademarked asset of The Nielsen Company. Vendors are encouraged to ensure their use of DMAs is properly licensed.
city string City using United Nations Code for Trade & Transport Locations “UN/LOCODE” with the space between country and city suppressed (e.g., Boston MA, USA = “USBOS”). Refer to UN/LOCODE Code List.
zip string ZIP or postal code.
utcoffset integer Local time as the number +/- of minutes from UTC.
ext object Optional vendor-specific extensions.

Object: Data

The data and segment objects together allow additional data about the related object (e.g., user, content) to be specified. This data may be from multiple sources whether from the exchange itself or third parties as specified by the id attribute. When in use, vendor-specific IDs should be discussed beforehand among the parties.

Implementer should ensure compliance with regional legislation around data usage and sharing.

Attribute         Type                     Definition
id string Vendor-specific ID for the data provider.
name string Vendor-specific displayable name for the data provider.
segment object array Array of Segment objects that contain the actual data values. Refer to Object: Segment.
ext object Optional vendor-specific extensions.

Object: Segment

Segment objects are essentially key-value pairs that convey specific units of data. The parent Data object is a collection of such values from a given data provider. When in use, vendor-specific IDs should be discussed beforehand among the parties.

Attribute         Type                     Definition
id string ID of the data segment specific to the data provider.
name string Displayable name of the data segment specific to the data provider.
value string String representation of the data segment value.
ext object Optional vendor-specific extensions.

Object: Extended Identifiers

Extended identifiers support in the OpenRTB specification allows buyers to use audience data in real-time bidding. The exchange should ensure that business agreements allow for the sending of this data. Note, it is assumed that exchanges and DSPs will collaborate with the appropriate regulatory agencies and ID vendor(s) to ensure compliance.

Attribute         Type                     Definition
source string Source or technology provider responsible for the set of included IDs. Expressed as a top-level domain.
uids object array Array of extended ID UID objects from the given source. Refer to Object: Extended Identifier UIDs.
ext object Optional vendor-specific extensions.

Object: Extended Identifier UIDs

Attribute         Type                     Definition
id string Cookie or platform-native identifier.
atype integer Type of user agent the match is from. It is highly recommended to set this, as many DSPs separate app-native IDs from browser-based IDs and require a type value for ID resolution. Refer to List: Agent Types.
ext object Optional vendor-specific extensions.

Object: Regs

This object contains any known legal, governmental, or industry regulations that are in effect.

Attribute         Type                     Definition
coppa integer Flag indicating if COPPA regulations apply, where 0 = no, 1 = yes. The Children's Online Privacy Protection Act (COPPA) was established by the U.S. Federal Trade Commission.
gdpr integer Flag indicating if GDPR regulations apply, where 0 = no, 1 = yes. The General Data Protection Regulation (GDPR) is a regulation of the European Union.
ext object Optional vendor-specific extensions.

Object: Restrictions

This object allows lists of restrictions on ad responses to be specified including specific content categories, advertisers, ads pertaining to specific apps, or creative attributes.

Attribute         Type                     Definition
bcat string array Block list of content categories using IDs from the taxonomy indicated in cattax.
cattax integer;
default 2
The taxonomy in use for the bcat attribute. Refer to List: Category Taxonomies.
badv string array Block list of advertisers by their domains (e.g., “ford.com”).
bapp string array Block list of apps for which ads are disallowed. These should be bundle or package names (e.g., “com.foo.mygame”) and should NOT be app store IDs (e.g., not iTunes store IDs).
battr integer array Block list of creative attributes. Refer to List: Creative Attributes.
ext object Optional vendor-specific extensions.

Enumerations

The following lists define enumerations referenced by attributes in AdCOM objects.

List: Agent Types

This list identifies the user agent types a user identifier is from.

Value Definition
1 An ID which is tied to a specific web browser or device (cookie-based, probabilistic, or other).
2 In-app impressions, which will typically contain a type of device ID (or rather, the privacy-compliant versions of device IDs).
3 A person-based ID, i.e., that is the same across devices.
500+ Vendor-specific codes.

List: API Frameworks

The following table is a list of API frameworks either supported by a placement or required by an ad.

Value Definition
1 VPAID 1.0
2 VPAID 2.0
3 MRAID 1.0
4 ORMMA
5 MRAID 2.0
6 MRAID 3.0
7 OMID 1.0
8 SIMID 1.0
9 SIMID 1.1
500+ Vendor-specific codes.

List: Audit Status Codes

The following table lists the codes used in Audit objects to reflect status or workflow state.

Value Definition
1 Pending Audit: An audit has not yet been completed on this ad. A recommendation cannot be made to use this ad, but vendors' policies may override.
2 Pre-Approved: An audit has not yet been completed on this ad. Subject to vendors' policies, it can be recommended for use. However, once the audit has been completed, its status will change and it may or may not be approved for continued use.
3 Approved: The audit is complete and the ad is approved for use. Note, however, that some attributes (e.g., adomain, cat, attr, etc.) may have been changed in the process by the auditor.
4 Denied: The audit is complete, but the ad has been found unacceptable in some material aspect and is disapproved for use.
5 Changed; Resubmission Requested: A version of the ad has been detected in use that is materially different from the version that was previously audited, which may result in rejection during use until the ad is resubmitted for audit and approved. Vendors need to communicate offline as to the criteria that constitutes a material change.
6 Expired: The ad has been marked as expired by the vendor. Vendors need to communicate offline as to the expected bidding behavior for ads with this status.
500+ Vendor-specific codes.

List: Auto Refresh Triggers

The following table is a list of triggers that result in an ad slot refreshing.

Value Definition
0 UNKNOWN
1 User Action: Refresh triggered by user-initiated action such as scrolling.
2 Event: Event-driven content change. For example, ads refresh when the football game score changes on the page.
3 Time:Time-based refresh. Ads refresh on a predefined time interval even without user activity.

List: Category Taxonomies

The following table lists the options for taxonomies that can be used to describe content, audience, and ad creative categories.

Value Definition
1 IAB Tech Lab Content Category Taxonomy 1.0: Deprecated, and recommend NOT be used since it does not have SCD flags.
2 IAB Tech Lab Content Category Taxonomy 2.0: Deprecated, and recommend NOT be used since it does not have SCD flags.
3 IAB Tech Lab Ad Product Taxonomy 1.0.
4 IAB Tech Lab Audience Taxonomy 1.1
5 IAB Tech Lab Content Taxonomy 2.1
6 IAB Tech Lab Content Taxonomy 2.2
7 IAB Tech Lab Content Taxonomy 3.0
8 IAB Tech Lab Ad Product Taxonomy 2.0
500+ Vendor-specific codes.

List: Click Types

The following table lists the types of creative activation (i.e., click) behavior types.

Value Definition
0 Non-Clickable
1 Clickable - Details Unknown
2 Clickable - Embedded Browser/Webview
3 Clickable - Native Browser
500+ Vendor-specific codes.

List: Companion Types

The following table lists the options to indicate markup types allowed for companion ads that apply to video and audio ads. This table is derived from VAST 2.0+ and DAAST 1.0+ specifications.

Value Definition
1 Static Resource
2 HTML Resource
3 iframe Resource

List: Connection Types

The following table lists the options for the type of device connectivity.

Value Definition
1 Ethernet; Wired Connection
2 WIFI
3 Cellular Network - Unknown Generation
4 Cellular Network - 2G
5 Cellular Network - 3G
6 Cellular Network - 4G
7 Cellular Network - 5G

List: Content Contexts

The following table lists the various options for indicating the type of content being used or consumed by the user in which ads may appear. This table has values derived from the TAG Inventory Quality Guidelines (IQG).

Value Definition
1 Video (i.e., video file or stream such as Internet TV broadcasts)
2 Game (i.e., an interactive software game)
3 Music (i.e., audio file or stream such as Internet radio broadcasts)
4 Application (i.e., an interactive software application)
5 Text (i.e., primarily textual document such as a web page, eBook, or news article)
6 Other (i.e., none of the other categories applies)
7 Unknown

List: Creative Attributes

The following table specifies a standard list of creative attributes that can describe an actual ad or restrictions relative to a given placement.

Value Definition
1 Audio Ad (Autoplay)
2 Audio Ad (User Initiated)
3 Expandable (Automatic)
4 Expandable (User Initiated - Click)
5 Expandable (User Initiated - Rollover)
6 In-Banner Video Ad (Autoplay)
7 In-Banner Video Ad (User Initiated)
8 Pop (e.g., Over, Under, or Upon Exit)
9 Provocative or Suggestive Imagery
10 Shaky, Flashing, Flickering, Extreme Animation, Smileys
11 Surveys
12 Text Only
13 User Interactive (e.g., Embedded Games)
14 Windows Dialog or Alert Style
15 Has Audio On/Off Button
16 Ad Provides Skip Button (e.g. VPAID-rendered skip button on pre-roll video)
17 Adobe Flash
18 Responsive; Sizeless; Fluid (i.e., creatives that dynamically resize to environment)
500+ Vendor-specific codes.

List: Creative Subtypes - Audio/Video

The following table lists the various subtypes of audio and video ad creatives.

Value Definition
1 VAST 1.0
2 VAST 2.0
3 VAST 3.0
4 VAST 1.0 Wrapper
5 VAST 2.0 Wrapper
6 VAST 3.0 Wrapper
7 VAST 4.0
8 VAST 4.0 Wrapper
9 DAAST 1.0
10 DAAST 1.0 Wrapper
11 VAST 4.1
12 VAST 4.1 Wrapper
13 VAST 4.2
14 VAST 4.2 Wrapper

List: Creative Subtypes - Display

The following table lists the various subtypes of display ad creatives.

Value Definition
1 HTML
2 AMPHTML
3 Structured Image Object
4 Structured Native Object

List: Delivery Methods

The following table lists the various options for the delivery of video or audio content.

Value Definition
1 Streaming
2 Progressive
3 Download

List: Device Types

The following table lists the types of devices. This table has values derived from the TAG Inventory Quality Guidelines (IQG).

Value Definition
1 Mobile/Tablet - General
2 Personal Computer
3 Connected TV
4 Phone
5 Tablet
6 Connected Device
7 Set Top Box
8 OOH Device

List: Display Context Types

The following table lists the types of context in which a native ad may appear (i.e., the type of content surrounding the ad on the page). This is intended to denote primary content although other content may also appear on the page. Note that there are two levels of detail grouped by 10s (i.e., 12 is a refined case of 100).

Value Definition
10 Content-centric context (e.g., newsfeed, article, image gallery, video gallery, etc.).
11 - Primarily article content, which could include images, etc. as part of the article.
12 - Primarily video content.
13 - Primarily audio content.
14 - Primarily image content.
15 - User-generated content (e.g., forums, comments, etc.).
20 Social-centric context (e.g., social network feed, email, chat, etc.).
21 - Primarily email content.
22 - Primarily chat/IM content.
30 Product context (e.g., product listings, details, recommendations, reviews, etc.).
31 - App store/marketplace.
32 - Product reviews site primarily, which may sell product secondarily.
500+ Vendor-specific codes.

List: Display Placement Types

The following table lists the general types of display placements; the locations where a native ad may be shown in relationship to the surrounding content.

Value Definition
1 In the feed of content (e.g., as an item inside the organic feed, grid, listing, carousel, etc.).
2 In the atomic unit of the content (e.g., in the article page or single image page).
3 Outside the core content (e.g., in the ads section on the right rail, as a banner-style placement near the content, etc.).
4 Recommendation widget; most commonly presented below article content.
500+ Vendor-specific codes.

List: DOOH Multiplier Measurement Source Types

The following table lists the types of entities that provide quantity measurement for impression multipliers, which are common in Out of Home advertising.

Value Definition
0 Unknown
1 Measurement Vendor Provided
2 Publisher Provided
3 Exchange Provided

List: DOOH Venue Taxonomies

The following table contains a list of supported taxonomies describing the locations and contexts in which Out-Of-Home media may be experienced. Taxonomies entries are expected to refer to a specific version, unless a given taxonomy has explicit semantics for forward compatibility and handling updates.

The specifics of how to serialize values for a given taxonomy are expected to be defined by the given taxonomy.

Value Definition
0 AdCom DOOH Venue Types (deprecated)
1 OpenOOH Venue Taxonomy 1.0 https://github.com/openooh/venue-taxonomy/blob/main/specification-1.0.md
2 DPAA Device Venue Types https://github.com/InteractiveAdvertisingBureau/AdCOM/blob/master/AdCOM%20v1.0%20FINAL.md#list--dooh-venue-types-
3 DMI Categorization of Venues 1.1 https://www.dmi-org.com/download/DMI_Standards_for_DOOH_Venues.pdf
4 OMA taxonomy Jan 2022 https://www.oma.org.au/industry-standards
5 OpenOOH Venue Taxonomy 1.1 https://github.com/openooh/venue-taxonomy/blob/main/specification-1.1.md

List: DOOH Venue Types (deprecated)

This list presents the digital out-of-home venue types and is derived from DPAA Programmatic Standards.

Value Definition
1 Airborne
2 Airports - General
3 Airports - Baggage Claim
4 Airports - Terminal
5 Airports - Lounges
6 ATMs
7 Backlights
8 Bars
9 Benches
10 Bike Racks
11 Bulletins
12 Buses
13 Cafes
14 Casual Dining Restaurants
15 Child Care
16 Cinema
17 City Information Panels
18 Convenience Stores
19 Dedicated Wild Posting
20 Doctors Offices - General
21 Doctors Offices - Obstetrics
22 Doctors Offices - Pediatrics
23 Family entertainment
24 Ferries
25 Financial Services
26 Gas Stations
27 Golf Courses
28 Gyms
29 Hospitals
30 Hotels
31 Junior Posters
32 Kiosks
33 Malls - General
34 Malls - Food Courts
35 Marine
36 Mobile Billboards
37 Movie Theater Lobbies
38 Newsstands
39 Office Buildings
40 Phone Kiosks
41 Posters
42 QSR
43 Rail
44 Receptacles
45 Resorts / Leisure
46 Retail
47 Salons
48 Shelters
49 Sports Arenas
50 Subway
51 Taxis / Wrapped vehicles
52 Truckside
53 Universities
54 Urban Panels
55 Veterinarian Offices
56 Walls / Spectaculars
57 Other
500+ Vendor-specific codes.

List: Event Tracking Methods

The following table lists the available methods of tracking of ad events. Vendor specific codes may include custom measurement companies (e.g., Moat, Doubleverify, IAS, etc.).

Value Definition
1 Image-Pixel: URL provided will be inserted as a 1x1 pixel at the time of the event.
2 JavaScript: URL provided will be inserted as a JavaScript tag at the time of the event.
500+ Vendor-specific codes.

List: Event Types

The following table lists the types of ad events available for tracking. These types refer to the actual event, timing, etc.; not the method of firing. Scripts that are performing measurement should be deployed at the "loaded" event.

Value Definition
1 loaded: Delivered as a part of the creative markup. Creative may be pre-cached or pre-loaded; prior to initial rendering.
2 impression: Ad impression per IAB/MRC Ad Impression Measurement Guidelines.
3 viewable-mrc50: Visible impression using MRC definition of 50% in view for 1 second.
4 viewable-mrc100: 100% in view for 1 second (i.e., the GroupM standard).
5 viewable-video50: Visible impression for video using MRC definition of 50% in view for 2 seconds.
500+ Vendor-specific codes.

List: Expandable Directions

The following table lists the directions in which an expandable ad may expand, given the positioning of the ad unit on the page and constraints imposed by the content.

Value Definition
1 Left
2 Right
3 Up
4 Down
5 Full Screen
6 Resize/Minimize (make smaller)

List: Feed Types

The following table lists the types of feeds for audio.

Value Class Definition
1 AOD Music streaming service
2 LIVE FM/AM broadcast (live content broadcast over the air but also available via online streaming)
3 AOD Podcast (original, pre-recorded content distributed as episodes in a series)
4 AOD Catch-up radio (recorded segment of a radio show that was originally broadcast live)
5 LIVE Web radio (live content only available via online streaming, not as AM/FM broadcast)
6 MISC Video game (background audio in video games)
7 MISC Text to speech (audio books, website plugin that can read article)
500+ MISC Vendor-specific codes.

List: ID Match Methods

The following table contains enumerations for various ways an ID could be matched to an ad request, and if they pertain to a single property or app. It should be used on conjunction with the mm attribute in Object: EID of OpenRTB 2.x.

Value Name Definition
0 Unknown
1 No Match No matching has occurred. The associated ID came directly from a 3rd-party cookie or OS-provided resettable device ID for advertising (IFA).
2 Browser Cookie Sync Real time cookie sync as described in Appendix: Cookie Based ID Syncing of OpenRTB 2.x
3 Authenticated ID match was based on user authentication such as an email login or hashed PII
4 Observed ID match was based on a 1st party observation, but without user authentication (e.g. GUID, SharedID, Session IDs, CHIPS or other 1st party cookies contained in localStorage)
5 Inference ID match was inferred from linkage based on non-authenticated features across multiple browsers or devices (e.g. IP address and/or UserAgent)
500+ Vendor Specific

List: IP Location Services

The following table lists the services and/or vendors used for resolving IP addresses to geolocations.

Value Definition
1 ip2location
2 Neustar (Quova)
3 MaxMind
4 NetAcuity (Digital Element)

List: Linearity Modes

The following table indicates the options for media linearity (typically video). This corresponds to the required type of VAST response, where a linear response is VAST containing video assets, and non-linear is a VAST response (typically) containing a banner/overlay.

Value Definition
1 Linear
2 Non-Linear (i.e., Overlay)

List: Location Types

The following table lists the options to indicate how the geographic information was determined.

Value Definition
1 GPS/Location Services
2 IP Address
3 User Provided (e.g., registration data)

List: Media Ratings

The following table lists the media ratings used in describing content based on the TAG Inventory Quality Guidelines (IQG) v2.1 categorization. Refer to www.iab.com/guidelines/digital-video-suite for more information.

Value Definition
1 All Audiences
2 Everyone Over Age 12
3 Mature Audiences

List: Native Data Asset Types

The following table is a list of common data asset types. This list is non-exhaustive and is intended to be expanded over time. Size recommendations are noted as "maximum length of at least", which means the publisher or supply platform should support a maximum length of at least this value and the buying platform knows that a string of this size should be accepted.

Value Definition
1 sponsored: "Sponsored By" message which should contain the brand name of the sponsor. Recommended maximum length of at least 25 characters.
2 desc: Descriptive text associated with the product or service being advertised. Long text lengths may be truncated or ellipsed when rendered. Recommended maximum length of at least 140 characters.
3 rating: Numeric rating of the product (e.g., an app's rating). Recommended integer range of 0-5.
4 likes: Number of social ratings or "likes" of the product.
5 downloads: Number downloads and/or installs of the product.
6 price: Price of the product, app, or in-app purchase. Value should include currency symbol in localized format (e.g., "$10").
7 saleprice: Sale price that can be used together with "price" to indicate a comparative discounted price. Value should include currency symbol in localized format (e.g., "$8.50").
8 phone: A formatted phone number.
9 address: A formatted address.
10 desc2: Additional descriptive text associated with the product.
11 displayurl: Display URL for the ad. To be used when sponsoring entity doesn't own the content (e.g., "Sponsored by Brand on Site", where Site is specified in this data asset).
12 ctatext: Description of the call to action (CTA) button for the destination URL. Recommended maximum length of at least 15 characters.
500+ Vendor-specific codes.

List: Native Image Asset Types

The following table is a list of common image asset types. This list is non-exhaustive and is intended to be expanded over time. Size recommendations are noted as "maximum height or width of at least", which means the publisher or supply platform should support a maximum height or width of at least this value and the buying platform knows that an image of this size should be accepted.

Value Definition
1 Icon: Icon image. Maximum height at least 50 device independent pixels (DIPS); aspect ratio 1:1.
3 Main: Large image preview for the ad. At least one of 2 size variants required:

Small: Maximum height at least 200 DIPS; maximum width at least 200, 267, or 382 DIPS (i.e., aspect ratios of 1:1, 4:3, or 1.91:1, respectively).

Large: Maximum height at least 627 DIPS; maximum width at least 627, 836, or 1198 DIPS (i.e., aspect ratios of 1:1, 4:3, or 1.91:1, respectively).
500+ Vendor-specific codes.

List: Operating Systems

The following table lists the options for device operating system.

Value Definition
0 Other Not Listed
1 3DS System Software
2 Android
3 Apple TV Software
4 Asha
5 Bada
6 BlackBerry
7 BREW
8 ChromeOS
9 Darwin
10 FireOS
11 FirefoxOS
12 HelenOS
13 iOS
14 Linux
15 MacOS
16 MeeGo
17 MorphOS
18 NetBSD
19 NucleusPLUS
20 PS Vita System Software
21 PS3 System Software
22 PS4 Software
23 PSP System Software
24 Symbian
25 Tizen
26 WatchOS
27 WebOS
28 Windows
500+ Vendor-specific codes.

List: Placement Positions

The following table lists the placement positions as a relative measure of visibility or prominence. This table has values derived from the TAG Inventory Quality Guidelines (IQG).

Value Definition
0 Unknown
1 Above The Fold
2 Locked (i.e., fixed position)
3 Below The Fold
4 Header
5 Footer
6 Sidebar
7 Fullscreen

List: Placement Subtypes - Video

The following table lists the various types of video placements derived largely from the IAB Digital Video Guidelines. To be sent using placement attribute in Object:Video. DEPRECATED AS OF 2.6-202303 RELEASE. Proposed removal of this list and associated attribute in 2024.

Value Definition
1 In-Stream: Played before, during or after the streaming video content that the consumer has requested (e.g., Pre-roll, Mid-roll, Post-roll).
2 In-Banner: Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery.
3 In-Article: Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message.
4 In-Feed: Found in content, social, or product feeds.
5 Interstitial/Slider/Floating: Covers the entire or a portion of screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view).

List: Plcmt Subtypes - Video

The following table lists the various types of video placements in accordance with updated IAB Digital Video Guidelines. To be sent using plcmt attribute in Object:Video. Please refer to the implementation guide for examples and information on how to use the updated signals.

Value Definition
1 Instream: Pre-roll, mid-roll, and post-roll ads that are played before, during or after the streaming video content that the consumer has requested. Instream video must be set to “sound on” by default at player start, or have explicitly clear user intent to watch the video content. While there may be other content surrounding the player, the video content must be the focus of the user’s visit. It should remain the primary content on the page and the only video player in-view capable of audio when playing. If the player converts to floating/sticky subsequent ad calls should accurately convey the updated player size.
2 Accompanying Content: Pre-roll, mid-roll, and post-roll ads that are played before, during, or after streaming video content. The video player loads and plays before, between, or after paragraphs of text or graphical content, and starts playing only when it enters the viewport. Accompanying content should only start playback upon entering the viewport. It may convert to a floating/sticky player as it scrolls off the page.
3 Interstitial:Video ads that are played without video content. During playback, it must be the primary focus of the page and take up the majority of the viewport and cannot be scrolled out of view. This can be in placements like in-app video or slideshows.
4 No Content/Standalone: Video ads that are played without streaming video content. This can be in placements like slideshows, native feeds, in-content or sticky/floating.

List: Playback Cessation Modes

The following table lists the various modes for when media playback terminates.

Value Definition
1 On Video Completion or when Terminated by User
2 On Leaving Viewport or when Terminated by User
3 On Leaving Viewport Continues as a Floating/Slider Unit until Video Completion or when Terminated by User

List: Playback Methods

The following table lists the various media playback methods.

Value Definition
1 Initiates on Page Load with Sound On
2 Initiates on Page Load with Sound Off by Default
3 Initiates on Click with Sound On
4 Initiates on Mouse-Over with Sound On
5 Initiates on Entering Viewport with Sound On
6 Initiates on Entering Viewport with Sound Off by Default
7 Continuous Playback - Media playback is set to play additional media automatically without user interaction. The media player will keep playing additional media (playlist or generated) for the user until the user actively stops this from happening.

List: Pod Deduplication Settings

The following table lists the various pod deduplication settings.

Value Definition
1 Deduplicated on adomain
2 Deduplicated on IAB category
3 Deduplicated on creative ID
4 Deduplicated on mediafile URL

List: Pod Sequence

The following table lists the values for the pod sequence field, for use in audio and video content streams with one or more ad pods.

Value Definition
-1 Last pod in the content stream
0 Any pod in the content stream
1 First pod in the content stream

List: Production Qualities

The following table lists the options for content quality. These values are defined by the IAB; refer to www.iab.com/wp-content/uploads/2015/03/long-form-video-final.pdf for more information.

Value Definition
0 Unknown
1 Professionally Produced
2 Prosumer
3 User Generated (UGC)

List: Size Units

The following table lists the units of height and width used by creatives, assets, and placement specifications where noted.

Value Definition
1 Device Independent Pixels (DIPS)
2 Inches
3 Centimeters

List: Slot Position in Pod

The following table lists the values for the slot position in pod field, for use in audio and video ad pods.

Value Definition
-1 Last ad in the pod
0 Any ad in the pod
1 First ad in the pod
2 First or Last ad in the pod

List: Start Delay Modes

The following table lists the various options for the video or audio start delay. If the start delay value is greater than 0, then the position is mid-roll and the value indicates the start delay.

Value Definition
>0 Mid-Roll (value indicates start delay in second)
0 Pre-Roll
-1 Generic Mid-Roll
-2 Generic Post-Roll

List: User-Agent Source

The following table lists the possible sources for User-Agent metadata.

Value Definition
0 Unspecified/unknown
1 User-Agent Client Hints (only low-entropy headers were available)
2 User-Agent Client Hints (with high-entropy headers available)
3 Parsed from User-Agent header (the same string carried by the ua field)

List: Volume Normalization Modes

The following table lists the types of volume normalization modes, typically for audio.

Value Definition
0 None
1 Ad Volume Average Normalized to Content
2 Ad Volume Peak Normalized to Content
3 Ad Loudness Normalized to Content
4 Custom Volume Normalization

Appendix A: Additional Resources

Interactive Advertising Bureau Technology Laboratory (IAB Tech Lab)
www.iabtechlab.com

Creative Commons / Attribution License
creativecommons.org/licenses/by/3.0

AdCOM Project on Github
https://github.com/InteractiveAdvertisingBureau/AdCOM

OpenRTB v3.0 Specification
https://github.com/InteractiveAdvertisingBureau/openrtb

IAB Resources & TAG Inventory Quality Guidelines (IQG)
www.iab.com/guidelines/taxonomy
www.iab.com/guidelines/digital-video-suite
www.iab.com/wp-content/uploads/2015/03/long-form-video-final.pdf
www.tagtoday.net/iqg/guidelines
github.com/InteractiveAdvertisingBureau/GDPR-Transparency-and-Consent-Framework

Digital Place-Based Advertising Association (DPAA)
dp-aa.org

United Nations Code for Trade & Transport Locations - UN/LOCODE"
www.unece.org/cefact/locode/service/location

IP Flow Anonymization Support / Truncation, Internet Engineering Task Force (IETF)
tools.ietf.org/html/rfc6235#section-4.1.1

MCC-MNC Codes for Mobile Carriers, Wikipedia
en.wikipedia.org/wiki/Mobile_country_code

JavaScript Object Notation (JSON)
www.json.org

Appendix B: Change Log

This appendix serves as a brief summary of changes to the specification. These changes pertain only to the substance of the specification and not routine document formatting, information organization, or content without technical impact. For that, see Appendix D: Errata.

Version Release Changes
1.0 March 2022 Updates to support OpenRTB 2.6 release and keep 2.x/AdCOM in sync
Added Pod Bidding features, rqddurs, poddur, podid, podseq, mincmppersec, slotinpod to AudioPlacement and VideoPlacement objects.
Added Device.langb and Content.langb to support IETF BCP 47
Fixed eids typo so that it is an object array instead of object
Added network and channel objects
Deprecated yob and gender
Added kwarray as preferred format to keywords
Added new playback method, continuousplayback
Added device type ooh
Added new lists to support pod bidding; Ad Sequence and Pod Sequence
Added new list to support User-Agent Source
Added UserAgent and BrandVersion objects to support User Agent Client Hints
1.0 August 2021 Added expdir to VideoPlacement: Support for indicating permitted expansion direction for video ads.
Added overlaydir to VideoPlacement and AudioPlacement: Support for indicating permitted expansion direction for video and audio ads overlays.
SIMID 1.1: SIMID 1.1 has been added to the API frameworks list.
Expansion directions: "Resize/Minimize (make smaller)" has been added to the list of expanding directions.
Definition of linearity: In the linearity modes list and the linear field in the VideoPlacement object, text has been revised to clarify that linearity corresponds to expected VAST response and is not an indication of in-stream vs out-stream.
Category taxonomies list updated: The category taxonomies list was updated with the latest IAB taxonomies. The description of the list was expanded to note that it includes taxonomies for describing content, ads, and audiences. Old versions of taxonomies have been marked deprecated. <>
1.0 June 2020 Added extended IDs object: Support for passing of multiple IDs of varying types.
1.0 February 2020 Regulatory guidance: A section has been added to call attention to the expectation that implementers comply with applicable laws or regulations. Fields and objects which may be impacted have had text added.
1.0 November 2019 Added VAST 4.2 and SIMID 1.0: API frameworks and video/audio subtypes lists have been updated to include VAST 4.2 and SIMID 1.0.
Versioning policy: Elaborated on the versioning of this specification.
1.0 November 2018 Initial release.

Appendix C: OpenRTB Interfaces

As OpenRTB v3.0+ is a very popular transaction layer that uses AdCOM, this appendix is provided to show the interface between the two specifications. This is presented here as informational only; please refer to the current OpenRTB specification v3.0+ for official details on OpenRTB.

In the JSON snippets that follow, AdCOM objects are shown within OpenRTB payloads. The ellipses indicate attributes unrelated to this example that have been omitted for brevity.

Request Context

The following is an abbreviated example of an OpenRTB v3.x bid request. It self-identifies as OpenRTB and shows its version as “3.0”. It also shows that it is using AdCOM v1.0 as its domain layer.

The context object is the OpenRTB interface to AdCOM context objects. It can contain any of the top-level context objects, all of which are optional, and their subordinates. This example includes top-level objects regs, restrictions, site (no more than one distribution channel subtype may be included), user, and device.

This example is indicating a mobile optimized website and some basic details about the site and its publisher. The user is a female born in 1990. She is using an Apple iPhone 6S, running iOS 11.4.1, and is connected via the Verizon network. Her device (and presumably she) is currently located in Boston MA, USA, during eastern standard time. She is not subject to GDPR or COPPA. We would also like to block adult, illegal, and uncategorized content as well as ads from car makers Ford and Buick.

{
   "openrtb": {
      "ver": "3.0",
      "domainspec": "adcom",
      "domainver": "1.0",
      "request": {
         ...
         "context": {
            "regs": {
               "gdpr": 0,
               "coppa": 0
            },
            "restrictions": {
               "bcat": [ "IAB24", "IAB25", "IAB26" ],
               "cattax": 1,
               "badv": [ "ford.com", "buick.com" ]
            },
            "site": {
               "id": "1234",
               "name": "Awesome Example Site",
               "domain": "examplesitedomain.com",
               "mobile": 1,
               "amp": 0,
               "pub": {
                  "id": "9876",
                  "name": "Example Publisher, Inc.",
                  "domain": "examplepubdomain.com"
               }
            },
            "user": {
               "id": "a0af45c77890045deec100acb8443baff57c",
               "buyeruid": "fcd4282456238256034abcdef220d9aa5892",
            },
            "device": {
               "type": 4,
               "ifa": "8846d6fa10008bceaaf322908dfcb221",
               "ip": "1.2.3.4",
               "ua": "...user agent string...",
               "make": "Apple",
               "model": "iPhone",
               "hwv": "6s",
               "os": 13,
               "osv": "11.4.1",
               "mccmnc": "310-005",
               "geo": {
                  "type": 1,
                  "lat": 42.3601,
                  "lon": 71.0581,
                  "country": "USA",
                  "utcoffset": -300
               }
            }
         }
         ...
      }
   }
}

Item Specifications

The following snippet is an abbreviated OpenRTB v3.x bid request that offers a single item for sale.

The spec object within an item is the OpenRTB interface to AdCOM placement objects. It contains one Placement top-level object and its subordinates.

This example is indicating a display placement that must be secure. Either a structured banner or AMPHTML is acceptable and if the latter, the AMP rendering mode will be early. The placement is not interstitial, two possible sizes are offered (i.e., 320x50 and 320x250), and a simple pixel tracker for the impression event is supported.

{
   "openrtb": {
      "ver": "3.0",
      "domainspec": "adcom",
      "domainver": "1.0",
      "request": {
         ...
         "item": [
            {
               ...
               "spec": {
                  "placement": {
                     "tagid": "plc-ftr-123abc",
                     "secure": 1,
                     "display": {
                        "ctype": [ 2, 3 ],
                        "ampren": 0,
                        "instl": 0,
                        "displayfmt": [
                           {
                              "w": 320,
                              "h": 50
                           },
                           {
                              "w": 320,
                              "h": 250
                           }
                        ],
                        "event": [
                           {
                              "type": 1,
                              "method": [ 1 ]
                           }
                        ]
                     }
                  }
               }
               ...
            }
         ]
         ...
      }
   }
}

Media Response

The following is an abbreviated example of an OpenRTB v3.x bid response. It self-identifies as OpenRTB and shows its version as “3.0”. It also shows that it is using AdCOM v1.0 as its domain layer.

The media object is the OpenRTB interface to AdCOM media objects. It contains one Ad top-level object and its subordinates.

This example is indicating a secure display ad for Ford using a structured banner object with a 320x50 JPEG creative. A pixel tracker for the impression rendering event is requested.

{
   "openrtb": {
      "ver": "3.0",
      "domainspec": "adcom",
      "domainver": "1.0",
      "response": {
         ...
         "seatbid": [
            {
               ...
               "bid": [
                  {
                     ...
                     "media": {
                        "ad": {
                           "id": "d0bcb39723af87c2bb00942afee5710e",
                           "adomain": [ "ford.com" ],
                           "secure": 1,
                           "display": {
                              "mime": "image/jpeg",
                              "ctype": 3,
                              "w": 320,
                              "h": 50,
                              "banner": {
                                 "img": "https://somebuyer.com/creative",
                                 "link": {
                                    "url": "https://somebuyer.com/click",
                                    "urlfb": "https://somebuyer.com"
                                 }
                              },
                              "event": [
                                 {
                                    "type": 1,
                                    "method": 1,
                                    "url": "https://somebuyer.com/pixel"
                                 }
                              ]
                           }
                        }
                     }
                     ...
                  }
               ]
            }
         ]
      }
   }
}

Appendix D: Errata

This appendix catalogues any error corrections which have been made to this document after its versioned release. The body of the document has been updated accordingly.

Only minor fixes, such as clarifications or corrections to descriptions, may be treated as errata. Improvements or material changes are summarized in the change log.

Granular details of the changes can be seen by reviewing the commit history of the document.

Clarification: mccmnc description and rwdd description for clarity. (2022/03/25)

Change of terminology: References to "whitelist" have been changed to "allow list" consistent with industry norms. (2021/05/11)

Language improvements: Word choice has been improved in places for clarity. (2020/02/14)

Description of "w" and "h" fields in VideoPlacement object: The description of the "w" and "h" fields has been corrected to read "[Width/Height] of the placement...." The size of the video player placement generally does not have a direct bearing on what creative assets may be served to it. (2018/12/12)

Clarification of event types: The Event Types list has been adjusted to clarify which event measurement scripts should be attached to (generally, "loaded") as well as clarifying the definition of "loaded" and "impression". (2018/12/12)

Appendix E: Versioning Policy

The current version of the AdCOM specification is updated approximately once a month if there are non-breaking improvements to be released such as new fields, objects, or values in enumerated lists. Errata, such as clarifications or corrections to descriptions not materially impacting the specification itself, are also addressed during monthly updates. See Errata.

AdCOM's version number is only incremented on breaking changes. In other words, AdCOM 1.1 should be considered a distinct version from AdCOM 1.0 where there is a need for distinguishing versions; for example, when parsing an OpenRTB bid request and interpreting the "domainver" field. See AdCOM Principles.

Release branches are created for each monthly release and the history of these can be reviewed on GitHub. The master branch for the repository will always reflect the most recent release, whereas ongoing development work occurs in the 'develop' branch.