MoPub
  1. DSPs
  2. Integration
  3. MoPub OpenRTB 2.3 Integration Guide

MoPub OpenRTB 2.3 Integration Guide

Important: Please review the changelog periodically for updates!

1. Overview

Summary

This doc serves as an integration guide and FAQ for our OpenRTB 2.3 + Native ads integration. Please consult the document on the demand support center and the changelog at the bottom of this guide for the latest updates.

If there is a conflict between this integration guide and your existing agreements with MoPub and Twitter, your agreements supersede this guide document.

Basic Auction on the MoPub Exchange

  1. MoPub receives an ad request from a mobile device.
  2. MoPub makes an http POST request to all partner bidder http endpoints. Each bidder must respond within the number of miliseconds passed in the bidrequest.tmax field.
  3. MoPub runs a second price auction based on all the valid responses from the bidders.
  4. MoPub pings the winning bidder’s nurl(s) to notify the DSP of a win
  5. MoPub sends down the winning bid’s HTML and imptrackers to the client
  6. The mobile device pings the imptrackers url(s) after the ad markup is rendered.

See section 2.4 for more information on nurls and impression tracking

IMPORTANT: All fields will be populated in the bid request if available. We will never pass null values or empty strings. If noted as not always passed, that parameter may not always be present in the bid request. For example, if the request doesn’t contain an SDK version, we will omit ver from the request.

It’s possible that an attribute is marked “not always passed” when there is a very low probability of this happening, e.g., country is passed >99% of the time.

2. Important Integration Notes

Note: It is highly recommended that you read this section in full before you begin integration testing.

2.1 Key Changes from RTB 2.1

Below represents the full set of changes from the MoPub 2.1 spec to MoPub 2.3. There are 4 categories. This is meant to be a checklist for integrations. Please refer to below tables and OpenRTB 2.3 spec for further descriptions on the fields.

  • [New]
  • [Updated]
  • [Moved]
  • [Removed]

RTB Request

  • wseat - [Removed]
  • regs - [New]
  • regs.coppa - [New]
  • regs.ext.gdpr - [New]
  • ext.pchain - [New]
  • imp.native - [New]
  • imp.secure - [New]
  • imp.pmp - [New] - note this is new from the original 2.1 spec but was implemented prior to 2.3 update
  • imp.ext.dlp - [New]
  • imp.ext.brsrclk - [New]
  • imp.banner.ext.nativebrowserclick - [Removed]
  • imp.banner.ext.video - [Removed]
  • imp.banner.ext.native - [Removed]
  • imp.banner.ext.nativead - [Removed]
  • imp.video.protocol - [Removed]
  • imp.video.companiontype - [New]
  • device.devicetype - [Updated]
  • device.lmt - [New]
  • device.dpidmd5 - [Updated] - deprecating
  • device.dpidsha1 - [Updated] - deprecating
  • device.h - [New]
  • device.w - [New]
  • device.model - [Updated]
  • device.hwv - [New]
  • device.ifa - [Moved]
  • device.geo.region - [Updated]
  • user.ext.consent - [New]

RTB Response

  • nbr - [New]
  • seatbid.bid.nurl - [Updated]
  • seatbid.bid.bundle - [New]
  • seatbid.bid.cat - [New]
  • seatbid.bid.h - [New]
  • seatbid.bid.w - [New]
  • seatbid.bid.dealid - [New] note this is new from the original 2.1 spec but was implemented prior to 2.3 update
  • seatbid.bid.ext.nurls - [New] (nurl array)
  • seatbid.bid.ext.imptrackers - [New]
  • seatbid.bid.ext.crtype - [Moved]
  • seatbid.bid.ext.native - [Removed]
  • seatbid.bid.ext.video - [Removed]
  • seatbid.bid.ext.duration - [Moved]
  • seatbid.bid.ext.video.type - [Removed]
  • seatbid.bid.ext.video.linearity - [Removed]

2.2 Note regarding OpenRTB 2.2 bidders

Any OpenRTB 2.2 compliant bidder should have no issues integrating to the MoPub 2.3 specification. Below represents a few important nuances to note for anyone on 2.2:

  1. bidrequest.device.lmt is new in 2.3 – please ensure that you still ingest the dnt flag properly as that will always be set when lmt=1
  2. OpenRTB native support is only in v2.3 – you must upgrade to 2.3 if you want to continue bidding on native ads
  3. bidresponse.seatbid.bid.bundle is preferred when bidding with app advertisers, understood that this will not be present on 2.2 bidders
  4. bidresponse.seatbid.bid.cat – required for the advertiser category checking

2.3 Note regarding DNT, COPPA and behavioral targeting

  • Previously we set dnt=1 as a global identifier for ‘do not track’ signaling to the bidder to not behaviorally target a user per OBA guidelines.
  • With the fields introduced in OpenRTB 2.2 & 2.3, MoPub will be updating our request to signal the following:
    • dnt = 1 will still always be set as before to ensure all bidders comply
    • lmt = 1 will be set when the mobile limit ad tracking is set on an Android or iOS device
    • bidrequest.regs.coppa = 1 will be set when the user is known to be a child under the age of 13, or the app is a child directed application

2.4 nurl and impression tracking updates

MoPub is making some important changes in the RTB 2.3 implementation to more closely align to the OpenRTB standard & introduce new ways for bidders to consistently track impressions for themselves and 3rd parties. As of this release, the following will be available:

  1. bidresponse.seatbid.bid.nurl - this is an optional variable to notify a bidder when they won the auction. This does not guarantee that an impression is served, nor does MoPub charge when this tracker is sent
    • The previous behavior for nurl was charging on this tracker and sending nurl client side. nurl is now sent server side.
  2. bidresponse.seatbid.bid.ext.nurls[] - this new optional extension field allows a bidder to submit multiple nurl trackers to optionally notify 3rd parties of the win. (note that if both nurl and the array are provided, we will only use what is present in the array field)
    • Note: nurl is sent server side
  3. bidresponse.seatbid.bid.ext.imptrackers[] - this new extension field allows a bidder to submit 1 or more impression trackers that will be sent on the impression / charge event for the ad. This is required in the RTB 2.3 bid response. Leveraging this field will ensure bidders (and 3rd parties) minimize discrepancies with MoPub’s invoices.
    • The logic for sending trackers in this field is identical to how MoPub used to send nurl trackers in RTB 2.1
    • This does not apply for native. Bidders are required to use the native.imptrackers array to submit impression trackers instead.

2.5 multiple bid responses and multiple seat bids

DSPs are encouraged to send multiple bids for each seat represented in the bid response. These are collected in the bid array in the seatbid object. We consider all bids from all seats, exclude the ones that do not match blocklist or are invalid, and take the highest of the remaining eligible bids across each seat.

bidresponse.seatbid.seat technical requirements:

  • Alphanumeric (azAZ09)
  • Max length of 40 characters
  • Ideally min 8 characters

Note: We currently support only 1 impression per auction, so these bids would all be competing for that single impression.

2.6 Click tracking extensions (Native browser clicks & Deep Link+)

2.6.1 Native Browser Clicks

Partners may choose to use the native browser click functionality supported by the MoPub SDK where the click url will be opened in the device native browser instead of the in app webview.

You can target this functionality via the imp.ext.brsrclk field on the request (note: this is moved / changed from imp.banner.ext.nativebrowserclick since it is supported for video and native as well). If set to 1 it is supported by the requesting SDK.

In the creative returned in the adm field, this behavior can be triggered by setting the click through URL in the following format using a custom URI pattern (this custom URI will open the URL in the native OS browser):

mopubnativebrowser://navigate?url=[URL_ENCODED_CLICKTHROUGH_URL]

IMPORTANT: Ensure that ‘http://’ or ‘https://’ is included in the intended landing page URL.

For more information and examples, see here.

Starting in MoPub’s SDK version 3.9, we standardized an improved approach to submitting deep links that ensure a better end user experience + improved buy-side tracking. To leverage deep link plus do the following:

  1. Target the bid request flag imp.ext.dlp - if present, Deep Link+ is supported
  2. Submit all deep links with the deeplink+ scheme:
deeplink+://navigate?
            primaryUrl=PRIMARY_DEEPLINK&
            primaryTrackingUrl=PRIMARY_TRACKER&
            fallbackUrl=FALLBACK_URL&
            fallbackTrackingUrl=FALLBACK_TRACKER

Example deeplink+:

deeplink+://navigate?
            primaryUrl=twitter%3A%2F%2Ftimeline&
            primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fclicktracking&
            primaryTrackingUrl=http%3A%2F%2Fmopub.com%2Fmopubtracking&
            fallbackUrl=http%3A%2F%2Fmobile.twitter.com

2.7 OpenRTB Native Specification v1.0

This update includes support for the new Native Ads 1.0 sub specification for OpenRTB. We have a few important notes regarding this update for MoPub’s exchange:

  1. native.request is a string - Note that there will always be a leading “native” object inside the request object to note a native creative request type.
  2. bidders have two options for returning ad markup
    1. (preferred method) As a JSON object in the ext.admnative field [note this is similar to MoPub’s original method of native ad bidding]
    2. as a serialized string in the adm field (as noted by OpenRTB)
  3. MoPub is requiring a minimum width and height of 80x80px for the icon asset. A value of 80 is passed in the bid request assets.img.wmin and assets.img.hmin.
  4. Main image and icon image height and width are required in the bid response image object
  5. Current bidders in MoPub’s native ads can map the data fields to the following asset object ids:
    • 1 = title
    • 2 = main image
    • 3 = icon
    • 4 = text
    • 5 = ctatext
    • 6 = starrating
    • 7 = VAST
  6. Native video is currently in beta. Please contact your your account team or mopubDSPsuccess@twitter.com if you would like to participate.

2.8 Note on SSL

Currently, all MoPub in-app inventory supports both SSL and non-SSL creative. Bidders may choose how they want to deliver ad markup as a result of a winning bid.

Additionally, with respect to the bid request and response, we are currently investigating whether to require SSL here and will formally provide details once we’ve made an internal decision.

If you have any specific requirements or questions regarding SSL (creative or OpenRTB integration), please let your account team know.

2.9 Note on VAST Support

  • All VAST videos will auto-play on iOS and Android when video is enabled
  • Linear videos only

Bid Request

To verify if an ad impression can accept a video ad, the DSP must check for the following:

  • Auto-play video is not one of the blocked attributes in the banner object (from the battr field).
  • The value is derived from Section 5.3 of RTB 2.3 spec. For auto-play video ads, its value is 6. Thus, if battr doesn’t contain 6 in the array, you can target auto-play video.

Bid Response

Note: VAST videos and opt-in rewarded video bid responses should be identical and follow the requirements below. Reference the video bid response (section 6.2.3) for both video and rewarded video bid response examples.

