/** * 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. */ syntax = "proto2"; import "google/protobuf/any.proto"; import "com/iabtechlab/adcom/v1/enums/enums.proto"; package com.iabtechlab.adcom.v1.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 block lists, language, secure status, etc. apply to all media types and native * assets as applicable). */ message Placement { // Identifier for specific ad placement or ad tag; unique within a distribution channel. optional string tagid = 1; // 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 1 = all client-side, // 2 = assets stitched server-side but tracking pixels fired client-side, 3 = all server-side. // Default = 0. optional int32 ssai = 2; // 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. optional string sdk = 3; // Version of the SDK specified in the "sdk" attribute. optional string sdkver = 4; // Indicates if this is a rewarded placement, where 0 = no, 1 = yes. Default = 0. optional bool reward = 5; // Allowlist 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 a priori. Omission of this attribute indicates there are no // restrictions. repeated string wlang = 6; // 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. optional int32 secure = 7; // Indicates if including markup is supported (i.e., the various "ad" attributes throughout the // "Placement" structure), where 0 = no, 1 = yes. optional int32 admx = 8; // Indicates if retrieving markup via URL reference is supported (i.e., the various "curl" // attributes throughout the "placement" structure), where 0 = no, 1 = yes. optional int32 curlx = 9; // 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 is required. optional DisplayPlacement display = 10; // 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 is required. optional VideoPlacement video = 11; // 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 is required. optional AudioPlacement audio = 12; // Optional vendor-specific extensions. extensions 100 to 9999; /** * 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. */ message DisplayPlacement { // Placement position on screen. // Refer to List: com.iabtechlab.adcom.v1.enums.PlacementPosition. optional int32 pos = 1; // Inidicates if this is an interstitial placement, where 0 = no, 1 = yes. Default 0. optional int32 instl = 2; // 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. optional int32 topframe = 3; // Array of iframe busters supported by this placement. The meaning of strings in this attribute // must be coordinated a priori among vendors. repeated string ifrbust = 4; // Indicates the click type of this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.ClickType. optional int32 clktype = 5; // AMPHTML rendering treatment for AMP ads in this placement, where 1 = early loading, // 2 = standard loading. optional int32 ampren = 6; // Recommended. The display placement type. // Refer to List: com.iabtechlab.adcom.v1.enums.DisplayPlacementType. optional int32 ptype = 7; // Recommended. The context of the placement. // Refer to List: com.iabtechlab.adcom.v1.enums.DisplayContextType. optional int32 context = 8; // Array of supported mime types (e.g., "image/jpeg", "image/gif"). If omitted, all types are // assumed. repeated string mime = 9; // List of supported APIs. If an API is not explicitly listed, it is assumed to be unsupported. // Refer to List: com.iabtechlab.adcom.v1.enums.APIFramework. repeated int32 api = 10; // Creative subtypes permitted. // Refer to List: com.iabtechlab.adcom.v1.enums.Creative.DisplayType. repeated int32 ctype = 11; // 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.). optional int32 w = 12; // 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.). optional int32 h = 13; // Unit of size used for placement size (i.e., "w" and "h" attributes). Default = 1. // Refer to List: com.iabtechlab.adcom.v1.enums.SizeUnit. optional int32 unit = 14 [default = 1]; // Indicator of whether or not the placement supports a buyer-specific privacy notice URL, // where false = no, true = yes. Default is false. optional bool priv = 15; // Array of objects that govern the attributes (e.g., sizes) of a banner display placement. // Note that including both "displayfmt" and "nativefmt" is not recommended. // Refer to Object: DisplayFormat. repeated DisplayFormat displayfmt = 16; // This object specified the required and permitted assets and attributes of a native display // placement. Note that including both "displayfmt" and "nativefmt" is not recommended. // Refer to Object: NativeFormat. optional NativeFormat nativefmt = 17; // Array of supported ad tracking events. // Refer to Object: EventSpec repeated EventSpec event = 18; // Optional vendor-specific extensions. extensions 100 to 9999; /** * This object represents an allowed set of parameters for a banner display ad and often appears * as an array when multiple sizes are permitted. */ message DisplayFormat { // Absolute width of the creative in units specified by "DisplayPlacement.unit". // Note that mixing absolute and relative sizes is not recommended. optional int32 w = 1; // Absolute hight of the creative in units specified by "DisplayPlacement.unit". // Note that mixing absolute and relative sizes is not recommended. optional int32 h = 2; // Relative width of the creative when expressing size as a ratio. // Note that mixing absolute and relative sizes is not recommended. optional int32 wratio = 3; // Relative height of the creative when expressing size as a ratio. // Note that mixing absolute and relative sizes is not recommended. optional int32 hratio = 4; // Directions in which the creative is permitted to expand. // Refer to List: com.iabtechlab.adcom.v1.enums.ExpandableDirection. repeated int32 expdir = 5; // Optional vendor-specific extensions. extensions 100 to 9999; } /** * 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. */ message NativeFormat { // Array of objects that specify the set of native assets and their permitted formats. // Refer to Object: AssetFormat. repeated AssetFormat asset = 1; // Optional vendor-specific extensions. extensions 100 to 9999; /** * 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. */ message AssetFormat { // Asset ID, unique within the scope of this placement specification. optional int32 id = 1; // Indicator of whether or not this asset is required. optional bool req = 2; // The specific asset format that provides additional asset forma detail. oneof asset_oneof { TitleAssetFormat title = 3; ImageAssetFormat img = 4; VideoPlacement video = 5; DataAssetFormat data = 6; } // Optional vendor-specific extensions. extensions 100 to 9999; /** * This object is used to provide native asset format specifications for a title element. * Title elements are simple strings. */ message TitleAssetFormat { // Required. The maximum allowed length of the title value. Recommended lengths are 25, // 90, or 140. optional int32 len = 1; // Optional vendor-specific extensions. extensions 100 to 9999; } /** * This object is used to provide native asset format specifications for an image element. * Image elements are typically used for actual creative image and icons. */ message ImageAssetFormat { // The type of image asset supported. // Refer to List: com.iabtechlab.adcom.v1.enums.NativeImageAssetType. optional int32 type = 1; // Array of supported mime types (e.g., "image/jpeg", "image/gif"). If omitted, all types // are assumed. repeated string mime = 2; // Absolute width of the image asset in device independent pixels (DIPS). // Note that mixing absolute and relative sizes is not recommended. optional int32 w = 3; // Absolute height of the image asset in device independent pixels (DIPS). // Note that mixing absolute and relative sizes is not recommended. optional int32 h = 4; // The minimum requested absolute width of the image in device independent pixels (DIPS). // This option should be used for any scaling of the images by the client. optional int32 wmin = 5; // The minimum requested absolute height of the image in device independent pixels (DIPS). // This option should be used for any scaling of the images by the client. optional int32 hmin = 6; // Relative width of the image asset when expressing size as a ratio. // Note that mixing absolute and relative sizes is not recommended. optional int32 wratio = 7; // Relative height of the image asset when expressing size as a ratio. // Note that mixing absolute and relative sizes is not recommended. optional int32 hratio = 8; // Optional vendor-specific extensions. extensions 100 to 9999; } /** * 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. */ message DataAssetFormat { // The type of data asset supported. // Refer to List: com.iabtechlab.adcom.v1.enums.NativeDataAssetType. optional int32 type = 1; // The maximum allowed length of the data value. optional int32 len = 2; // Optional vendor-specific extensions. extensions 100 to 9999; } } } /** * 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. */ message EventSpec { // Required. Type of supported ad tracking event. // Refer to List: com.iabtechlab.adcom.v1.enums.EventType. optional int32 type = 1; // Array of supported event tracking methods for this event type. // Refer to List: com.iabtechlab.adcom.v1.enums.EventTrackingMethod. repeated int32 method = 2; // Event tracking APIs available for us; only relevant for JavaScript method trackers. // Refer to List: com.iabtechlab.adcom.v1.enums.APIFramework. repeated int32 api = 3; // Array of domains, top two levels only (e.g., "tracker.com"), that constitutes a restriction // list of JavaScript trackers. The sense of restrictions is determined by "wjs". repeated string jstrk = 4; // Sense of the "jstrk" restriction list, where false = blocklist, true = allowlist. // Default = true. optional bool wjs = 5 [default = true]; // 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". repeated string pxtrk = 6; // Sense of the "pxtrk" restriction list, where false = blocklist, true = allowlist. // Default = true. optional bool wpx = 7 [default = true]; // Optional vendor-specific extensions. extensions 100 to 9999; } } /** * This object signals that the placement may be a video placement and provides additional detail * about permitted video ads (e.g., VAST). */ message VideoPlacement { // Placement subtype. // Refer to List: com.iabtechlab.adcom.v1.enums.VideoPlacementSubtype. optional int32 ptype = 1; // Placement position on screen. Refer to List: com.iabtechlab.adcom.v1.enums.PlacementPosition. optional int32 pos = 2; // 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. optional int32 delay = 3; // Indicates if the placement imposes ad skippability, where false = no, true = yes. optional bool skip = 4; // The placement allows creatives of total duration greater than this number of seconds to be // skipped; only applicable if the ad is skippable. // Default = 0. optional int32 skipmin = 5; // Number of seconds a creative must play before the placement enables skipping; only // applicable if the ad is skippable. // Default = 0. optional int32 skipafter = 6; // Playback method in use for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.PlaybackMethod. optional int32 playmethod = 7; // The event that causes playback to end for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.PlaybackCessationMode. optional int32 playend = 8; // Indicates the click type of the placement. // Refer to List: com.iabtechlab.adcom.v1.enums.ClickType. optional int32 clktype = 9; // Array of supported mime types (e.g., "video/mp4"). If omitted, all types are assumed. // Required. repeated string mime = 10; // List of supported APIs for this placement. If an API is not explicitly listed, it is // assumed to be unsupported. // Refer to List: com.iabtechlab.adcom.v1.enums.APIFramework. repeated int32 api = 11; // Creative subtypes permitted for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.Creative.AudioVideoType. repeated int32 ctype = 12; // Width of the creative in units specified by "unit". optional int32 w = 13; // Height of the creative in units spcified by "unit". optional int32 h = 14; // Units of size used for "w" and "h" attributes. // Refer to List: com.iabtechlab.adcom.v1.enums.SizeUnit. // Default = 1. optional int32 unit = 15 [default = 1]; // Minimum creative duration in seconds. optional int32 mindur = 16; // Maximum creative duration in seconds. optional int32 maxdur = 17; // 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. // Default = 0. optional int32 maxext = 18; // Minimum bit rate of the creative in Kbps. optional int32 minbitr = 19; // Maximum bit rate of the creative in Kbps. optional int32 maxbitr = 20; // Array of supported creative delivery methods. If omitted, all can be assumed. // Refer to List: com.iabtechlab.adcom.v1.enums.DeliveryMethod. repeated int32 delivery = 21; // The maximum number of ads that can be played in an ad pod. optional int32 maxseq = 22; // Indicates if the creative must be linear, nonlinear, etc. If none specified, no restrictions // are assumed. // Refer to List: com.iabtechlab.adcom.v1.enums.LinearityMode. optional int32 linear = 23; // Indicates if letterboxing of 4:3 creatives into a 16:9 window is allowed, where false = no, // true = yes. // Default = true. optional bool boxing = 24 [default = true]; // Array of objects indicating that companion ads are available and providing the // specifications thereof. // Refer to Object: Companion. repeated Companion comp = 25; // Supported companion ad types; recommended if companion ads are specified in "comp". // Refer to List: com.iabtechlab.adcom.v1.enums.CompanionType. repeated int32 comptype = 26; // Optional vendor-specific extensions. extensions 100 to 9999; } /** * This object signals that the placement may be an audio placement and provides additional * detail about permitted audio ads (e.g., DAAST). */ message AudioPlacement { // 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. optional int32 delay = 1; // Indicates if the placement imposes ad skippability, where false = no, true = yes. optional bool skip = 2; // The placement allows creatives of total duration greater than this number of seconds to be // skipped; only applicable if the ad is skippable. // Default 0. optional int32 skipmin = 3; // Number of seconds a creative must play before the placement enables skipping; only // applicable if the ad is skippable. optional int32 skipafter = 4; // Playback method in use for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.PlaybackMethod. optional int32 playmethod = 5; // The event that causes playback to end for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.PlaybackCessationMode. optional int32 playend = 6; // Type of audio feed for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.FeedType. optional int32 feed = 7; // Volume normalization mode of this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.VolumeNormalizationMode. optional int32 nvol = 8; // Array of supported mime types (e.g., "audio/mp4"). If omitted, all types are assumed. // Required. repeated string mime = 9; // List of supported APIs for this placement. If an API is not explicitly listed, it is assumed // to be unsupported. // Refer to List: com.iabtechlab.adcom.v1.enums.APIFramework. repeated int32 api = 10; // Creative subtypes permitted for this placement. // Refer to List: com.iabtechlab.adcom.v1.enums.Creative.AudioVideoType. repeated int32 ctype = 11; // Minimum creative duration in seconds. optional int32 mindur = 12; // Maximum creative duration in seconds. optional int32 maxdur = 13; // 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. optional int32 maxext = 14; // Minimum bit rate of the creative in Kbps. optional int32 minbitr = 15; // Maximum bit rate of the creative in Kbps. optional int32 maxbitr = 16; // Array of supported creative delivery methods. If omitted, all can be assumed. // Refer to List: com.iabtechlab.adcom.v1.enums.DeliveryMethod. repeated int32 delivery = 17; // The maximum number of ads that can be played in a pod. optional int32 maxseq = 18; // Array of objects indicating that companion ads are available and providing the // specifications thereof. // Refer to Object: Companion. repeated Companion comp = 19; // Supported companion ad types; recommended if companion ads are specified in "comp". // Refer to List: com.iabtechlab.adcom.v1.enums.CompanionType. repeated int32 comptype = 20; // Optional vendor-specific extensions. extensions 100 to 9999; } /** * 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. */ message Companion { // Identifier of the companion ad; unique within this placement. optional string id = 1; // 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. optional int32 vcm = 2; // Display specification object representing the companion ad. // Refer to Object: DisplayPlacement. optional DisplayPlacement display = 3; // Optional vendor-specific extensions. extensions 100 to 9999; } }