Open RTB v2.5
Documentation for Bidders
Magnite Technical Operations
26 October 2021 – v2.5.9
This document describes the current implementation of Magnite CTV Open RTB exchange. The reader may see how the selection of objects and fields supported is reflective of Magnite CTV’s goal of strict and rich IAB Open RTB v2. 5 specification compliance: All IAB-required objects and fields are present and populated per the IAB specification. Additionally, this document enumerates which of the recommended and optional fields Magnite CTV supports. For these Magnite CTV-supported recommended and optional fields, each the bid request includes a field when the data-specific supply ad call use case allows.
If an object or field is enumerated below, Magnite CTV supports it as best may be in each bid request, based on available supply-side policies, exchange policies, and/or data availability. Please use this document as an adjunct to the IAB standard when implementing your bidder against the Magnite CTV implementation. Bidders typically see bid requests with a rich complement of IAB-recommended and optional fields for those objects and fields enumerated here as Magnite CTV supported. This is especially the case for IAB-recommended fields.
A key point is that for all non-required IAB fields, bidders should be tolerant of such a field’s presence, or lack thereof, in any one particular bid request.
Magnite CTV’s RTB Exchange offers Desktop Web, Mobile Web, In-App and CTV supply both in
This section provides the full list of IAB Open RTB API Specification Version 2.5-compliant objects that the Magnite CTV Exchange supports, a brief description of each field as well as the format type and an example. RTB Bid Request examples are also included in the end of the document.
Object
Online
Mobile Web
In App
CTV
Bid Object
x
Impression Object
Video Object
Site Object
App Object
Content Object
Publisher Object
Device Object
Geo Object
User Object
Regulations Object
PMP Object
Direct Deals Object
Source
2.1.2 Bid Request Object
Field Name
IAB Open RTB Description
Type
Sample Value
Notes
id
Unique ID of the bid request, provided by the exchange.
String
"3074b60c-0464-4125-a752-136f78c4d00b"
IAB required.
imp
See Impressions Object below
Magnite CTV exchange: Always present.
site
See Site Object below
IAB recommended for websites.
Magnite CTV exchange: Always present for web browser supply. Supply which is being accessed by a mobile device web browser is represented with a Site object.
app
See App Object below
IAB recommended for in application supply.
Magnite CTV exchange: Always present for application supply
device
See Device object below
user
See User object below
IAB recommended.
at
Auction type, where 1 = First Price, 2 = Second Price.
Integer
2
tmax
Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout.
250
Magnite CTV exchange: Currently conducts 250 millisecond auctions (June 2015). Some very small percentage of supply may be offered with tmax as low as 150-160 msecs (June 2019).
wseat
White list of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions.
Array of strings
["test", "DspCo-GP", "testUFRseat"] or ["DspCo-GP"]
cur
Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.
["USD"]
bcat
Blocked advertiser categories using the IAB content categories.
["IAB1-1", "IAB1-2"]
Magnite CTV exchange: Uses IAB categories
badv
Block list of advertisers by their domains
["iloveny.com", "sprite.com"]
regs
See Regulations object below
Impression identifier: A unique identifier for this impression within the context of the bid request
"1"
June 2014: Magnite CTV currently follows the IAB suggestion that "… [this] value starts with 1, and increments up to n for n impressions…"
video
See Video object below
IAB required for video impressions
displaymanager
Name of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner.
"testDisplayManager" or "acudeo"
IAB recommended
displaymanagerver
Version of ad mediation partner, SDK technology, or native player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner
"2.1.04"
bidfloor
Minimum bid for this impression expressed in CPM
Float
9.38
bidfloorcur
Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.
"USD"
instl
Interstitial flag: 1 if the ad is interstitial or full screen; else 0 (i.e., no).
0
Magnite CTV exchange: Always present
tagid
Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging operational issues, or for optimization by the buyer.
secure
Secure creatives required flag: Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.
If omitted, the secure state is unknown, but non-secure HTTP support can be assumed.
exp
Impression Expiration: Advisory as to the number of seconds that may elapse between the auction and the actual impression.
1800
Magnite CTV exchange: For publishers who cache their creatives and associated pixels for later use, the Magnite CTV VMP provides the ability to extend the impression pixel wait time before the pixel expires. Via this field, the bidder is alerted to the fact that the publisher-specific and declared impression pixel expiration time setting within the Magnite CTV console, for the inventory being made available, allowing DSPs to set their pixels with the same value to avoid reporting discrepancies.
ext.viewabilityvendors
Field indicating which viewability vendors’ SDK/tools are integrated with the supply partner for the specific piece of supply offered in the bid request, allowing buyers to include appropriate elements to leverage in the VAST documents returned.
["doubleverify.com ", comscore.com”]
Available options and string values:
o Integral Ad Science: "‘integralads.com” o Comscore “comscore.com” o Sizmek “sizmek.com” o Adform “adform.com” o WhiteOps “whiteops.com” o DoubleVerify “doubleverify.com” o AVID Open Source SDK “avidopensdk.cp," o MOAT “moat.com”
ext.ssai
SSAI type - Indicates if server-side ad insertion 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 = not in use (or not declared). This is the default value. 1 = all client-side, 2 = assets stitched server-side but tracking pixels fired client-side, 3 = all server-side stitching an ad into a video stream
Adopted from OpenRTB v3.0 definition.
pmp
See Private Marketplace Object below
Magnite CTV exchange: Present only if the bid request is an offering under any of the three IAB defined Private Market Plac types:Automated Guaranteed, Unreserved Fixed Rate, or Invitation-Only Auction.
mimes
Content MIME types supported.
["application/x-shockwave-flash", "video/x-flv"] or [ "video/mp4", "application/javascript" ]
minduration
Minimum video ad duration in seconds
maxduration
Maximum video ad duration in seconds
30
IAB recommended. Magnite CTV exchange: Always present.
protocols
Array of supported video protocols.
Array of integers
[2,5]
Magnite CTV exchange: The following are supported by the exchange when supported by the publisher in the bid request. 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
w
Width of the video player in device independent pixels (DIPS).
720
Magnite CTV exchange: Almost always present. The exchange requires publishers/suppliers to provide this value.
h
Height of the video player in device independent pixels (DIPS).
480
startdelay
Indicates the start delay in seconds for preroll, midroll, or postroll ad placement.
linearity
Indicates if the impression must be linear, nonlinear, etc. If none specified, assume all are allowed.
1
“In-stream” or “linear” (value = 1) video refers to pre-roll, post-roll, or mid-roll video ads where the user is forced to watch ad in order to see the video content. “Overlay” or “non-linear” (value = 2) refers to ads that are shown on top of the video content.
placement
Placement type for the impression.
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). Note that a full-screen interstitial (e.g., in mobile) can be distinguished from a floating/slider unit by the imp.instl field.
skip
Skippable Video: Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes. If a bidder sends markup/creative that is itself skippable, the Bid object should include the attr array with an element of 16 indicating skippable video.
skipmin
Skippable video minimum duration: Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable.
15
Magnite CTV exchange: Always present if skip = 1.
skipafter
Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.
7
battr
Blocked creative attributes
maxextended
Maximum extended ad duration if extension is allowed. If blank or 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 maxduration value.
10
minbitrate
15000
maxbitrate
Maximum bit rate in Kbps.
20000
boxingallowed
Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.
playbackmethod
Playback methods that may be in use. If none are specified, any method may be used. Only one method is typically used in practice. As a result, this array may be converted to an integer in a future version of the specification. It is strongly advised to use only the first element of this array in preparation for this change.
[1,2]
delivery
Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported.
Magnite CTV exchange: Where publishers support streaming creative types (e.g. HLS, DASH), indication of streaming delivery is now indicated with this field. In addition to this field, new streaming MIME types may be seen in the available mime list, specifically "application/vnd.apple.mpegurl” for HLS stream, “application/dash+xml” for MPEG-DASH, and "application/vnd.ms-sstr+xml” for Microsoft Smooth Streaming.)
pos
Ad position on screen
api
List of supported API frameworks for this impression. If an API is not explicitly listed, it is assumed not to be supported
Magnite CTV exchange: Supported APIs are: 1 VPAID 1.0 2 VPAID 2.0
Exchange-specific site ID.
"bbea2e39-ad5a-
4211-bfd6-906b4b2ec0e0"
name
Site name (may be aliased at the publisher’s request).
"Magnite CTV TEST SUPPLY site"
domain
Domain of the site (e.g., “mysite.foo.com”).
"Magnite CTV.com"
cat
Array of IAB content categories of the site
Magnite CTV exchange: Uses IAB categories. See the Content Categories list section of the IAB OpenRTB specification for acceptable values.
page
URL of the page where the impression will be shown.
http://www.magnite.com/a/video/page.html
ref
Referrer URL that caused navigation to the current page.
http://www.magnite CTV.com
privacypolicy
Indicates if the site has a privacy policy, where 0 = no, 1 = yes.
publisher
See Publisher Object below
content
See Content Object below
Application ID: Exchange-specific app ID.
" h3vde-ed4sh "
App name
" MusicBox - Audiocaster Radio Music "
May be aliased or masked at the publisher’s request
bundle
A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID.
"com.Magnite CTV.sample"
Magnite CTV exchange: For iOS, a DSP may ask Magnite CTV to send either the iTunes numeric TrackId string or the package name. Please work with Magnite CTV Technical Operations team at magnite-rtb@magnite.com to make your selection.
Domain of the application.
"foo.com"
storeurl
App store URL for an installed app; for IQG 2.1 compliance.
"https://play.google.com/store/apps/details?id=XXXXXXXXX"
Array of IAB content categories of the app.
ver
Application version
string
"1.0.0"
Indicates if the app has a privacy policy, where 0 = no, 1 = yes.
paid
0 = app free, 1 = version.
See Publisher Object
See Content Object
Id
ID uniquely identifying the content
"e31f206a239be5379d639c7fa75183ab"
episode
Episode number.
6
title
Content title.
Video Examples: “Search Committee” (television), “A New Hope” (movie)
series
Content series
Video Examples: “The Office” (television), “Star Wars” (movie)
season
Content season
"Season 3"
genre
Content genre
Genre that best describes the content. Example: “drama”
ext.network
Content network
"BigSportsNetwork"
Extension object to support content network.
This field is relevant to CTV supply and especially CTV/OTT multichannel video programming distributors (“MVNPs”), where these publishers have a number of “channels”, all of which are under a parent Network umbrella branding. See companion field, ext.channel, below. The primary use case for this parameter is for supply from traditional linear TV publisher structures, as may be seen in the examples in the previous column.
ext.channel
Content channel
"BigSportsNetNews"
"BigSportsNetwork2"
"XBCNY4"
Extension object to support content channel.
This field is relevant to CTV supply and especially CTV/OTT multichannel video programming distributors (“MVNPs”). It is used to pass the name of the channel, as the examples in the previous column illustrate.
url
URL of the content, for buy-side contextualization or review.
http://www.videohub.com/the.flv
Array of IAB content categories for the content. See Table 6.1 Content Categories.
prodq
Production quality
In ORTB v2.5, replaces videoquality
videoquality
Video quality per the IAB’s classification. See Table 6.14 Video Quality.
In ORTB v2.5, videoquality deprecated in favor of prodq.
keywords
Comma separated list of keywords describing the content.
contentrating
Content rating (e.g., MPAA).
userrating
User rating of the content (e.g., number of stars, likes, etc.).
"4star"
context
Type of content (game, video, text, etc.).
sourcerelationship
0 = indirect, 1 = direct.
livestream
0 = not live, 1 = content is live (e.g., stream, live blog).
Len
Length of content in seconds; appropriate for video or audio.
embeddable
Indicator of whether or not the content is embeddable (e.g., an embeddable video player), where 0 = no, 1 = yes.
integer
BigSportsNetwork
Extension object to support content network. This field is relevant to CTV supply and especially CTV/OTT multichannel video programming distributors (“MVNPs”), where these publishers have a number of “channels”, all of which are under a parent Network umbrella branding. See companion field, ext.channel, below. The primary use case for this parameter is for supply from traditional linear TV publisher structures, as may be seen in the examples in the previous column.
BigSportsNetNews BigSportsNetwork2 XBCNY4
Extension object to support content channel. This field is relevant to CTV supply and especially CTV/OTT multichannel video programming distributors (“MVNPs”). It is used to pass the name of the channel, as the examples in the previous column illustrate.
Exchange-specific publisher ID.
"TestPublisher"
Publisher name (may be aliased at the publisher’s request).
"Magnite CTV Test Publisher"
Array of IAB content categories that describe the publisher.
Highest level domain of the publisher
ua
Browser user agent string.
"Mozilla/5.0 (Windows NT 6.1; WOW64; rv:30.0) Gecko/20100101 Firefox/30.0"
geo
See Geo Object below
dnt
Do not track: If “0”, then do not track Is set to false, if “1”, then do no track is set to true in browser.
lmt
“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
ip
IPv4 address closest to device.
"64.208.202.10"
IAB recommended. Magnite CTV exchange: All bid requests contain either this field or the ipv6 field.
ipv6
IPv6 address closest to device
“2001:0db8:85a3:0000:0000:8a2e:0370:7334”
Magnite CTV exchange: All bid requests contain either this field or the ip field.
make
Device make (e.g., “Apple”).
“Apple”
model
Device model (e.g., “iPhone”).
“iPhone”
os
Device operating system
"Windows"
osv
"3.1.2"
Physical height of the screen in pixels.
Physical width of the screen in pixels.
flashver
Version of Flash supported by the browser.
language
Browser language using ISO-639-1-alpha-2.
“en”
connectiontype
Network connection type.
dpidsha1
Platform device ID (e.g., Android ID); hashed via SHA1.
"017823bd574b2d39265d12237aad30875a7cf75c"
macsha1
MAC address of the device; hashed via SHA1.
ifa
ID sanctioned for advertiser use in the clear (i.e., not hashed).
" BE269CA1-B1F3-479D-B655-CAE6012AB299”
Magnite CTV exchange: As of September 2017, for CTV supply, this may not always be in the form of the iOS or Android syntax- see second example.
In 2019, as the following iAB specification was finalized in December 2018, Magnite CTV has been evangelizing the adoption of the UUID ifa form, aka “8-4-4-4-12”, to publishers. For full details, please see https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf.
ext.ifa_type
IFA Type: An extension based on the iAB document adoption in December 2018. The following values may be seen: dpid The generic “device provided id”. Useful for when the device is providing the IFA, but isn't covered by one of the more specific values below rida Roku Identifier for Advertisers aaid Android Advertising ID idfa Apple's Identifier for Advertisers afai Amazon Fire Advertising ID msai Microsoft Advertising ID ppid Publisher Provided ID sspid If there is no supply provided ifa, the Magnite CTV VMP synthesizes an ifa value, which is only useful for frequency capping, and the ifa_type is automatically set by the platform to “sspid” sessionid A "session" id that is only relevant for the specific playback session
“sspid”
For full details, please see https://iabtechlab.com/wp-content/uploads/2018/12/OTT-IFA-guidelines.final_Dec2018.pdf.
Magnite CTV exchange:
IMPORTANT - If a DSP would like to receive this extension, please contact Magnite CTV Technical Operations at Magnite-RTB@Magnite CTV.com and request that this extension be enabled.
devicetype
The general type of device
Magnite CTV exchange: The supported values:
1 Mobile/Tablet * Not used in favor of values 4 and 5. 2 Personal Computer 3 Connected TV 4 Phone 5 Tablet 6 Connected Device 7 Set Top Box
2.1.10 Geo Object
lat
Latitude from -90.0 to +90.0, where negative is south.
39.8967
lon
Longitude from -180.0 to +180.0, where negative is west.
-143.8956
type
Source of location data; recommended when passing lat/lon.
IAB recommended 1 GPS/Location Services 2 IP Address 3 User provided (e.g., registration data)
ipservice
Service or provider used to determine geolocation from IP address if applicable (i.e., type = 2).
3
county
Country using ISO-3166-1 Alpha-3.
"USA"
region
Region code using ISO-3166-2; 2-letter state code if USA.
"CA"
metro
Google metro code; similar to but not exactly Nielsen DMAs.
"828"
city
City using United Nations Code for Trade and Transport Locations
"US SRU"
http://www.unece.org/cefact/locode/service/location
zip
Zip/Postal Code
"95060"
Unique consumer ID of this user on the exchange.
"e6f5a0b3181a40
36bcb1178d99428f43"
buyeruid
Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyeruid or id is recommended.
"57839052-49023"
IAB recommended Magnite CTV exchange supplies the ID string assigned by the bidder, if an ID has previously been received in the user ID cookie sync process.
ext.gdpr_consent
Extension used for GDPR consent string: Conveys user consent when GDPR regulations are in effect, containing the data structure developed by the GDPR Consent Working Group under the auspices of IAB Europe.
“BOQfmh_OQfmiAAKACBENBQ-AAAAdt7_______9______9uz_
Gv_v_f__33e8__9v_h_7_-___u_-33d4-_1vX99yPk1-7fNr1tp3c6uWsSJB”
IAB recommended for EEA supply, as if the request is subject to GDPR regulations (i.e., Regs.ext.gdpr = 1). The default sense of consent under GDPR is “opt-out” and as such, an omitted consent string in a request subject to GDPR would need to be interpreted as equivalent to the user fully opting out of all defined purposes for data use by all parties.
Magnite CTV has added an extension to the User object to support the rise of “universal” user buyeruid (aka “synced user ids”). Currently, there is support for the following id services, with more in the planning stages:
If a DSP would like to receive this extension, please contact magnite-rtb@magnite.com and request that this extension be enabled.
eids
Extended Ids: Array of universal / shared ID values
Array
Magnite CTV exchange: IMPORTANT - If a DSP would like to receive this extension, please contact magnite-rtb@magnite.com
eids.source
Source organization: Domain of organization managing the shared id
“adserver.org”
eids.uids
Universal IDs: Array of id values for the user
eids.uids.id
Id for the user
“43f888e1-2941-4b9f-8dc9-1ffb631b7786”
eids.uids.
ext.rtiPartner
Real time ID partner code: Partner code for specific user id ‘family’
“TDID"
Here’s is a complete example of the User Object with an ID Extension:
"user": { "id": "W13bZtHM5KUAAEQRVFsAAAAL", "ext": { "eids": [{ "source": "adserver.org", "uids": [{ "id": "43f888e1-2941-4b9f-8dc9-1ffb631b7786", "ext": { "rtiPartner": "TDID" } }] }] } }
Here's an example of an inbound Liveramp RTB example:
"user": { "ext": { "eids": [{ "source": "liveramp.com", "uids": [{ "id": "XY1000bIVBVah9ium-sZ3ykhPiXQbEcUpn4GjCtxrrw2BRDGM" }] }] } }
2.1.13 Regulations Object
Description
coppa
US FTC COPPA flag: Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.
Magnite CTV exchange: When set to true (=1), the following information is suppressed: · Device IDs(ifa/dpidisha1/dpidmd5): not sent · IP/IPv6: last 8/32 bits zeroed out · Geo info: not sent User info: not sent
ext.gdpr
Extension used for GDPR consent
"gdpr": 0
In an extension object: Signals whether the request is subject to GDPR regulations. · 0=GDPR does not apply · 1=GDPR applies Under OpenRTB conventions for optional attributes, omission indicates Unknown
ext.us_privacy
California Consumer Protection Act (“CCPA”) CCPA flags, as passed by publisher to Magnite CTV
“1YNY”
Magnite CTV exchange: In an extension object: Passed the CCPA string data supplied by a publisher. For more information, please see https://iabtechlab.com/wp-content/uploads/2019/11/U.S.-Privacy-String-v1.0-IAB-Tech-Lab.pdf and https://iabtechlab.com/wp-content/uploads/2019/11/OpenRTB-Extension-U.S.-Privacy-IAB-Tech-Lab.pdf
private_auction
Private transaction flag: Indicator of auction eligibility to seats named in the Direct Deals object, where 0 = all bids are accepted, 1 = bids are restricted to the deals specified
The private_auction field is present and set to 1 for all three IAB PMP marketplace types, indicating that this supply offering is not exposed to all bidders.
deals
See Direct Deals Object below
Array of objects
Deal ID: A unique identifier for the direct deal.
"20140527-FL7483-WK-RB-24702"
IAB required
Deal floor / strike price: Minimum bid for this impression expressed in CPM.
22.8
Currency specified using ISO-4217 alpha codes.
This may be different from bid currency returned by bidder if this is allowed by the exchange.
Auction type: Optional override of the overall auction type of the bid request, where 1 = First Price, 2 = Second Price Plus, 3 = the value passed in bidfloor is the agreed upon deal price. Additional auction types can be defined by the exchange.
Magnite CTV supports no additional auction types beyond the IAB defined types.
Buyer seats allowed: Whitelist of buyer seats (e.g., advertisers, agencies) allowed to bid on this deal. IDs of seats and the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. Omission implies no seat restrictions.
["400000000012-TradingDeskY”, "80000000014-AgencyA”]
wadomain
Advertiser domains allowed: Array of advertiser domains (e.g., advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions.
["iloveny.com", "sprite.com", “advertiser1.com”]
ext.guaranteed
PMP Automated Guaranteed (“AG”)marketplace type flag: Extension, which indicates that the PMP being offered in the Deal object is PMP Automated Guaranteed marketplace type, in contrast to a PMP Unreserved Fixed Rate (“UFR”).
Magnite CTV exchange: IMPORTANT - If a DSP would like to receive this extension, please contact Magnite CTV Technical Operations at magnite-rtb@magnite.com and request that this extension be enabled.
complete
Complete flag: Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes.
iAB required.
nodes
Supply Chain Nodes: Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction, i.e. the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.
See examples below
Version of the supply chain specification in use, in the format of “major.minor”. For example, for version 1.0 of the spec, use the string “1.0”.
Magnite CTV exchange: Magnite CTV supports version 1.0.
Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.
1a4e959a1b50034a:7klg6gdmx0
In ORTB v2.5, pchain is under the source object. For ORTB 2.2, 2.3, 2.4 integrations, pchain is under an extension in the bid object
Final Decision: Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source.
ext.schain
Extension: Supply Chain: For full details, please see https://github.com/InteractiveAdvertisingBureau
/openrtb/blob/master/supplychainobject.md
JSON object
See next section
iAB recommended. Magnite CTV exchange: Magnite CTV requires all publishers to provide these data. For OpenRTB versions 2,2, 2,3 and 2.4, this extension field is found in the base bid request JSON object, i.e. ext.schain
asi
Ad System Id: The canonical domain name of the SSP, Exchange, Header Wrapper, etc. system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists.
sid
Seller Id: The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e. OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id.
rid
Request Id: The OpenRTB Request Id of the request as issued by this seller.
iAB optional.
Seller Name: The name of the company (the legal entity) that is paid for inventory transacted under the given seller_id. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.
Seller Business Domain: The business domain name of the entity represented by this node. This value is optional and should NOT be included if it exists in the advertising system’s sellers.json file.
hp
Handles Payments: Indicates whether this node will be involved in the flow of payment for the inventory. When set to 1, the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to 0, this node is not involved in the flow of payment for the inventory. For version 1.0 of SupplyChain, this property should always be 1. It is explicitly required to be included as it is expected that future versions of the specification will introduce non-payment handling nodes. Implementers should ensure that they support this field and propagate it onwards when constructing SupplyChain objects in bid requests sent to a downstream advertising system.
Here’s is a complete example of the Source Object with an ID Extension:
"bidrequest" : { "id": "BidRequest1", "app": { "publisher": { "id": "00001" } } "source": { "ext": { "schain": { "ver":"1.0", "complete": 1, "nodes": [ { "asi":"directseller.com", "sid":"00001", "rid":"BidRequest1", "hp":1 } ] } } } } "bidrequest" : { "id": "BidRequest2", "app": { "publisher": { "id": "aaaaa" } } "source": { "ext": { "schain": { "ver":"1.0", "complete": 1, "nodes": [ { "asi":"directseller.com", "sid":"00001" "rid":"BidRequest1", "hp":1 }, { "asi":"reseller.com", "sid":"aaaaa", "rid":"BidRequest2", "hp":1 } ] } } } }
2.1 BID RESPONSE DETAILS
Bid request identifier: ID of the bid request to which this is a response.
IAB required. Magnite CTV exchange: Required.
seatbid
Array of seatbid objects; 1or more required if a bid is to be made.
bidid
Bidder generated response ID to assist with logging/tracking.
Bid currency using ISO-4217 alphabetic codes
“USD”
Magnite CTV exchange: Required. If more than one currency was allowed in the bid request. If USD was only currency allowed in the bid request, this is the only case where USD is assumed. Best practice: Always send a currency even if only USD is supported by bidder.
nbr
Reason for not bidding
Use reason codes in the IAB specification
bid
Array of 1 or more Bid objects (Section 4.2.3) each related to an impression. Multiple bids can relate to the same impression.
seat
ID of the bidder seat on whose behalf this bid is made.
Magnite CTV exchange: Strongly encourages bidders to include this field in all bid responses. This data is helpful to the Magnite CTV operations team when working with a bidder in investigation of creative and/or other issues.
2.2.2 Bid Object
Bidder generated bid ID to assist with logging/tracking.
impid
ID of the Imp object in the related bid request.
price
Bid price expressed as CPM although the actual transaction is for a single unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java).
nurl
Win notice URL called by the exchange if the bid wins (not necessarily indicative of a delivered, viewed, or billable ad); optional means of serving ad markup. Substitution macros may be included in both the URL and optionally returned markup.
Magnite CTV exchange: Check WINNER NOTIFICATION section below for details
adm
Optional means of conveying ad markup in case the bid wins; supersedes the win notice if markup is included in both. Substitution macros (Section 4.4) may be included.
adid
ID of a preloaded ad to be served if the bid wins.
adomain
Advertiser domain for block list checking (e.g., “ford.com”). This can be an array of for the case of rotating creatives. Exchanges can mandate that only one domain is allowed.
Array of stings
Magnite CTV exchange: As of 25 April 2016, this field is required in all bid responses. Please note that the value should be reflective of the actual advertiser, which may not be the domain of the click-thru URL.
Iurl
URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.
Magnite CTV exchange: Strongly encourages bidders to include this field in all bid responses.
cid
Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
crid
Creative ID to assist with ad quality checking.
Magnite CTV exchange: As of 25 April 2016, this field is required in all bid responses.
attr
Set of attributes describing the creative.
dealid
Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal.
Magnite CTV exchange: For PMP responses, the Bid object dealid must be included, as is required in this case by the IAB.
As of 25 April 2016, these fields are required in all bid responses. Magnite CTV actively enforces the return of an accurate adomain in the bid response.
Bidders are strongly encouraged to include in the Bid object the fields, cid, iurl and attr, as these may be used as the IAB describes in section 4.3.3 of the OpenRTB v2.2 specification. Your inclusion of these fields helps us work with you to maintain an efficient exchange. From the IAB specification, section 4.3.3 Bid Object
The “adomain” attribute can be used to check advertiser block list compliance. The “iurl” attribute can provide a link to an image that is representative of the campaign’s content (irrespective of whether the campaign may have multiple creatives). This enables human review for spotting inappropriate content. The “cid” attribute can be used to block ads that were previously identified as inappropriate; essentially a safety net beyond the block lists. The “crid” attribute can be helpful in reporting creative issues back to bidders. Finally, the “attr” array indicates the creative attributes that describe the ad to be served.
The Magnite CTV platform allows GZIP-ed bid responses from all DSP bidders. All bid requests indicate this by including the Accept-Encoding:gzip in the HTTP headers.
If you would like Magnite CTV to send bid requests that are GZIP encoded, please let us know via email to magnite-RTB@magnite.com and Magnite CTV Technical Operations will enable that for your bidder.
Magnite CTV Open Auctions are first or second price auctions.
Magnite CTV PMP Invitation-Only Auctions (“IOA”) are either first or second-price auctions. The 'at' field is useful to detect this.
For PMP Deals, the Magnite CTV exchange expects the agreed deal price returned in the PMP bid responses under the price field. Magnite CTV sees the return of the agreed to strike price in the bid response as an” acknowledgement” of the strike price, which was presented in the bid request in the bidfloor field in the Deal object. This is a check against human or machine error.
Magnite CTV supports delivery of markup via either the adm or nurl methods, following the details specified in IAB OpenRTB spec v2.5, section 4.3 Ad Serving Options.
Magnite CTV supports the provision of a nurl in the bid response both:
After determining the winning bidder, and in case the nurl field is included in the winning bidder’s response, Magnite CTV sends a Win Notice. This serves as a record of when a Bidder won an auction, thereby helping bidders achieve a better accounting of the wins, separate from impressions.
The Win Notice is a HTTP GET request, sent to Win Notice URL, supplied in the bid response. It is important for a bidder to note that when a nurl is supplied in a bid response, for either of these purposes, markup delivery and/or simple win notification (with markup delivered in the adm with the bid response), the Magnite CTV exchange makes the HTTP call from the Magnite CTV exchange server. Thus, the HTTP call is decorated with headers, IP address, etc., which are reflective of the server in the exchange – NOT the original client user equipment / browser, which made the original supply side ad call to the exchange. In other words, the nurl, if supplied, is called as a server-to-server call. This is a highly reliable call, which is in no way dependent on the actual delivery and/or rendering of the creative markup on the supply.
If the Ad Markup is not supplied under the adm field in the Bid Response, Magnite CTV expects the raw ad markup in the response body of the win notice call. Magnite CTV’s Exchange sends win notifications to winning bidders but does not guarantee the delivery for these notifications.
If an error occurs during the transmission of a Win Notice, the exchange does not retransmit the Win Notice to that winning bidder. In this error case, the winning bidder may not receive the Win Notice.
Magnite CTV’s platform supports the synchronization of Magnite CTV’s internal user IDs with demand partner-assigned user ID strings. The Magnite CTV system does this via a HTTP call which is separate from the auction process, for those users which do not already have a demand partners ID stored in a cookie on the user equipment (“new users for demand partner”). Upon receipt of this HTTP call, the demand partner may then assign a user ID string of its choosing and return that to the Magnite CTV platform. This demand partner-assigned user ID will then be presented to the demand partner in all future auctions for supply from this user.
Magnite CTV provides this synchronization opportunity to RTB demand partners for all supply ad calls regardless of whether the demand partner bids on and/or wins an auction for an impression opportunity from a “new user”.
For EEA supply that is subject to GDPR, the Magnite CTV platform only user ID syncs on supply for which Magnite CTV has received GDPR consent.
Magnite CTV’s RTB platform supports the substitutions of all the following macros:
Macro
${AUCTION_ID}
ID of the bid request; from BidRequest.id attribute.
${AUCTION_BID_ID}
ID of the bid; from BidResponse.bidid attribute.
${AUCTION_IMP_ID}
ID of the impression just won; from imp.id attribute.
${AUCTION_SEAT_ID}
ID of the bidder seat for whom the bid was made.
${AUCTION_AD_ID}
ID of the ad markup the bidder wishes to serve; from bid.adid attribute.
${AUCTION_PRICE}
Clearing price using the same currency and units as the bid.
${AUCTION_CURRENCY}
The currency used in the bid (explicit or implied); for confirmation only.
On GDPR effective date of 25 May 2018, Magnite CTV’s SSP provided DSPs with the following alternatives:
{ "cur": [ "USD" ], "site": { "privacypolicy": 1, "ref": "https://www.referredURL.com/", "domain": "domain.com", "name": "site name", "publisher": { "domain": "publisher.com", "name": "Publisher name", "id": "111wm" }, "id": "11111-x8k98", "page": "https://www.page.com", "content": { "prodq": 0, "title": "content title", "url": "//videourl.com/vid/filename.mp4", "livestream": 0 } }, "at": 1, "tmax": 250, "bcat": [ "IAB11-4" ], "regs": { "ext": { "us_privacy": "1---" }, "coppa": 0 }, "id": "1869446b-865c-4c70-b054-0906c30c5b07", "source": { "ext": { "schain": { "complete": 0, "nodes": [ { "asi": "telaria.com", "sid": "111wm", "hp": 1 } ], "ver": "1.0" } }, "pchain": "1111159a1b50034a:gklfs5h375", "fd": 1 }, "imp": [ { "tagid": "11111-5h375", "id": "1", "video": { "boxingallowed": 1, "maxextended": 0, "linearity": 1, "h": 393, "skip": 0, "playbackmethod": [ 2 ], "minduration": 5, "mimes": [ "video/mp4", "application/javascript" ], "maxduration": 60, "pos": 1, "w": 700, "startdelay": 0, "api": [ 2 ], "placement": 4, "protocols": [ 2, 3, 7, 5, 6, 8 ] }, "secure": 1, "exp": 300, "instl": 0 } ], "device": { "geo": { "zip": "04011", "country": "USA", "metro": "500", "ipservice": 3, "utcoffset": -300, "lon": -69.9817, "region": "ME", "type": 2, "lat": 43.8971 }, "osv": "10.15", "os": "os x", "ip": "169.244.94.222", "language": "en", "dnt": 0, "ua": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/93.0.4577.82 Safari/537.36", "devicetype": 2 }, "user": { "ext": { "eids": [ { "uids": [ { "ext": { "rtiPartner": "extuserid" }, "id": "11111111-3722-4f11-b42d-163541836349" } ], "source": "source.org" } ] }, "buyeruid": "1111111111997840e9a79c79fb8d807820", "id": "1111111111119450eb5c2b7018dea16f4" } }
PMP CTV Bid Request
{ "app": { "privacypolicy": 1, "domain": “domain.com ", "name": "app name", "paid": 0, "publisher": { "domain": "domain.com", "name": "pub", "id": "pubpu" }, "id": "11111-pvq8u", "bundle": "bundleiDexample.ott", "content": { "prodq": 1, "livestream": 0 } }, "cur": [ "USD" ], "at": 2, "tmax": 250, "bcat": [ "IAB7-3", "IAB23", "IAB26-1", "IAB7-28", "IAB7-39" ], "regs": { "ext": {}, "coppa": 0 }, "id": "11111111-e4e6-4fc0-bdda-77c31d745362", "source": { "ext": { "schain": { "complete": 1, "nodes": [ { "asi": "telaria.com", "rid": "11111111-e4e6-4fc0-bdda-77c31d745362", "sid": "pubpu", "hp": 1 } ], "ver": "1.0" } }, "pchain": "111111111b50034a:s7kc92fexu", "fd": 0 }, "imp": [ { "ext": { "ssai": 3 }, "pmp": { "deals": [ { "at": 2, "bidfloor": 11.1, "bidfloorcur": "USD", "id": "IOA-test-dealID" }, { "at": 3, "bidfloor": 15., "bidfloorcur": "USD", "id": "UFR-test-dealID" } ], "private_auction": 1 }, "tagid": "11111-2fexu", "displaymanager": "mobiletag", "displaymanagerver": "1.0", "id": "1", "video": { "boxingallowed": 1, "battr": [ 11, 16 ], "maxextended": 0, "linearity": 1, "minbitrate": 0, "h": 450, "skip": 0, "playbackmethod": [ 3 ], "minduration": 5, "mimes": [ "video/mp4" ], "maxbitrate": 2500, "maxduration": 31, "w": 800, "startdelay": -1, "placement": 1, "protocols": [ 2, 3, 5, 6 ] }, "secure": 1, "exp": 7200, "instl": 0 } ], "device": { "ext": { "ifa_type": "sspid" }, "os": "tizen", "ifa": "11111111-5885-4d70-ba25-6424c12b52cc", "ip": "55.555.555.230", "language": "en", "dnt": 0, "ua": "Mozilla/5.0 (SMART-TV; LINUX; Tizen 3.0) AppleWebKit/538.1 (KHTML, like Gecko) Version/3.0 TV Safari/538.1,gzip(gfe),gzip(gfe)", "devicetype": 3, "geo": { "zip": "3088", "country": "AUS", "metro": "0", "ipservice": 3, "utcoffset": 600, "lon": 145.1231, "region": "VIC", "type": 2, "lat": -37.7041 }, "lmt": 0, "osv": "3.0", "model": "Tizen TV", "make": "Samsung", "dpidsha1": "111111c54c5c701d15c998741ac78d1f69fad613" }, "wseat": [], "badv": [ "blockedadomain.au", "blockedadomain2.com" ] }
{ "id": "4696e8f5-3253-4120-aa66-9ea7ff3cefaa", "seatbid": [ { "bid": [ { "id": "1", "impid": "1", "price": 38.4, "adid": "111119NUSA", "adm": "<VAST version=\"2.0\">\n <Ad id………………………………..\n</VAST>", "adomain": [ "adomain.com" ], "cid": "11111Uk5aj", "crid": "111119NUSA", "cat": [ "IAB7" ], "dealid": "IOA-testdealID" } ], "seat": "111119yqeh", "group": 0 } ], "bidid": "TFWeZvDLEB", "cur": "USD" }
{ "id": "b38326ce-e4e6-4fc0-bdda-77c31d745362", "seatbid": [ { "bid": [ { "id": "1", "impid": "1", "price": 43.484722, "adm": "<VAST version='3.0'><Ad id=……………………………</VAST>", "nurl": "https://testnurl.com", "cid": "j483f60", "crid": "pes4f88d", "adomain": [ "adomain.com" ], "dealid": "UFR-testdealID", "cat": [ "IAB20", "IAB20-4" ] } ], "seat": "1111" } ], "cur": "USD" }
Copyrights
This documentation and related technology is the sole and exclusive property of Magnite CTV, Inc.("Magnite CTV"). Unless otherwise agreed to in writing by Magnite CTV, no part of this documentation or related technology may be used, reproduced, displayed, distributed, disclosed, stored or transmitted in any form or by any means. The information contained in this documentation is confidential
Disclaimer
The information provided in this documentation is subject to change at any time. Magnite CTV does not warrant, guarantee or make any representations concerning the contents of this documentation or its applicability for any purpose. This documentation does not create any legally enforceable obligations on the part of Magnite CTV.