Required fields:

  • bid.ext.duration
    • Must match the actual length of the video
    • Must adhere to min/max duration passed in the bid request
  • bid.ext.crtype
    • Type of video being served
  • bid.attr
    • This field indicates the type of creative being served
    • Its value is derived from Section 5.3 of RTB 2.3 spec
    • For auto-play video ads, its value is 6
  • bid.adm
    • The adm (or admarkup field) contains the entire VAST 2.0 XML payload, VAST 2.0 Wrapper, VAST 3.0 XML payload, or VAST 3.0 Wrapper
    • URL-encoded VAST tags are NOT supported

2.10 Inventory Packages

  • Inventory packages will follow similar specifications to PMPs
    • See PMP Object (Section 3.2.17) and Auction Types (Section 7) for more information
  • Bid Response: Look for a matching campaign for the requested Inventory Package. If there is a matching campaign found, return the dealID in the bid response. If there is no campaign for that inventory package, fallback to the open auction and do not respond with a dealID.
    • Please contact your account manager if you would like to be enabled for Inventory Packages

2.11 Viewability Support

DSPs can transact against inventory that has a viewability enabled SDK through Inventory Packages or the Viewability Vendor Flag

Inventory Packages

DSPs can transact against IAS and/or Moat inventory packages today. Viewability inventory packages represent publisher app inventory that currently have the IAS and/or Moat SDK integrated. To get started, contact your account team. See section above to learn more.

Viewability Vendor Flag

We are adding support for DSPs to target inventory that has the IAS and/or Moat SDK integrated. By delivering an IAS or Moat tag to an SDK that supports viewability, buyers can get more robust and accurate measurement.

Bid Request: The bid request will contain imp.ext.metric object which sends the vendor SDK that the publisher supports (See section 3.2.2.1 and 3.2.2.1.1)

Bid Response: Buyers are required to respond with the vendor in the bid response bid.ext when they are returning a campaign for viewability (See section 4.2.4)

We encourage you to read through our Viewability FAQs

2.12 GDPR

For more information about GDPR, see our FAQ

bidrequest.regs.ext.gdpr

The “Regs” object will signal whether or not the request is subject to GDPR regulations. It will do so via the extension attribute “gdpr” which is an integer that indicates: 0 = No, 1 = Yes. The extension is an object.

bidrequest.user.ext.consent

The “User” object will convey user consent when GDPR regulations are in effect. It will do so via the extension attribute “consent”. This string will pass “1” indicating the user has provided consent or “0” indicating that the user has not consented. The extension is an object and if GDPR does not apply, this field will be omitted from the bid request

If we do not have consent, we will not be collecting the following fields. Additionally, all of these fields except IFA will be omitted from the request. IFA will be present, however it will contain zeroes.

  • Advertising ID
  • Lat/Long
  • Age
  • Gender
  • Interest and demographic keywords
  • IP address: we will truncate the 8 lowest bits
  • city
  • metro
  • region
  • zipcode

Sample GDPR Consent/No Consent Requests

3. Bid Request Variables & Definitions

Please ensure you have the OpenRTB 2.3 Specification Guide available while consulting below. This document will contain information and nuances specific to MoPub’s implementation and its expected that you also follow the guidelines presented in OpenRTB when unchanged.

Additional notes:

  • Below section naming will follow OpenRTB for simplicity
  • All fields will be populated in the request if available. We will never pass null values or empty strings. If noted as “always passed”, that parameter will always be present, otherwise it may not be present in all requests. For example, if the request doesn’t contain an SDK version, we will omit the field ver from the request.
  • Types and descriptions from OpenRTB aren’t included below
  • Any objects and attributes from OpenRTB not supported by MoPub will be noted by a strikethrough
Object Section Description
bidrequest 3.2.1 Top-level object.
imp 3.2.2 Container for the description of a specific impression; at least 1 per request.
banner 3.2.3 Details for a banner impression (incl. in-banner video) or video companion ad.
video 3.2.4 Details for a video impression or the video asset of a native impression.
native 3.2.5 Container for a native impression conforming to the Native Ad Spec.
site 3.2.6 Details of the website calling for the impression.
app 3.2.7 Details of the application calling for the impression.
publisher 3.2.8 Entity that controls the content of and distributes the site or app.
content 3.2.9 Details about the published content itself, within which the ad will be shown.
producer 3.2.10 Producer of the content; not necessarily the publisher (e.g., syndication).
device 3.2.11 Details of the device on which the content and impressions are displayed.
geo 3.2.12 Location of the device or user’s home base depending on the parent object.
user 3.2.13 Human user of the device; audience for advertising.
data 3.2.14 Collection of additional user targeting data from a specific data source.
segment 3.2.15 Specific data point about a user from a specific data source.
regs 3.2.16 Regulatory conditions in effect for all impressions in this bid request.
pmp 3.2.17 Collection of private marketplace (PMP) deals applicable to this impression.
deal 3.2.18 Deal terms pertaining to this impression between a seller and buyer.

3.2.1 Object: bidrequest

Attribute Always Passed MoPub implementation specifics
id Yes Unique ID of the bid request, provided by the exchange. (this is the field that is mapped to "id" in bid response)
imp Yes Array of Imp objects (Section 3.2.2) representing the impressions offered. Only one impression object will be passed.
site No (either site or app always) Details via a Site object (Section 3.2.6) about the publisher’s website. Sent when the impression is mobile web.
app No (either site or app always) Details via an App object (Section 3.2.7) about the publisher’s app (i.e., non-browser applications). Sent for all mobile application requests.
device Yes Details via a Device object (Section 3.2.11) about the user’s device to which the impression will be delivered.
user No Details via a User object (Section 3.2.13) about the human user of the device; the advertising audience.
test n.a Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.
at Yes Always set to "2" for MoPub meaning 2nd price auction.
tmax yes Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline. The default value passed is typically 300 or 410 ms. For partners connected to our APAC POP, the default value is typically 180 ms.
wseat n.a Whitelist of buyer seats allowed to bid on this impression. Seat IDs must be communicated between bidders and the exchange a priori. Omission implies no seat restrictions.
allimps n.a Flag to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (e.g., all on the web page, all video spots such as pre/mid/post roll) to support road-blocking. 0 = no or unknown, 1 = yes, the impressions offered represent all that are available.
cur n.a Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.
bcat No Blocked advertiser categories using the IAB content categories. Refer to List 5.1.
badv No Block list of advertisers by their top-level domains (e.g., "ford.com").
regs No A Regs object (Section 3.2.16) that specifies any industry, legal, or governmental regulations in force for this request.
ext Yes Placeholder for exchange-specific extensions to OpenRTB.

3.2.2 Object: imp

Attribute Always Passed Description
id yes A unique identifier for this impression within the context of the bid request . Set to 1, indicating that this is the first (and only) impression in the bid request. (Map this value to bid.impid in the response)
banner only for banner imps A Banner object (Section 3.2.3); required if this impression is offered as a banner ad opportunity.
video only for video imps A Video object (Section 3.2.4); required if this impression is offered as a video ad opportunity.
native only for native imps A Native object (Section 3.2.5); required if this impression is offered as a native ad opportunity.
displaymanager no Will pass "mopub" when the sdk is present
displaymanagerver no MoPub SDK version passed from the SDK, otherwise not passed
instl yes 1 = the ad is interstitial or full screen, 0 = not interstitial.
tagid yes Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer. This is known as "adunit id" by MoPub publishers.
bidfloor yes Minimum bid for this impression expressed in CPM.
bidfloorcur
 n/a Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.
secure yes 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.
iframebuster n/a Array of exchange-specific names of supported iframe busters.
pmp no A pmp object (Section 3.2.17) containing any private marketplace deals in effect for this impression.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.2.1 Object: imp.ext

Attribute Always Passed Description
brsrclk no Set to 1 if Native Browser Clicks are supported.
dlp no Set to 1 if Deep Link+ is supported (SDK 3.9+)
metric no Array of metrics supported by the impression

3.2.2.1.1 Object: imp.ext.metric

Object Array: If the inventory supports viewability, the metric object will be present in the bid request.

Attribute Type Description
type string Type of metric being presented using exchange curated string names which should be published to bidders a priori.
Set to viewability
vendor string Source of the value using exchange curated string names which should be published to bidders a priori.
Set to “ias” for Integral Ad Science (IAS) Set to “moat” for Moat Dependent on the partners that are supported by the publisher. If only one is supported, only one will be passed. If both are supported, both will be passed

3.2.3 Object: banner

Attribute Always Passed Description
w yes Width of the impression in pixels. This value is an exact width requirement.
h yes Height of the impression in pixels. This value is an exact height requirement.
wmax n/a Maximum width of the impression in pixels. If included along with a w value then w should be interpreted as a recommended or preferred width.
hmax n/a Maximum height of the impression in pixels. If included along with an h value then h should be interpreted as a recommended or preferred height.
wmin n/a Minimum width of the impression in pixels. If included along with a w value then w should be interpreted as a recommended or preferred width.
hmin n/a Minimum height of the impression in pixels. If included along with an h value then h should be interpreted as a recommended or preferred height.
id n/a Unique identifier for this banner object. Recommended when Banner objects are used with a Video object (Section 3.2.4) to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression.
btype yes Blocked banner ad types. Refer to List 5.2. Set to [4], to reflect our platform-wide prohibition on IFRAMEs
battr yes Blocked creative attributes. Refer to List 5.3. Please refer to MoPub’s demand side policies for detailed requirements.
pos yes Ad position on screen. Refer to List 5.4. Position is set to 1 ("above the fold", i.e. visible)
mimes n/a Content MIME types supported. Popular MIME types may include application/x-shockwave-flash, image/jpg, and image/gif.
topframe n/a Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.
expdir n/a Directions in which the banner may expand. Refer to List 5.5.
api no List of supported API frameworks for this impression. Refer to List 5.6. If an API is not explicitly listed, it is assumed not to be supported. Array of integers. 3 = MRAID 1.0 is supported, 5 = MRAID 2.0
ext no Placeholder for exchange-specific extensions to OpenRTB.

3.2.3.1 Object: banner.ext

Attribute Always Passed Description
format no Array of format objects representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended.

3.2.3.1.1 Object: banner.ext.format

Attribute Type Description
w integer Width in device independent pixels (DIPS).
h integer Height in device independent pixels (DIPS).

3.2.4 Object: video

