AdCOM Specification v1.0

June 2020

About the IAB Technology Lab

The IAB Technology Laboratory (Tech Lab) is a non-profit research and development consortium that produces and provides standards, software, and services to drive growth of an effective and sustainable global digital media ecosystem. Comprised of digital publishers and ad technology firms as well as marketers, agencies, and other companies with interests in the interactive marketing arena, IAB Tech Lab aims to enable brand and media growth via a transparent, safe, effective supply chain, simpler and more consistent measurement, and better advertising experiences for consumers, with a focus on mobile and TV/digital video channel enablement. The IAB Tech Lab portfolio includes the DigiTrust real-time standardized identity service designed to improve the digital experience for consumers, publishers, advertisers, and third-party platforms. Board members include AppNexus, ExtremeReach, Google, GroupM, Hearst Digital Media, Integral Ad Science, Index Exchange, LinkedIn, MediaMath, Microsoft, Moat, Pandora, PubMatic, Quantcast, Telaria, The Trade Desk, and Yahoo! Japan. Established in 2014, the IAB Tech Lab is headquartered in New York City with an office in San Francisco and representation in Seattle and London.

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.

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 if this is a rewarded placement, where 0 = no, 1 = yes.
`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: Placement 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	Playback method 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.
`maxdur`	integer	Maximum creative duration in seconds.
`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.
`linear`	integer	Indicates if the creative must be linear, nonlinear, etc. If none specified, no restrictions are assumed. Refer to List: Linearity Modes.
`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.
`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	Playback method 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.
`maxdur`	integer	Maximum creative duration in seconds.
`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.
`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.
`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.
`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.
`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 List: Category Taxonomies.
`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.
`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.
`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.
`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: 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	Year of birth as a 4-digit integer.
`gender`	string	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.
`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	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.
`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.
`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.
`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: 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
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: Category Taxonomies

This list identifies the taxonomy in effect when content categories are listed.

Value	Definition
1	IAB Content Category Taxonomy 1.0.
2	IAB Content Category Taxonomy 2.0: www.iab.com/guidelines/taxonomy
3	IAB Ad Product Taxonomy 1.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

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 Venue Types

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

List: Feed Types

The following table lists the types of feeds, typically for audio.

Value	Definition
1	Music Service
2	FM/AM Broadcast
3	Podcast

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 for video.

Value	Definition
1	Linear (i.e., In-Stream such as Pre-Roll, Mid-Roll, Post-Roll)
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 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). Large: 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).
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
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.

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: 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

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
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: 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: 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	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",
               "yob": 1990,
               "gender": "F"
            },
            "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.

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.

Files

AdCOM v1.0 FINAL.md

Latest commit

History

AdCOM v1.0 FINAL.md

File metadata and controls

AdCOM Specification v1.0

Table of Contents

OVERVIEW

OpenMedia Mission

AdCOM Executive Summary

ARCHITECTURE

OpenMedia Layers

AdCOM Principles

REGULATORY GUIDANCE

SPECIFICATION

Media Objects

Object: Ad

Object: Display

Object: Banner

Object: Native

Object: Asset

Object: LinkAsset

Object: TitleAsset

Object: ImageAsset

Object: VideoAsset

Object: DataAsset

Object: Event

Object: Video

Object: Audio

Object: Audit

Placement Objects

Object: Placement

Object: DisplayPlacement

Object: DisplayFormat

Object: NativeFormat

Object: AssetFormat

Object: TitleAssetFormat

Object: ImageAssetFormat

Object: DataAssetFormat

Object: EventSpec

Object: VideoPlacement

Object: AudioPlacement

Object: Companion

Context Objects

Abstract Class: DistributionChannel

Object: Site

Object: App

Object: Dooh

Object: Publisher

Object: Content

Object: Producer

Object: User

Object: Device

Object: Geo

Object: Data

Object: Segment

Object: Extended Identifiers

Object: Extended Identifier UIDs

Object: Regs

Object: Restrictions

Enumerations

List: Agent Types

List: API Frameworks

List: Audit Status Codes

List: Category Taxonomies

List: Click Types

List: Companion Types

List: Connection Types

List: Content Contexts

List: Creative Attributes

List: Creative Subtypes - Audio/Video

List: Creative Subtypes - Display

List: Delivery Methods

List: Device Types

List: Display Context Types

List: Display Placement Types

List: DOOH Venue Types

List: Event Tracking Methods

List: Event Types