Attribute Always Passed Description
mimes yes Content MIME types supported. Flash is not supported. MoPub supported MIMEs are: iOS: [video/3gpp, video/3gpp2, video/mp4, video/quicktime, video/x-m4v] Android: [video/mp4, video/.3gp]
minduration yes Minimum video ad duration in seconds.
maxduration yes Maximum video ad duration in seconds.
protocol n/a NOTE: Use of protocols instead is highly recommended. Supported video bid response protocol. Refer to List 5.8. At least one supported protocol must be specified in either the protocol or protocols attribute.
protocols yes Array of supported video bid response protocols. Refer to List 5.8. We support VAST 2.0, 3.0 and wrappers. Protocols will reflect what the specific inventory source supports as some inventory only supports 2.0, others both 2.0/3.0.
w yes Width of the video player in pixels.
h yes Height of the video player in pixels.
startdelay yes Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to List 5.10 for additional generic values. MoPub always passes 0.
linearity yes Indicates if the impression must be linear, nonlinear, etc. We only support linear video, i.e., linearity = 1
sequence n/a If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.
battr yes Blocked creative attributes. Refer to List 5.3. Please refer to MoPub’s demand side policies for detailed requirements.
maxextended n/a Maximum extended video 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.
minbitrate n/a Minimum bit rate in Kbps. Exchange may set this dynamically or universally across their set of publishers.
maxbitrate n/a Maximum bit rate in Kbps. Exchange may set this dynamically or universally across their set of publishers.
boxingallowed n/a Indicates if letter-boxing of 4:3 content into a 16:9 window is allowed, where 0 = no, 1 = yes.
playbackmethod n/a Allowed playback methods. If none specified, assume all are allowed. Refer to List 5.9
delivery n/a Supported delivery methods (e.g., streaming, progressive). If none specified, assume all are supported. Refer to List 5.13
pos n/a Ad position on screen. Refer to List 5.4
companionad n/a Array of Banner objects (Section 3.2.3) if companion ads are available.
api n/a List of supported API frameworks for this impression. Refer to List 5.6. If an API is not explicitly listed, it is assumed not to be supported.
companiontype yes Supported VAST companion ad types. Refer to List 5.12. Some inventory supports all companion types and others static only. Please target the correct companion types 1,2,3.
ext no Passed for opt-in rewarded video requests only.

3.2.4.1 Object: video.ext

Attribute Always Passed Description
skip yes Indicates if the player will allow the video to be skipped, where 0 = no, 1 = yes MoPub always sets to 0 to identify non-skip opt-in rewarded video Currently passed for opt-in rewarded video requests only.
videotype yes Always set to "rewarded" indicating the request is for an opt-in rewarded video.

3.2.5 Object: native

Attribute Always Passed Description
request yes Request payload complying with the Native Ad Specification. Note that this is a string
ver yes Version of the Native Ad Specification to which request complies; highly recommended for efficient parsing.
api n/a List of supported API frameworks for this impression. Refer to List 5.6. If an API is not explicitly listed, it is assumed not to be supported.
battr yes Blocked creative attributes. Refer to List 5.3. Please refer to MoPub’s demand side policies for detailed requirements.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.6 Object: site

Attribute Always Passed Description
id yes Exchange-specific site ID.
name yes The Site name as entered by the publisher in MoPub UI (may be aliased at the publisher’s request).
domain yes Domain of the site (e.g., "mysite.foo.com").
cat yes Array of IAB content categories of the site. Refer to List 5.1. These are self declared by publisher.
sectioncat n/a Array of IAB content categories that describe the current section of the site. Refer to List 5.1.
pagecat n/a Array of IAB content categories that describe the current page or view of the site. Refer to List 5.1.
page n/a URL of the page where the impression will be shown.
ref n/a Referrer URL that caused navigation to the current page.
search n/a Search string that caused navigation to the current page.
mobile n/a Mobile-optimized signal, where 0 = no, 1 = yes.
privacypolicy n/a Indicates if the site has a privacy policy, where 0 = no, 1 = yes.
publisher yes Details about the Publisher (Section 3.2.8) of the site.
content n/a Details about the Content (Section 3.2.9) within the site.
keywords n/a Comma separated list of keywords about the site.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.7 Object: app

Attribute Always Passed Description
id yes Exchange-specific app ID.
name yes App name (may be aliased at the publisher’s request).
bundle no Application bundle or package name (e.g., com.foo.mygame); intended to be a unique ID across exchanges. iOS will pass the app store ID, Android the package bundle. Not passed for blind apps This is currently self-declared by applications.
domain n/a Domain of the app (e.g., "mygame.foo.com").
storeurl no App store URL for an installed app; for QAG 1.5 & app-ads.txt compliance. Example: https://itunes.apple.com/us/app/twitter/id333903271 & https://play.google.com/store/apps/details?id=com.twitter.android - based on publisher inputs.
cat yes Array of IAB content categories of the app. Refer to List 5.1. These are self declared by publisher.
sectioncat n/a Array of IAB content categories that describe the current section of the app. Refer to List 5.1.
pagecat n/a Array of IAB content categories that describe the current page or view of the app. Refer to List 5.1.
ver no Application version. passed when available
privacypolicy n/a Indicates if the app has a privacy policy, where 0 = no, 1 = yes.
paid n/a 0 = app is free, 1 = the app is a paid version.
publisher yes Details about the Publisher (Section 3.2.8) of the app.
content n/a Details about the Content (Section 3.2.9) within the app.
keywords n/a Comma separated list of keywords about the app.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.8 Object: publisher

Attribute Always Passed Description
id yes Exchange-specific publisher ID.
name yes Publisher name (may be aliased at the publisher’s request).
cat n/a Array of IAB content categories that describe the publisher. Refer to List 5.1.
domain n/a Highest level domain of the publisher (e.g., "publisher.com").
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.11 Object: device

Attribute Always Passed Description
ua usually Browser user agent string.
geo yes Location of the device assumed to be the user’s current location defined by a Geo object (Section 3.2.12).
dnt no Standard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. Only passed when DNT=1. Note that this field is the catch all for signaling not to behaviorally target. We will pass this for any browser dnt signal, lmt signal or coppa flagged user.
lmt no "Limit Ad Tracking" signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
ip yes IPv4 address closest to device.
ipv6 n/a IP address closest to device as IPv6.
devicetype no The general type of device. Refer to List 5.17. Types 4 = phone, 5 = tablet are only available on iOS
make no Device make (e.g., “Apple”).
model no Device model (e.g., “iPhone”). iOS will show iPhone, iPad, iPod Android will have detailed model information such as “SAMSUNG-SM-G900A”
os no Device operating system (e.g., “iOS” or “Android”).
osv no Device operating system version (e.g., “3.1.2”).
hwv no Hardware version of the device (e.g., “5S” for iPhone 5S). Only used for iOS - will show, e.g., “iPhone 5s (GSM)” - what formerly was placed in model
h no Physical height of the screen in pixels. this may be dependent on the device orientation. Note this can differ from banner.h
w no Physical width of the screen in pixels. this may be dependent on the device orientation. Note this can differ from banner.w
ppi n/a Screen size as pixels per linear inch.
pxratio n/a The ratio of physical pixels to device independent pixels.
js yes Support for JavaScript, where 0 = no, 1 = yes. always = 1
flashver n/a Version of Flash supported by the browser.
language no Parsed out from HTTP headers as highlighted below. Acceptable values are two-letter ISO 639-1 codes. iOS: Accept-Language: en-us Android: User-Agent: Mozilla/5.0 (Linux; U; Android 4.1.2; en-us; SAMSUNG-SGH-I317 Build/JZO54K) AppleWebKit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30 Paros/3.2.13
carrier no Carrier or ISP (e.g., “VERIZON”). “WIFI” is often used in mobile to indicate high bandwidth (e.g., video friendly vs. cellular). __ No change from MoPub 2.1 support. moved to standardized list of carrier codes (“MNC”) from this list. This value will be formatted as follows: {mcc}-{mnc} for example, “310-053” would represent Virgin Mobile US in the United States. This value will be passed along to the DSP when it is present via the SDK.
connectiontype no Network connection type. Refer to List 5.18.
ifa no ID sanctioned for advertiser use in the clear (i.e., not hashed). The raw IDFA or Google Advertising ID, unhashed. Present on iOS6+ or apps using the Google Play Services SDK
didsha1 n/a Hardware device ID (e.g., IMEI); hashed via SHA1.
didmd5 n/a Hardware device ID (e.g., IMEI); hashed via MD5.
dpidsha1 no Platform device ID (e.g., Android ID); hashed via SHA1. – only pass with legacy IDs We are deprecating this field and will only pass if ifa is not present and a legacy Android ID or UDID are present.
dpidmd5 no Platform device ID (e.g., Android ID); hashed via MD5. – only pass with legacy IDs We are deprecating this field and will only pass if ifa is not present and a legacy Android ID or UDID are present.
macsha1 n/a MAC address of the device; hashed via SHA1.
macmd5 n/a MAC address of the device; hashed via MD5.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.12 Object: geo

Attribute Always Passed Description
lat no Latitude from -90.0 to +90.0, where negative is south. Lat/long are passed directly from the device if MoPub SDK integrated, or from the publisher if a 3rd party integration. Blank when not passed.
lon no Longitude from -180.0 to +180.0, where negative is west. Lat/long are passed directly from the device if MoPub SDK integrated, or from the publisher if a 3rd party integration. Blank when not passed.
type n/a Source of location data; recommended when passing lat/lon. Refer to List 5.16
country no Country code using ISO-3166-1-alpha-3. Always derived from IP, never a reverse geocode from Lat/Lon
region no Region code using ISO-3166-2; 2-letter state code if USA. Always derived from IP, never a reverse geocode from Lat/Lon
regionfips104 n/a Region of a country using FIPS 10-4 notation. While OpenRTB supports this attribute, it has been withdrawn by NIST in 2008.
metro no Metro codes taken from this list. Only be passed for US and Canada. Always derived from IP, never a reverse geocode from Lat/Lon
city no Always derived from IP, never a reverse geocode from Lat/Lon
zip no Always derived from IP, never a reverse geocode from Lat/Lon
utcoffset n/a Local time as the number +/- of minutes from UTC.
ext no Placeholder for exchange-specific extensions to OpenRTB.

3.2.13 Object: user

Attribute Always Passed Description
id no Exchange-specific ID for the user. At least one of id or buyerid is recommended. Note: reserving for future support
buyerid n/a Buyer-specific ID for the user as mapped by the exchange for the buyer. At least one of buyerid or id is recommended.
yob no Year of birth as a 4-digit integer. Publisher passed when available.
gender no Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown).
keywords no Comma separated list of keywords, interests, or intent.
customdata n/a Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks.
geo n/a Location of the user’s home base defined by a Geo object (Section 3.2.12) This is not necessarily their current location.
data no Additional user data. Each Data object (Section 3.2.14) represents a different data source.
ext no Placeholder for exchange-specific extensions to OpenRTB.

3.2.13.1 Object: user.ext

Attribute Always Passed Description
consent no String that indicates the user has provided GDPR consent. “0” = No Consent “1” = User has consented

3.2.14 Object: data

Attribute Always Passed Description
id no Exchange-specific ID for the data provider.
name no Exchange-specific name for the data provider.
segment no Array of Segment (Section 3.2.15) objects that contain the actual data values.
ext no Placeholder for exchange-specific extensions to OpenRTB.

3.2.15 Object: segment

Attribute Always Passed Description
id no ID of the data segment specific to the data provider.
name n/a Name of the data segment specific to the data provider.
value n/a String representation of the data segment value.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.16 Object: regs

Attribute Always Passed Description
coppa no Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes. Field will only be passed when coppa = 1
ext yes Placeholder for exchange-specific extensions to OpenRTB.

3.2.16.1 Object: regs.ext

Attribute Always Passed Description
gdpr yes Integer that signals whether or not the request is subject to GDPR regulations: 0 = No, 1 = Yes.

3.2.17 Object: pmp

Attribute Always Passed Description
private_auction no 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 and the terms thereof. Always set to 0 for inventory packages.
deals no Array of Deal (Section 3.2.18) objects that convey the specific deals applicable to this impression.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.18 Object: deals

Attribute Always Passed Description
id no A unique identifier for the direct deal. This is the dealid the publisher sets - required in bid response when bidding on a PMP.
bidfloor no Minimum bid for this impression expressed in CPM. Represents price of pmp deal set by publisher - i.e., bids must meet or exceed to win the auction.
bidfloorcur n/a Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange.
at no 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. Currently MoPub always sets at=2
wseat no Whitelist of buyer seats allowed to bid on this deal. Seat IDs must be communicated between bidders and the exchange a priori. Omission implies no seat restrictions. Will be passed if publisher is whitelisting seats for this pmp. Seat in the bid response must match seat in request.
wadomain no Array of advertiser domains (e.g., advertiser.com) allowed to bid on this deal. Omission implies no advertiser restrictions. Adomain in the bid response must match wadomain in request.
ext n/a Placeholder for exchange-specific extensions to OpenRTB.

3.2.19 Object: native.request (4.1 in native subspec)

Attribute Always Passed Description
ver n/a Version of the Native Markup version in use.
layout no The Layout ID of the native ad unit. See the Table of Layout IDs below. MoPub supports layouts 3 & 6 only. Refer to list 7.1 of the OpenRTB Native 1.0 spec.
adunit n/a The Ad unit ID of the native ad unit. See Table of Layout IDs below for a list of supported core ad units.
plcmtcnt n/a The number of identical placements in this Layout. ReferSection 8.1 Multiplacement Bid Requests.
seq no (see the layout types). 0 for the first ad, 1 for the second ad, and so on. This is not the sequence number of the content in the stream.
assets yes An array of AssetObjects. Any bid must comply with the array of elements expressed by the Exchange. Note this is similar to what we previously called ‘admsupport’
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification
privacy no Set to 1 when the native ad supports buyer-specific privacy notice. Field is absent when the native ad doesn’t support custom privacy links or if support is unknown.

3.2.19.1 Object: native.request.assets (4.2 in native subspec)

Attribute Always Passed Description
id yes Unique asset ID, assigned by exchange. Typically a counter for the array. 1 = title
2 = main image
3 = icon
4 = text
5 = ctatext
6 = starrating (not currently supported)
7 = VAST
required yes Set to 1 if asset is required (exchange will not accept a bid without it)
title yes1 Title object for title assets. See TitleObject definition. Max characters = 50 (may truncate after 25 characters)
img yes1 Image object for image assets. See ImageObject definition.
video n/a Video object for video assets. See the Video request object definition. Note that in-stream video ads are not part of Native. Native ads may contain a video as the ad creative itself.
data yes1 Data object for ratings, prices etc. See Data Object definition
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

1: asset object may contain only one of title, img, data or video.

3.2.19.2 Title Object (4.3 in native subspec)

Attribute Always Passed Description
len yes Maximum length of the text in the title element.
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

3.2.19.3 Image Object (4.4 in native subspec)

Attribute Always Passed Description
type yes Type ID of the image element supported by the publisher. The publisher can display this information in an appropriate format. From OpenRTB Native 1.0 spec Table 7.4 "Image Asset Types", the values are 1 for Icon image, 2 for Logo image, 3 for Main image and 500+ for Exchange specific values. MoPub currently supports values of 1 or 3 for the icon and main images respectively.
h no Recommended height of the image in pixels. Only set for mainimage with a value of 627.
w no Recommended width of the image in pixels. Only set for mainimage with a value of 1200.
hmin no The minimum requested height of the image in pixels. This option should be used for any rescaling of images by the client. Either h or hmin should be transmitted. If only h is included, it should be considered an exact requirement. Set for icon image with a value of 80 - require 1:1 aspect ratio. Set for main image with a value of 417 - require 1.91:1 aspect ratio (1200x627, 1200x628 and 800x418 recommended).
wmin no The minimum requested width of the image in pixels. This option should be used for any rescaling of images by the client. Either w or wmin should be transmitted. If only w is included, it should be considered an exact requirement. Set for icon image with a value of 80 - require 1:1 aspect ratio. Set for main image with a value of 800 - require 1.91:1 aspect ratio (1200x627, 1200x628 and 800x418 recommended).
mimes n/a Whitelist of content MIME types supported. Popular MIME types include, but are not limited to image/jpg and image/gif. Each implementing Exchange should have their own list of supported types in the integration docs. See Wikipedia's MIME page for more information and links to all IETF RFCs. If blank, assume all types are allowed.
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

3.2.19.4 Video Object (4.5 in native subspec)

Not currently supported

Attribute Always Passed Description
mimes yes Currently only mp4 is supported
minduration yes Minimum video ad duration in seconds. Set to 5
maxduration yes Maximum video ad duration in seconds. Set to 120
protocols yes Array of supported video bid response protocols. Refer to List 5.8. We support Vast 2.0, 3.0 and wrappers.

3.2.19.5 Data Object (4.6 in native subspec)

Attribute Always Passed Description
type yes Type ID of the element supported by the publisher. The publisher can display this information in an appropriate format. See table 7.3 Data Asset Types for commonly used examples. "text" = 2 (text format) "starrating" = 3 (number formatted as string) "ctatext" = 12 (text format)
len no Maximum length of the text in the element’s response. "text" = 150 (may truncate after 100 characters) "ctatext" = 15 (we default to "Install" if no value is present) "starrating" do not pass
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

3.2.20 Object: ext

Attribute Always Passed Description
pchain yes Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0.

4. Bid Response Variables & Definitions

Additional notes:

  • Below section naming will follow OpenRTB for simplicity
  • The types are unchanged from OpenRTB specification
  • Attribute requirements reflect MoPub requirements and may differ from OpenRTB
  • Any objects and attributes not supported by MoPub will be noted by a strikethrough
Object Section MoPub Support / Description
bidresponse 4.2.1 Top-level object.
seatbid 4.2.2 Collection of bids made by the bidder on behalf of a specific seat.
bid 4.2.3 An offer to buy a specific impression under certain business terms.

4.2.1 Object: bidresponse

Attribute Type; Requirement MoPub Support / Description
id string; required ID of the bid request to which this is a response. (i.e., must match bidrequest.id)
seatbid object array; required Array of seatbid objects; 1+ required if a bid is to be made.
bidid string; optional Bidder generated response ID to assist with logging/tracking.
cur string; default "USD"; optional Currently only accepts and defaults to "USD".
customdata string Optional feature to allow a bidder to set data in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include "escaped" quotation marks.
nbr integer; recommended Reason for not bidding. Refer to List 5.19. Also refer to section 4.4 on preferred response when not bidding but sending an nbr
ext object Placeholder for bidder-specific extensions to OpenRTB.

4.2.2 Object: seatbid

Attribute Type; Requirement MoPub Support / Description
bid object array; required Array of 1+Bidobjects (Section 4.2.3) each related to an impression. Multiple bids can relate to the same impression.
seat string; recommended (required in some cases) ID of the bidder seat on whose behalf this bid is made. Required by DSPs who have multiple buyer seats using their platform. A bid response may contain bids from multiple "seats" or contain multiple bids from the same seat. MUSTbe an alphanumeric string, max 40 characters, ideally min 8 char. This should be logged and will primarily be used for billing purposes. Note:Do not pass unless you have multiple buyer seats on your platform. Required if using multiple seats.
group integer; default 0 0 = impressions can be won individually; 1 = impressions must be won or lost as a group.
ext object Placeholder for bidder-specific extensions to OpenRTB.

4.2.3 Object: bid

Attribute Type; Requirement MoPub Support / Description
id string; required Bidder generated bid ID to assist with logging/tracking.
impid string; required ID of theImpobject in the related bid request.
price float; required Bid price expressed as CPM although the actual transaction is for a unit impression only. Note that while the type indicates float, integer math is highly recommended when handling currencies (e.g., BigDecimal in Java).
adid string, optional ID of a preloaded ad to be served if the bid wins.
nurl string, recommended Win notice URL called by the exchange if the bid wins. (note that this will be sent server side when auction is resolved if winner) See above section 2.5 on nurl support for changes with nurl and impression tracking in MoPub’s RTB 2.3 protocol.
adm string, required Placement of the ad markup directly in the bid response is the main method supported by MoPub. For native ads however, it’s recommended to use the admnative object rather than adm. For VAST video you must submit XML per OpenRTB (VAST URLs must be submitted as wrapper tags).
adomain string array, required Advertiser domain for block list checking (e.g., "ford.com"). Please refer to MoPub’s demand side policies for detailed requirements on adomain.
bundle string, required for apps Bundle or package name (e.g., com.foo.mygame) of the app being advertised, if applicable; intended to be a unique ID across exchanges. Note: This is recommended to be passed in addition to adomain for app advertisements. We will be moving to requiring bundle instead of adomain for app advertisements at a future date.
iurl string, optional URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking.
cid string, recommended Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
crid string, required Creative ID to assist with ad quality checking. This should uniquely identify the creative, and can be used for blocking or identification / aggregation purposes.
cat string array, required IAB content categories of the creative. Refer to List 5.1.
attr integer array, required Required when applicable, creative attributes, an array of values taken from §5.3 Creative Attributes, that indicate if the ad is expandable, etc. When present, this must be accurate and reflect the actual creative, otherwise it is a policy violation. Required for video, recommended otherwise
dealid string, required for pmp Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. Do not pass unless bidding against a private marketplace deal or inventory package.
Do not pass unless bidding against a private marketplace deal
For inventory packages, Look for a matching campaign for the requested Inventory Package. If there is a matching campaign found, return the dealID in the bid response. If there is no campaign for that inventory package, fallback to the open auction and do not respond with a dealID.
h integer, recommended Height of the creative in density independent pixels.
w integer, recommended Width of the creative in density independent pixels.
privacy array of objects; optional If support was indicated in the request, the image_url of the privacy information icon and click_url of the privacy information page informing the user about the buyer's targeting activity. See List 4.2.6.
ext object Placeholder for bidder-specific extensions to OpenRTB.

4.2.4 Object: bid.ext

Attribute Type; Requirement Description
admnative object, recommended for native ads Recommended for native ads. Pass the native ad json object directly into this field instead of serializing it in adm. If using admnative do not pass adm (we will ignore) Note: this is formerly "admjson" in mopub native spec).
nurls array, optional Array of nurl notifications to be sent on auction win (pass only nurl or nurls[]; if both are present we will default to contents of this variable and ignore the bid.nurl value)
imptrackers array, required Array of impression trackers (1st & 3rd Party) to be consistently tracked when MoPub records the billable impression event This does not apply for native. See native object imptrackers.
loadtrackers array, optional Array of load trackers (1st & 3rd Party) that will fire when an ad has been downloaded or pre-cached on the device, before an impression has been shown.
data array object, required if bidding on data Identical structure to the user/data object that was passed in the BidRequest. Reference 3rd Party Data Support above.
duration int, required for video Length of the video (if a video ad) in seconds
crtype string, required for some creative types This field can contain one of the following values depending on the type of creative: [{"VAST 2.0", "VAST 3.0", "MRAID 1.0", "MRAID 2.0", "MRAID playable", "Image Ad", "HTML5", "JS", "native"}]. This field is required when serving video ("VAST 2.0", "VAST 3.0", "HTML5"), MRAID ("MRAID 1.0", "MRAID 2.0", "MRAID playable") or native ("native"). This field is preferred for all other ad formats.
vendor string array, required for campaigns that measure viewability Name of viewability vendor(s) that will be measuring viewability for the ad that is shown. You should only declare viewability vendors in the bid response when you are collecting viewability measurement for an impression. Set to “ias” for Integral Ad Science (IAS) Set to “moat” for Moat Buyers are required to respond with the vendor in the bid response when they are returning a display campaign for viewability.

4.2.5 Native Ad creative JSON (5.1 in native subspec)

Attribute Type; Requirement Description
native object, required top level native object

4.2.5.1 Object: native (5.2 in native subspec)

Attribute Type; Requirement Description
ver integer; n/a Version of the Native Markup version in use.
assets array of objects; required lists the native ad assets
link object; required Destination Link. This is default link object for the ad. Individual assets can also have a link object which applies if the asset is activated (clicked). If the asset doesn’t have a link object, the parent link object applies. See LinkObject Definition Note: we don’t support link objects on assets
imptrackers array of strings; required Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers.
jstracker string; n/a Optional JavaScript impression tracker. This is a valid HTML, JavaScript is already wrapped in <script> tags. It should be executed at impression time where it can be supported
privacy string; optional If support was indicated in the request, the click_url of the privacy information page informing the user about the buyer's targeting activity.
ext object; n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

4.2.5.2 Object: native.assets (5.3 in native subspec)

Attribute Type; Requirement Description
id integer; required Unique asset ID, assigned by exchange. Typically a counter for the array. Code to match the request asset object
required integer; optional Note that mopub will ignore this field for bids
title object; required Title object for title assets. See TitleObject definition.
img object; optional1 Image object for image assets. See ImageObject definition.
video object; optional1 Video object for video assets. See the Video request object definition. Note that in-stream video ads are not part of Native. Native ads may contain a video as the ad creative itself.
data object; optional1 Data object for ratings, prices etc. See DataObject definition
link object; optional1 Link object for call to actions. The link object applies if the asset item is activated (clicked). If there is no link object on the asset, the parent link object on the bid response applies.

1: asset object may contain only one of img, data or video.

4.2.5.3 Title Object (5.4 in native subspec)

Attribute Type; Requirement Description
text string, required The text associated with the text element.
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

4.2.5.4 Image Object (5.5 in native subspec)

Attribute Type; Requirement Description
url string; required URL of the image asset
h integer; required Height of the image
w integer; required Width of the image
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

4.2.5.5 Data Object (5.6 in native subspec)

Attribute Type; Requirement Description
label string; n/a The optional formatted string name of the data type to be displayed.
value string; required The formatted string of data to be displayed. Can contain a formatted value such as "5 stars" or "$10" or "3.4 stars out of 5".
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

4.2.5.6 Video Object (5.7 in native subspec)

Attribute Type; Requirement Description
vasttag string; required VAST XML per OpenRTB VAST URLs must be submitted as wrapper tags
Attribute Type; Requirement Description
url string; required Landing URL of the clickable link
clicktrackers array of strings; optional List of third-party tracker URLs to be fired on click of the URL.
fallback string; optional Fallback URL for deeplink. To be used if the URL given in url is not supported by the device.
ext n/a This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification

4.2.6 Object: bid.privacy

Attribute Type; Requirement Description
image_url string, optional The URL of the privacy information icon. Recommended size is 120x120 pixels.
click_url string, optional The URL of the privacy information page.

4.3 Substitution Macros

Macro Description
${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} Settlement price using the same currency and units as the bid.
${AUCTION_CURRENCY} The currency used in the bid (explicit or implied); for confirmation only.
${AUCTION_PRICE:B64} Settlement price using the same currency and units as the bid, encoded with Base 64 encoding. Example: MC4x and MC40MQ are the base 64 encodings of "0.1" and "0.41" respectively

All macros must be formatted as ${MACRO_NAME}

Macro substitution is supported for the following fields:

  • seatbid.bid.nurl
  • seatbid.bid.adm
  • seatbid.bid.ext.nurls
  • seatbid.bid.ext.imptrackers
  • seatbid.bid.ext.admnative.native.imptrackers

Note that MoPub has added support for encoding the price in RTB 2.3. We only support Base 64 encoding. If the bidder requires price to be encoded, they should use the below ${AUCTION_PRICE:B64}

4.4 Sending nbr when not bidding

Preferred for bidder to send a bare minimum bid response object when not bidding but providing nbr. For example:

{
  "id": "123",
  "nbr": 5
}

In this case the bidder would send back an HTTP 200 response code 200 with this barebones response object.

5. Enumerated Lists Specification

5.1 Lists: OpenRTB 2.3 Spec

Please refer to the Enumerated Lists section in the OpenRTB 2.3 specification.

5.10 Video Start Delay

The following table lists the various options for the video 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 Description
> 0 Mid-Roll (value indicates start delay in second)
0 Pre-Roll
-1 Generic Mid-Roll
-2 Generic Post-Roll

5.18 Connection Type

Value Description
0 Unknown
1 Ethernet
2 WIFI
3 Cellular Network – Unknown Generation
4 Cellular Network – 2G
5 Cellular Network – 3G
6 Cellular Network – 4G

5.2 Lists: Native Subspec

Please refer to the Reference Lists/Enumerations section in the Native subspec.

7.1 Native Layout IDs

Layout ID Description
1 Content Wall
2 App Wall
3 News Feed
4 Chat List
5 Carousel
6 Content Stream
7 Grid adjoining the content
500+ Reserved for Exchange specific layouts.

7.2 Native Ad Unit IDs

Ad Unit ID Description
1 Paid Search Unit
2 Recommendation Widgets
3 Promoted Listings
4 In-Ad (IAB Standard) with Native Element Units
5 Custom/"Can't Be Contained"
500+ Reserved for Exchange specific formats.

7.3 Data Asset Types

Type ID Name Description Format
1 sponsored Sponsored By message where response should contain the brand name of the sponsor. text
2 desc Descriptive text associated with the product or service being advertised. text
3 rating Rating of the product being offered to the user. For example an app’s rating in an app store from 0-5. number formatted as string
4 likes Number of social ratings or “likes” of the product being offered to the user. number formatted as string
5 downloads Number downloads/installs of this product number formatted as string
6 price Price for product / app / in-app purchase. Value should include currency symbol in localised format. number formatted as string
7 saleprice Sale price that can be used together with price to indicate a discounted price compared to a regular price. Value should include currency symbol in localised format. number formatted as string
8 phone Phone number formatted string
9 address Address text
10 desc2 Additional descriptive text associated with the product or service being advertised text
11 displayurl Display URL for the text ad text
12 ctatext CTA description - descriptive text describing a ‘call to action’ button for the destination URL. text
500+ XXX Reserved for Exchange specific usage numbered above 500 Unknown

7.4 Image Asset Types

Type ID Name Description
1 Icon Icon image
2 Logo Logo image for the brand/app.
3 Main Large image preview for the ad
500+ XXX Reserved for Exchange specific usage numbered above 500

5.3 Lists: Creative Attributes

Value Description
1 Audio Ad (Auto-Play)
2 Audio Ad (User Initiated)
3 Expandable (Automatic)
4 Expandable (User Initiated - Click)
5 Expandable (User Initiated - Rollover)
6 In-Banner Video Ad (Auto-Play)
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 Can be Skipped (e.g., Skip Button on Pre-Roll Video)

6. Bid Request / Response Samples

6.1 Bid Request Examples

Note: Bid requests below are not fully formed. Please defer to the spec to see additional fields that may be passed.

6.1.1 Banner Bid Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB7-39",
      "IAB8-5",
      "IAB8-18",
      "IAB9-9",
      "IAB25",
      "IAB26",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"USA",
         "lat":10.738701,
         "lon":-76.0037
      },
      "h":1920,
      "hwv":"iPhone 6+",
      "ifa":"e785aa3f-0b58-4ff1-8758-74ae56a9b2d9",
      "ip":"8.25.196.26",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411",
      "w":1080
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"8e41bc64-188d-43cf-b98f-9853cb2a2886",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "btype":[
               4
            ],
            "h":50,
            "pos":1,
            "w":320
         },
         "bidfloor":0.12,
         "displaymanager":"mopub",
         "displaymanagerver":"3.10.0",
         "ext":{
            "brsrclk":1,
            "dlp":1
         },
         "id":"1",
         "instl":0,
         "secure":0,
         "tagid":"b12ae796186931bfe7aa39471487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.2 Video Bid Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"USA",
         "lat":30.738701,
         "lon":-24.0037
      },
      "h":1920,
      "hwv":"iPhone 6+",
      "ifa":"e785aa3f-0b58-4ff1-8758-74ae56a9b2d9",
      "ip":"8.25.196.26",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411",
      "w":1080
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"e25af195-2a43-4499-b4cd-60519c1915df",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               9,
               10,
               14
            ],
            "btype":[
               4
            ],
            "h":480,
            "pos":1,
            "w":320
         },
         "bidfloor":0.12,
         "displaymanager":"mopub",
         "displaymanagerver":"3.10.0",
         "ext":{
            "brsrclk":1,
            "dlp":1
         },
         "id":"1",
         "instl":1,
         "secure":0,
         "tagid":"441fb971540fd4bbc364b83397721b5e",
         "video":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               9,
               10,
               14
            ],
            "companiontype":[
               1,
               2,
               3
            ],
            "h":480,
            "linearity":1,
            "maxduration":120,
            "mimes":[
               "video/3gpp",
               "video/3gpp2",
               "video/mp4",
               "video/quicktime",
               "video/x-m4v"
            ],
            "minduration":0,
            "protocols":[
               2,
               5,
               3,
               6
            ],
            "startdelay": 0,
            "w":320
         }
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.3 Private Marketplace Bid Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"USA"
      },
      "hwv":"iPhone 6+",
      "ifa":"3485E719-C68E-495B-945E-C8DF42879D3D",
      "ip":"8.25.196.26",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411"
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"2af6ea7e-f807-49eb-95ca-0ed021e914c2",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "btype":[
               4
            ],
            "h":50,
            "pos":1,
            "w":320
         },
         "bidfloor":5.0,
         "displaymanager":"mopub",
         "displaymanagerver":"3.4.0",
         "ext":{
            "brsrclk":1
         },
         "id":"1",
         "instl":0,
         "pmp":{
            "deals":[
               {
                  "at":2,
                  "bidfloor":5.0,
                  "id":"09e57922e9684f508b30cb897ff6e3ab",
                  "wadomain":[
                     "nike.com"
                  ]
               }
            ],
            "private_auction":1
         },
         "secure":0,
         "tagid":"b12aefe7aa39471796186931b487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.4 Native Bid Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB1",
         "IAB1-6",
         "music"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "city":"Chicago",
         "country":"USA",
         "metro":"602",
         "region":"IL",
         "zip":"60614"
      },
      "hwv":"iPhone 6+",
      "ifa":"3485E719-C68E-495B-945E-C89D3DF4287D",
      "ip":"108.176.57.230",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411"
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"59e709a0-e806-4230-976d-9e177f76522c",
   "imp":[
      {
         "bidfloor":0.12,
         "displaymanager":"mopub",
         "id":"1",
         "instl":0,
         "native":{
            "battr":[
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "request":"{\"native\":{\"assets\":[{\"data\":{\"len\":15,\"type\":12},\"id\":5,\"required\":0},{\"id\":3,\"img\":{\"hmin\":80,\"type\":1,\"wmin\":80},\"required\":1},{\"id\":2,\"img\":{\"h\":627,\"hmin\":417,\"type\":3,\"w\":1200,\"wmin\":800},\"required\":1},{\"data\":{\"len\":100,\"type\":2},\"id\":4,\"required\":1},{\"id\":1,\"required\":1,\"title\":{\"len\":25}}],\"layout\":6}}",
            "ver":"1.0.0.2"
         },
         "secure":1,
         "tagid":"3704ade244268514f54b5ab4b2672321"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.5 Native Video Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB1",
         "IAB1-6",
         "music"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "city":"Chicago",
         "country":"USA",
         "metro":"602",
         "region":"IL",
         "zip":"60614"
      },
      "h":1136,
      "hwv":"iPhone 6+",
      "ifa":"3E67D059-6F94-4C88-AD2A-72533799FE15",
      "ip":"108.176.57.230",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.3",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411",
      "w":640
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"02ed2e67-84f0-4470-897c-3b99753c8f53",
   "imp":[
      {
         "bidfloor":0.12,
         "displaymanager":"mopub",
         "displaymanagerver":"4.0.0",
         "ext":{
            "brsrclk":1,
            "dlp":1
         },
         "id":"1",
         "instl":0,
         "native":{
            "battr":[
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "request":"{\"native\":{\"assets\":[{\"data\":{\"len\":15,\"type\":12},\"id\":5,\"required\":0},{\"id\":3,\"img\":{\"hmin\":80,\"type\":1,\"wmin\":80},\"required\":1},{\"id\":2,\"img\":{\"h\":627,\"hmin\":417,\"type\":3,\"w\":1200,\"wmin\":800},\"required\":1},\"required\":1},{\"data\":{\"len\":100,\"type\":2},\"id\":4,\"required\":1},{\"id\":1,\"required\":1,\"title\":{\"len\":25}},{\"id\":7,\"required\":0,\"video\":{\"maxduration\":120,\"mimes\":[\"video/mp4\"],\"minduration\":5,\"protocols\":[2,3,5,6]}}],\"layout\":6,\"seq\":3}}",
            "ver":"1.0.0.2"
         },
         "secure":1,
         "tagid":"e7fb4d46d877b1edb482687d64be5ff1"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.6 Rewarded Video Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"USA",
         "lat":30.738701,
         "lon":-24.0037
      },
      "h":1920,
      "hwv":"iPhone 6+",
      "ifa":"e785aa3f-0b58-4ff1-8758-74ae56a9b2d9",
      "ip":"8.25.196.26",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411",
      "w":1080
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"e25af195-2a43-4499-b4cd-60519c1915df",
   "imp":[
      {
         "bidfloor":0.12,
         "displaymanager":"mopub",
         "displaymanagerver":"3.10.0",
         "ext":{
            "brsrclk":1,
            "dlp":1
         },
         "id":"1",
         "instl":1,
         "secure":0,
         "tagid":"441fb971540fd4bbc364b83397721b5e",
         "video":{
            "battr":[
               3,
               8,
               9,
               10,
               14
            ],
            "companiontype":[
               1,
               2,
               3
            ],
            "ext":{
               "skip":0,
               "videotype":"rewarded"
            },
            "h":480,
            "linearity":1,
            "maxduration":30,
            "mimes":[
               "video/3gpp",
               "video/3gpp2",
               "video/mp4",
               "video/quicktime",
               "video/x-m4v"
            ],
            "minduration":0,
            "protocols":[
               2,
               5,
               3,
               6
            ],
            "startdelay": 0,
            "w":320
         }
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.7 Inventory Package Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"USA"
      },
      "hwv":"iPhone 6+",
      "ifa":"3485E719-C68E-495B-945E-C8DF42879D3D",
      "ip":"8.25.196.26",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411"
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"2af6ea7e-f807-49eb-95ca-0ed021e914c2",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "btype":[
               4
            ],
            "h":50,
            "pos":1,
            "w":320
         },
         "bidfloor":5.0,
         "displaymanager":"mopub",
         "displaymanagerver":"4.13.0",
         "ext":{
            "brsrclk":1,
            "metric":[
               {
                  "type":"viewability",
                  "vendor":"ias"
               },
               {
                  "type":"viewability",
                  "vendor":"moat"
               }
            ]
         },
         "id":"1",
         "instl":0,
         "pmp":{
            "deals":[
               {
                  "at":2,
                  "bidfloor":5.0,
                  "id":"ip_3ba84451c2f94b34af95effaf8c4fa9d"
               },
               {
                  "id":"ip_1c2f94b33ba84454af95effaf8c4fa9d",
                  "at":2,
                  "bidfloor":5.0
               }
            ],
            "private_auction":0
         },
         "secure":0,
         "tagid":"b12aefe7aa39471796186931b487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

6.1.8 Viewability Request

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "storeurl":"https://itunes.apple.com/us/app/candy-crush-saga/id553834731?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"USA"
      },
      "hwv":"iPhone 6+",
      "ifa":"3485E719-C68E-495B-945E-C8DF42879D3D",
      "ip":"8.25.196.26",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 8_1 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12B411"
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"2af6ea7e-f807-49eb-95ca-0ed021e914c2",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "btype":[
               4
            ],
            "h":50,
            "pos":1,
            "w":320
         },
         "bidfloor":5.0,
         "displaymanager":"mopub",
         "displaymanagerver":"4.13.0",
         "ext":{
            "brsrclk":1,
            "metric":[
               {
                  "type":"viewability",
                  "vendor":"ias"
               },
               {
                  "type":"viewability",
                  "vendor":"moat"
               }
            ]
         },
         "id":"1",
         "instl":0,
         "secure":0,
         "tagid":"b12aefe7aa39471796186931b487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "tmax": 300
}

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "ver":"1.0"
   },
   "at":2,
   "bcat":[
      "IAB7-39",
      "IAB8-5",
      "IAB8-18",
      "IAB9-9",
      "IAB25",
      "IAB26",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":3,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "city":"Paris",
         "country":"FRA",
         "lat": 48.860757,
         "lon": 2.337562,
         "region":"IDF",
         "zip":"75001"
      },
      "h":800,
      "hwv":"iPhone 6+",
      "ifa":"e785aa3f-0b58-4ff1-8758-74ae56a9b2d9",
      "ip":"8.25.197.65",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"8.1",
      "pxratio":1.5,
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 6_1_3 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Mobile/10B329",
      "w":480
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"8e41bc64-188d-43cf-b98f-9853cb2a2886",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               10,
               14,
               6
            ],
            "btype":[
               4
            ],
            "h":50,
            "pos":1,
            "w":320
         },
         "bidfloor":2.15,
         "displaymanager":"mopub",
         "displaymanagerver":"5.0",
         "ext":{
            "brsrclk":1,
            "dlp":1
         },
         "id":"1",
         "instl":0,
         "secure":0,
         "tagid":"b12aefe7aa39471796186931b487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":1
      }
   },
   "tmax": 300,
   "user":{
      "ext":{
         "consent":"1"
      }
   }
}

{
   "app":{
      "bundle":"553834731",
      "cat":[
         "IAB3",
         "business"
      ],
      "id":"a422f9bf94df0c59389d5beff67f8821",
      "name":"App_Name",
      "publisher":{
         "id":"04241e0b1cc98976858ce16377c7eef4",
         "name":"Publisher_Name"
      },
      "ver":"1.0.13"
   },
   "at":2,
   "bcat":[
      "IAB25",
      "IAB26",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{
      "carrier":"310-260",
      "connectiontype":3,
      "devicetype":4,
      "dnt":0,
      "geo":{
         "country":"FRA"
      },
      "h":800,
      "hwv":"iPhone 6+",
      "ifa":"00000000-0000-0000-0000-000000000000",
      "ip":"8.25.197.0",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"6.1.3",
      "pxratio":1.5,
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 6_1_3 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Mobile/10B329",
      "w":480
   },
   "ext":{
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"8e41bc64-188d-43cf-b98f-9853cb2a2886",
   "imp":[
      {
         "banner":{
            "api":[
               3,
               5
            ],
            "battr":[
               3,
               8,
               10,
               14,
               6
            ],
            "btype":[
               4
            ],
            "h":50,
            "pos":1,
            "w":320
         },
         "bidfloor":2.15,
         "displaymanager":"mopub",
         "displaymanagerver":"5.0",
         "ext":{
            "brsrclk":1,
            "dlp":1
         },
         "id":"1",
         "instl":0,
         "secure":0,
         "tagid":"b12aefe7aa39471796186931b487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":1
      }
   },
   "tmax": 300,
   "user":{
      "ext":{
         "consent":"0"
      }
   }
}

6.1.10 Format Array Bid Request

{  
   "app":{  
      "bundle":"333903271",
      "cat":[  
         "IAB3",
         "productivity"
      ],
      "id":"039e99e6b85e4288a1d42790ae00d2d6",
      "name":"App",
      "publisher":{  
         "id":"fa167489379c4e78b9e164b22e51965a",
         "name":"Twitter"
      },
      "storeurl":"https://itunes.apple.com/us/app/twitter/id333903271?mt=8",
      "ver":"1.0"
   },
   "at":2,
   "bcat":[  
      "IAB25",
      "IAB26",
      "IAB7-39",
      "IAB8-18",
      "IAB8-5",
      "IAB9-9",
      "IAB3-7"
   ],
   "device":{  
      "carrier":"311-480",
      "connectiontype":2,
      "devicetype":4,
      "dnt":0,
      "geo":{  
         "city":"San Francisco",
         "country":"USA",
         "metro":"807",
         "region":"CA",
         "zip":"94109"
      },
      "h":1920,
      "hwv":"iPhone10,1",
      "ifa":"7EA77E86-4C7D-4BEB-AA39-BD4B87C7140E",
      "ip":"8.25.197.65",
      "js":1,
      "language":"en",
      "make":"Apple",
      "model":"iPhone",
      "os":"iOS",
      "osv":"11.4.1",
      "pxratio":3.0,
      "ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 11_4_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15G77",
      "w":1080
   },
   "ext":{  
      "pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
   },
   "id":"bbf7ddea-8b89-40ed-864b-fb1076e414f4",
   "imp":[  
      {  
         "banner":{  
            "api":[  
               3,
               5
            ],
            "battr":[  
               3,
               8,
               9,
               10,
               14,
               6
            ],
            "btype":[  
               4
            ],
            "ext":{  
               "format":[  
                  {  
                     "w":320,
                     "h":480
                  },
                  {  
                     "w":300,
                     "h":568
                  },
                  {  
                     "w":300,
                     "h":600
                  },
                  {  
                     "w":360,
                     "h":640
                  }
               ]
            },
            "h":480,
            "pos":1,
            "w":320
         },
         "bidfloor":0.2,
         "displaymanager":"mopub",
         "displaymanagerver":"5.3.0",
         "ext":{  
            "brsrclk":1,
            "dlp":1,
            "metric":[  
               {  
                  "type":"viewability",
                  "vendor":"ias"
               },
               {  
                  "type":"viewability",
                  "vendor":"moat"
               }
            ]
         },
         "id":"1",
         "instl":0,
         "pmp":{  
            "deals":[  
               {  
                  "at":2,
                  "bidfloor":0.2,
                  "id":"ip_0cfeaebb190d47df8b86399232853e23"
               }
            ],
            "private_auction":0
         },
         "secure":1,
         "tagid":"de0051465ae74bd1a2a5d3616abea82c"
      }
   ],
   "regs":{  
      "ext":{  
         "gdpr":0
      }
   },
   "tmax":300,
   "user":{  
      "keywords":"mpxtest"
   }
}

6.2 Bid Response Examples

Note: Bid responses below are not fully formed and may include optional fields. Please defer to the spec.

6.2.1 Banner Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "Image Ad",
        "imptrackers": [
          "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adm": "",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        4,
        7
      ],
      "cid": "campaign111",
      "crid": "101409",
      "h": 50,
      "w": 320,
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.2 MRAID Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "MRAID 1.0",
        "imptrackers": [
          "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adm": "",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        4,
        7
      ],
      "cid": "campaign111",
      "crid": "101409",
      "h": 50,
      "w": 320,
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.3 Video Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz123456",
    "bid": [{
      "ext": {
        "duration": 30,
        "crtype": "VAST 2.0",
        "imptrackers": [
          "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adm": "",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        6
      ],
      "cid": "campaign111",
      "crid": "101409",
      "h": 320,
      "w": 480,
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.4 MRAID Video Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "MRAID 1.0",
        "imptrackers": [
          "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adm": "",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        7
      ],
      "cid": "campaign111",
      "crid": "101409",
      "h": 320,
      "w": 480,
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.5 Private Marketplace Bid Response

{
   "bidid":"abc1234",
   "cur":"USD",
   "id":"1234567890",
   "seatbid":[
      {
         "seat":"xyz12345",
         "bid":[
            {
               "ext":{
                  "crtype":"Image Ad",
                  "imptrackers":[
                     "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
                     "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
                  ],
                  "nurls":[
                     "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
                     "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
                  ]
               },
               "id":"12345678",
               "adid":"314",
               "cat":[
                  "IAB18"
               ],
               "adm":" ",
               "adomain":[
                  "nike.com"
               ],
               "bundle":"com.foo.mygame",
               "dealid":"09e57922e9684f508b30cb897ff6e3ab",
               "cid":"campaign111",
               "crid":"101409",
               "h":50,
               "w":320,
               "impid":"1",
               "price":5.00
            }
         ]
      }
   ]
}

6.2.6 Native Bid Response (adm)

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "native"
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB3"
      ],
      "adm": "{\"native\":{\"link\":{\"url\":\"http:\/\/www.mopub.com\"},\"assets\":[{\"id\":1,\"title\":{\"text\":\"This is the title\"}},{\"id\":2,\"img\":{\"url\":\"http:\/\/d30x8mtr3hjnzo.cloudfront.net\/creatives\/8003cbe865a24282a47ce346ff271000\",\"h\":627,\"w\":1200}},{\"id\":3,\"img\":{\"url\":\"http:\/\/d30x8mtr3hjnzo.cloudfront.net\/creatives\/a7b528d5c537426da5e42f418cc35e47\",\"h\":80,\"w\":80}},{\"data\":{\"value\":\"This is the text\"},\"id\":4},{\"data\":{\"value\":\"CTA Text\"},\"id\":5},{\"data\":{\"value\":\"4.5\"},\"id\":6}],\"imptrackers\":[\"https:\/\/imptrackers1.com\/mopub\/win\/${AUCTION_ID}\/${AUCTION_BID_ID}\/${AUCTION_IMP_ID}\/${AUCTION_SEAT_ID}\/${AUCTION_AD_ID}\/${AUCTION_PRICE}\/0.999\",\"https:\/\/imptrackers2.com\/mopub\/win\/${AUCTION_ID}\/${AUCTION_BID_ID}\/${AUCTION_IMP_ID}\/${AUCTION_SEAT_ID}\/${AUCTION_AD_ID}\/${AUCTION_PRICE}\/0.999\"]}}",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "cid": "campaign111",
      "crid": "101409",
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.7 Native Bid Response (ext.admnative)

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "native",
        "admnative": {
          "native": {
            "link": {
              "url": "http://www.mopub.com"
            },
            "imptrackers": [
              "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
              "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
            ],
            "assets": [{
                "id": 1,
                "title": {
                  "text": "This is the title"
                }
              },
              {
                "id": 2,
                "img": {
                  "url": "http://d30x8mtr3hjnzo.cloudfront.net/creatives/8003cbe865a24282a47ce346ff271000",
                  "h": 627,
                  "w": 1200
                }
              },
              {
                "id": 3,
                "img": {
                  "url": "http://d30x8mtr3hjnzo.cloudfront.net/creatives/a7b528d5c537426da5e42f418cc35e47",
                  "h": 80,
                  "w": 80
                }
              },
              {
                "id": 4,
                "data": {
                  "value": "This is the text"
                }
              },
              {
                "id": 5,
                "data": {
                  "value": "CTA Text"
                }
              },
              {
                "id": 6,
                "data": {
                  "value": "4.5"
                }
              }
            ]
          }
        }
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB3"
      ],
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "cid": "campaign111",
      "crid": "101409",
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.8 Native Video Bid Response (adm)

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "native"
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adm": "{\r\n   \"native\":{\r\n      \"link\":{\r\n         \"url\":\"http:\/\/www.mopub.com\"\r\n      },\r\n      \"imptrackers\":[\r\n         \"https:\/\/imptrackers1.com\/mopub\/win\/${AUCTION_ID}\/${AUCTION_BID_ID}\/${AUCTION_IMP_ID}\/${AUCTION_SEAT_ID}\/${AUCTION_AD_ID}\/${AUCTION_PRICE}\/0.999\",\r\n         \"https:\/\/imptrackers2.com\/mopub\/win\/${AUCTION_ID}\/${AUCTION_BID_ID}\/${AUCTION_IMP_ID}\/${AUCTION_SEAT_ID}\/${AUCTION_AD_ID}\/${AUCTION_PRICE}\/0.999\"\r\n      ],\r\n      \"assets\":[\r\n         {\r\n            \"id\":1,\r\n            \"title\":{\r\n               \"text\":\"Title\"\r\n            }\r\n         },\r\n         {\r\n            \"id\":2,\r\n            \"img\":{\r\n               \"url\":\"http:\/\/d30x8mtr3hjnzo.cloudfront.net\/creatives\/8003cbe865a24282a47ce346ff271000\",\r\n               \"h\":627,\r\n               \"w\":1200\r\n            }\r\n         },\r\n         {\r\n            \"id\":3,\r\n            \"img\":{\r\n               \"url\":\"http:\/\/d30x8mtr3hjnzo.cloudfront.net\/creatives\/a7b528d5c537426da5e42f418cc35e47\",\r\n               \"h\":80,\r\n               \"w\":80\r\n            }\r\n         },\r\n         {\r\n            \"id\":4,\r\n            \"data\":{\r\n               \"value\":\"This is the text\"\r\n            }\r\n         },\r\n         {\r\n            \"id\":5,\r\n            \"data\":{\r\n               \"value\":\"CTA Text\"\r\n            }\r\n         },\r\n         {\r\n            \"id\":6,\r\n            \"data\":{\r\n               \"value\":\"4.5\"\r\n            }\r\n         },\r\n         {\r\n            \"id\":7,\r\n            \"video\":{\r\n               \"vasttag\":\"<<INSERT VAST XML>>\"\r\n            }\r\n         }\r\n      ]\r\n   }\r\n}",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "cid": "campaign111",
      "crid": "101409",
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.9 Native Video Bid Response (ext.admnative)

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "native",
        "admnative": {
          "native": {
            "link": {
              "url": "http://www.mopub.com"
            },
            "imptrackers": [
              "https://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
              "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
            ],
            "assets": [{
                "id": 1,
                "title": {
                  "text": "Title"
                }
              },
              {
                "id": 2,
                "img": {
                  "url": "http://d30x8mtr3hjnzo.cloudfront.net/creatives/8003cbe865a24282a47ce346ff271000",
                  "h": 627,
                  "w": 1200
                }
              },
              {
                "id": 3,
                "img": {
                  "url": "http://d30x8mtr3hjnzo.cloudfront.net/creatives/a7b528d5c537426da5e42f418cc35e47",
                  "h": 80,
                  "w": 80
                }
              },
              {
                "id": 4,
                "data": {
                  "value": "This is the text"
                }
              },
              {
                "id": 5,
                "data": {
                  "value": "CTA Text"
                }
              },
              {
                "id": 6,
                "data": {
                  "value": "4.5"
                }
              },
              {
                "id": 7,
                "video": {
                  "vasttag": "<<INSERT VAST XML>>"
                }
              }
            ]
          }
        }
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "cid": "campaign111",
      "crid": "101409",
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.10 Multi-Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz123456",
    "bid": [{
      "ext": {
        "imptrackers": [
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "https://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB1-6"
      ],
      "adm": "",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        6
      ],
      "cid": "campaign111",
      "crid": "101409",
      "h": 320,
      "w": 480,
      "impid": "1",
      "price": 0.999
    }, {
      "ext": {
        "imptrackers": [
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "https://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "567890",
      "adid": "123",
      "cat": [
        "IAB1-6"
      ],
      "adm": "adfas",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        6
      ],
      "cid": "campaign123",
      "crid": "1234567",
      "h": 320,
      "w": 480,
      "impid": "1",
      "price": 0.999
    }, {
      "ext": {
        "imptrackers": [
          "https://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "https://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "098765",
      "adid": "678",
      "cat": [
        "IAB1-6"
      ],
      "adm": "",
      "adomain": [
        "advertiserdomain.com"
      ],
      "bundle": "com.foo.mygame",
      "attr": [
        6
      ],
      "cid": "campaign567",
      "crid": "101567",
      "h": 320,
      "w": 480,
      "impid": "1",
      "price": 0.999
    }]
  }]
}

6.2.11 Inventory Package Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "crtype": "Image Ad",
        "imptrackers": [
          "http://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB18"
      ],
      "adm": "",
      "adomain": [
        "nike.com"
      ],
      "dealid": "ip_3ba84451c2f94b34af95effaf8c4fa9d",
      "cid": "campaign111",
      "crid": "101409",
      "h": 50,
      "w": 320,
      "impid": "1",
      "price": 5.00
    }]
  }]
}

6.2.12 Viewability Bid Response

{
  "bidid": "abc1234",
  "cur": "USD",
  "id": "1234567890",
  "seatbid": [{
    "seat": "xyz12345",
    "bid": [{
      "ext": {
        "vendor": [
          "ias"
        ],
        "crtype": "Image Ad",
        "imptrackers": [
          "http://imptrackers1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://imptrackers2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ],
        "nurls": [
          "http://nurl1.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999",
          "http://nurl2.com/mopub/win/${AUCTION_ID}/${AUCTION_BID_ID}/${AUCTION_IMP_ID}/${AUCTION_SEAT_ID}/${AUCTION_AD_ID}/${AUCTION_PRICE}/0.999"
        ]
      },
      "id": "12345678",
      "adid": "314",
      "cat": [
        "IAB18"
      ],
      "adm": "",
      "adomain": [
        "nike.com"
      ],
      "cid": "campaign111",
      "crid": "101409",
      "h": 50,
      "w": 320,
      "impid": "1",
      "price": 5.00
    }]
  }]
}

7. Auction Types

Auction Type Description Sample Request
Private Marketplace This is the how the current 1:1 deals work on MoPub. No changes are required.
Private_auction is set to 1 in the bid request
Only bid responses that contain a matching deal ID are accepted 
"pmp": {
  "deals": [{
    "at": 2,
    "bidfloor": 5.0,
    "id": "09e5793ab"
  }],
  "private_auction": 1
},
Inventory Packages This is the inventory package that will be used to pass the viewability deal ID.
Private_auction is set to 0 in the bid request.
Bid responses with or without a deal ID are accepted. If you are returning a campaign to measure viewability, respond with the deal ID in the bid response. If you do not have a campaign for viewability, your bid response may fallback to an open auction bid response 
"pmp": {
  "deals": [{
    "at": 2,
    "bidfloor": 5.0,
    "id": "ip_3ba8b451c2f94b34af95effaf8c4fa9d"
  }],
  "private_auction": 0
},
Open Auction PMP object is not present in the bid request N/A - PMP object is not present in the bid request

8. Changelog

  • [07/23/2019]
    • seatbid.bid.iurl is now an optional field
  • [11/12/2018]
    • seatbid.bid.ext.loadtrackers supported
  • [10/17/2018]
    • As of October 2018, max title and text character limits for native ads have increased to 50 and 150, respectively.
  • [9/27/2018]
    • imp.video.startdelay supported
  • [8/14/2018]
    • bidrequest.device.connectiontype supports values 4, 5 and 6 for cellular connection granularity, when available.
    • bidrequest.tmax supported
  • [4/24/2018]
    • GDPR support updates
    • Added bidrequest.user.ext.consent (Section 3.2.13.1)
    • Added bidrequest.regs.ext.gdpr (Section 3.2.16.1)
  • [3/28/2018]
    • Added wmin and hmin to the imp.native.request main image
    • Main images minimum size dimensions now 800x417. (1200x627, 1200x628 and 800x418 recommended)
  • [2/12/2018]
    • TAG Payment ID supported
  • [9/11/2017]
    • Viewability vendor flag supported
  • [8/24/2017]
    • Added documentation for viewability support (Section 2.10)
      • Added metric to imp.ext (Section 3.2.2.1)
      • Added metric object array (Section 3.2.2.1.1)
      • Added vendor field to bid.ext (Section 4.2.4)
      • Added example viewability bid request (Section 6.1.8)
      • Added example viewability bid response (Section 6.2.12)
    • Added information about inventory packages
      • Added Auction Types table (Section 7)
      • Added example inventory package request (Section 6.1.7)
      • Added example inventory package response (Section 6.1.8)
      • Clarified that pmp.private_auction will always be set to 0 for inventory packages
      • Clarified use of dealid for inventory package in bid response dealid description
  • [5/10/2017]
    • Added Multi-Bid Response example
  • [1/07/2017]
    • Added MRAID Video Bid Response example
  • [11/15/2016]
    • Added support for device.pxratio
  • [10/18/2016]
    • Added support for opt-in rewarded video
      • Updated video extension description to note that the extension will only be present on opt-in rewarded video (Section 3.2.4)
      • Added video.ext object for opt-in rewarded video support (Section 3.2.4.1)
        • Attributes skip and videotype have been added
      • Added rewarded video bid request example (Section 6.1.6)
      • Added clarifications that VAST video and rewarded video bid responses are identical (Section 2.9 and Section 6.2.3)
  • [9/19/2016]
    • Removed references to native starrating asset id
  • [3/15/16]
    • Added clarifications to nurl and impression tracking description (Section 2.4)
      • Clarified nurl is sent server side
      • Clarified imptrackers is a required bid response field
    • Added clarifications to Native Browser Clicks description (Section 2.6.1):
      • Clarified urls must be encoded
      • Updated example to include an encoded url
    • Added note in the native request layout description to refer to list 7.1 of OpenRTB Native spec
    • Updated domain attribute to all lowercase values (Section 3.2.6)
  • [10/12/15]
    • Changed native bid response image width and height to ‘required’ from ‘recommended’ in section 4.2.5.4
    • Clarified that native main image and icon image width and height are required in the bid response (Section 2.7
  • [10/9/15]
    • Full support for bidrequest.imp.secure therefore it is no longer hard coded to 0
      • Updated bidrequest.imp.secure description
      • Removed bidrequest.imp.secure from Section 2.2
    • Updated Section 2.2 bidresponse.seatbid.bid.cat description from preferred to required
  • [9/24/15]
    • Changed native icon image minimum size requirement to 80x80px from 500x500px
      • Updated section 2.7 description
      • Updated assets.img.wmin and assets.img.hmin description in section 3.2.19.3
    • Changed native main image pixel requirements to 1200x627 from 1200x628
      • Updated assets.img.w description in section 3.2.19.3
  • [9/10/15] Series of modifications and clarifications
    • Added sample bid requests and bid responses (Section 6)
    • Added section ‘Basic Auction on the MoPub Exchange’ to the Overview
    • Added section 2.9 to provide more information on VAST support and bid response requirements
    • Updated bid.ext.crtype description to note VAST 3.0 support
    • Removed support for pmp.deals.wseat
    • Added support for video.api
    • Added a note on native icon image requirements in section 2.7
      • Changed native icon image minimum size requirement to 80x80px from 500x500px (Section 2.7)
      • Updated assets.img.wmin and assets.img.hmin description in section 3.2.19.3
    • Changed native main image pixel requirements to 1200x627 from 1200x628
      • Updated assets.img.w description in section 3.2.19.3
  • [9/2/15]
    • Modified deeplink formatting in section 2.6
      • Changed from “Deep link” to “deeplink”
    • Clarified that native.link.clicktrackers is not supported (Section 4.2.5.7)
  • [8/26/15]
    • Updated bid.ext.crtype requirement from recommended to required for some formats
    • Updated native.request field type from an object to a string
      • Updated section 2.7 description
  • [7/24/15]
    • Added clarifying note on leading nested “native” object inside the request object
  • [7/27/15]
    • Clarified changes in bid response extensions for video bids and fields that are removed in 2.3.
  • [7/8/15]
    • Added section 2.8 note on SSL support for comments on support for SSL creative + future support of SSL in bid request/response
    • Updates to Section 4.3 on substitution macros
      • Added clarification on what bid response fields support substitution
      • Added note on support for base 64 encoding of price macro
    • Updated section 2.6 on click tracking extensions with information on “Deep Link+” and changes to the bid request location of nativebrowserclick
      • New imp.ext object for two new fields (dlp & brsrclk)
      • imp.banner.ext.nativebrowserclick field is now imp.ext.brsrclk
    • Updated bid.ext field for array of nurls - now called “nurls” not “nurl”
    • Updated video.protocols description to note VAST 3.0 support
    • Updated video.companiontype to note broader support for HTML and iFrame companions on some inventory
    • Added support for native.request.layout (supporting layouts 3 & 6)
    • Added note in bid.adm for VAST noting that VAST URLs must be submitted as wrapper tags / XML
  • [6/14/15] Clarified how device.carrier is set in bid requests.  
    • Unchanged behavior from MoPub RTB 2.1.

This document may include materials licensed under the Creative Commons Attribution 3.0 license by OpenRTB, based on a work at http://openrtb.github.io/OpenRTB/.

The OpenRTB project is released under a BSD 3-Clause license (c) 2014 OpenRTB Project, All Rights Reserved.

Last updated August 26, 2019

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2019 MoPub (a division of Twitter, Inc.)