MoPub Advanced Bidding OpenRTB 2.5 and Native 1.2 Specification
- Contents
- 1. Overview
- 2. Instructions for Using this Guide
- 3. Bid Request Variables and Definitions
- 4. Bid Response Variables and Definitions
- 5. Enumerated Lists Specification
- 6. Bid Request and Response Samples
- 7. Changelog
Last Updated: April 2020
This specification is for MoPub’s Advanced Bidding Partners who are beginning the integration process. It uses OpenRTB 2.5 + Native Ads 1.2 (subsequently referred to as “OpenRTB native subspec”) spec protocols and explains MoPub’s use of flexible fields.
Contents
2. Instructions for Using This Guide
3. Bid Request Variables and Definitions
- 3.2.1 Object: bidrequest
- 3.2.2 Object: source
- 3.2.3 Object: regs
- 3.2.4 Object: imp
- 3.2.5 Object: metric
- 3.2.6 Object: banner
- 3.2.7 Object: video
- 3.2.9 Object: native
- 3.2.10 Object: format
- 3.2.11 Object: pmp
- 3.2.12 Object: deal
- 3.2.14 Object: app
- 3.2.15 Object: publisher
- 3.2.18 Object: device
- 3.2.19 Object: geo
- 3.2.20 Object: user
- 3.2.23 Object: imp.native.request (4.1 in OpenRTB Native subspec)
- 3.2.23.1 Object: native.request.assets (4.2 in OpenRTB Native subspec)
- 3.2.23.2 Title Object (4.3 in OpenRTB native subspec)
- 3.2.23.3 Image Object (4.4 in OpenRTB Native subspec)
- 3.2.23.4 Video Object (4.5 in OpenRTB Native subspec)
- 3.2.23.5 Data Object (4.6 in OpenRTB Native subspec)
- 3.2.23.6 Event Trackers Object (4.7 in OpenRTB native subspec)
4. Bid Response Variables and Definitions
- 4.2.1 Object: bidresponse
- 4.2.2 Object: seatbid
- 4.2.3 Object: bid
- 4.2.4 Object: bid.ext
- 4.2.5 Native Ad Creative JSON (5.1 in OpenRTB Native subspec)
- 4.2.5.1 Object: native (5.1 in OpenRTB Native subspec)
- 4.2.5.2 Object: native.assets (5.2 in OpenRTB Native subspec)
- 4.2.5.3 Title Object (5.3 in OpenRTB Native subspec)
- 4.2.5.4 Image Object (5.4 in OpenRTB Native subspec)
- 4.2.5.5 Data Object (5.5 in OpenRTB Native subspec)
- 4.2.5.6 Video Object (5.6 in OpenRTB Native subspec)
- 4.2.5.7 Link Object (5.7 in OpenRTB Native subspec)
- 4.2.5.8 Event Tracker Object (5.8 in OpenRTB native subspec)
- 4.3 Substitution Macros
5. Enumerated Lists Specification
6. Bid Request and Response Samples
1. Overview
This specification describes the integration method for ad networks to bid on mobile app inventory in real time through MoPub’s Advanced Bidding integration.
Advanced Bidding enables network demand sources to submit a real-time price at the time of the ad request. MoPub then uses that price to select a winning bid in an auction that includes other Advanced Bidding partners as well as the MoPub Marketplace. The Advanced Bidding specification uses all of the protocols and naming conventions of the OpenRTB 2.5 + Native Ads 1.2. Advanced Bidding also allows for the preservation of a network partner’s core SDK technology.
2. Instructions for Using this Guide
Have the OpenRTB 2.5 available when you consult this spec. Read this specification fully, referring to callouts to the OpenRTB 2.5 spec as necessary. Sections 3 and 4 contain information and nuances specific to MoPub’s Advanced Bidding implementation. Any values present in the OpenRTB 2.5 but not used in our Advanced Bidding spec are denoted by strikethrough font. Refer to the sample bid request and bid response formats in Section 6.
Our specification also includes support for the OpenRTB Native Ads 1.2 spec, subsequently referred to as “OpenRTB native subspec”.
2.1 MoPub Marketplace Spec vs. Advanced Bidding Spec
The Advanced Bidding bid request is very similar to the bid request that MoPub sends to Marketplace DSPs. There are Marketplace-specific values in this Advanced Bidding spec that are irrelevant to Advanced Bidders, and that can be ignored (Section 2.1.1).
Likewise, there are bid response values in this specification that are required or used by Marketplace that are optional for Advanced Bidders (Section 2.1.2).
2.1.1 Optional Bid Request Values for Advanced Bidders
The following values are present in the bid request both for Marketplace and Advanced Bidding, however only Marketplace bidders are required to respect them.
bcat
(blocked advertiser categories)badv
(blocked advertiser by domain)battr
(blocked creative attributes)btype
(blocked banner types)tagid
(MoPub-generated ad unit/placement ID)pmp
(Private Marketplace field)deal
(Private Marketplace field)metric
(used for viewability by MPX only)bapp
bseat
wseat
imp.video.protocols
imp.video.skipmin
imp.video.skipafter
imp.video.playbackmethod
imp.metric.type
imp.metric.vendor
2.1.2 Bid Response Values Optional for Advanced Bidders
The following bid response values are required for Marketplace bidders but optional for Advanced Bidders:
dealid
(Not relevant to Advanced Bidders, used for Private Marketplace deals only)minduration
maxduration
imptrackers
(These should not be sent as they will not be fired for Advanced Bidders)native.assets
(Advanced Bidders use their own SDK for rendering and therefore do not pass raw native assets)
2.1.3 Additional Key Differences
The following notes apply to Advanced Bidding use of the spec only; they do not apply to the MoPub Marketplace specification that is used for DSPs:
-
The
ext
attribute in theimp
object discussed in Section 3.2.4.2 is used to capture the unique placement IDs and application IDs specific to your network. These IDs are generated by the publisher in the Advanced Bidder’s UI, and trafficked in the MoPub UI. -
Advanced Bidders have the option to pass a single data packet from their SDK to MoPub via the adapters. If passed, this data packet will be present in the
buyeruid
, an attribute in theuser
object, and may contain any custom data a network wishes to receive in the bid request. This is not required. -
Advanced Bidding header format:
{"Content-Type" : "application/json; charset=UTF-8", "X-MPX-Mode" : "AB", "X-OpenRTB-Version" : "2.5"}
2.2 SDK Deployment and Adapter Instructions
Publishers who participate in Advanced Bidding must be on MoPub SDK v.5.5+ and the supported network SDK versions and adapters listed.
2.2.1 Changes to Mediation Adapters
A few changes are required for the mediation adapters to work with Advanced Bidding. The MoPub team will provide all necessary details to the network. Some of these changes include:
-
Network Adapters must be set up to pass an additional field to the network. This field contains data passed via the
adm
field in the bid response:-
Android:
adm
in theserverExtras
map -
iOS:
adMarkup
field in the ad request
-
-
There is a new
AdapterConfiguration
interface for both Android and iOS. Adapters must create anAdapterConfiguration
class that implements this interface and returns the Advanced Bidding token.
2.2.2 After the Auction Process
Winning bid responses are then sent through MoPub’s SDK to the partner SDK via adapters, which the publisher must integrate into the app. The partner SDK can then render the ad.
3. Bid Request Variables and Definitions
This section contains information and nuances specific to MoPub’s Advanced Bidding implementation of the OpenRTB 2.5 spec. Types and descriptions from OpenRTB are not included below. For simplicity, this section’s naming follows OpenRTB 2.5 spec conventions. Any objects or attributes from OpenRTB that MoPub Advanced Bidding does not support are denoted by strikethrough font.
All available fields are populated in the request. If a parameter is not available, MoPub removes it instead of passing a null value or empty string. Therefore, if this spec describes a field as not always being passed, it is because that parameter is not always present in the request.
Note the following key differences between the Advanced Bidding specification and the MoPub Marketplace specification. Both are based on the OpenRTB 2.5 specification.
Object | Section | Description |
---|---|---|
bidrequest
|
3.2.1 | Top-level object. |
source
|
3.2.2 | Request source details on post-auction decisioning (e.g., header bidding) |
regs
|
3.2.3 | Regulatory conditions in effect for all impressions in this bid request. |
imp
|
3.2.4 | Container for the description of a specific impression; at least 1 per request. |
metric
|
3.2.5 | A quantifiable often historical data point about an impression. |
Banner
|
3.2.6 | Details for a banner impression (incl. in-banner video) or video companion ad. |
Video
|
3.2.7 | Details for a video impression or the video asset of a native impression. |
Audio |
||
Native
|
3.2.9 | Container for a native impression conforming to the Native Ad Spec. |
Format
|
3.2.10 | An allowed size of a banner. |
Pmp
|
3.2.11 | Collection of private marketplace (PMP) deals applicable to this impression. |
Deal
|
3.2.12 | Deal terms pertaining to this impression between a seller and buyer. |
Site |
||
App
|
3.2.14 | Details of the application calling for the impression. |
publisher
|
3.2.15 | Entity that controls the content of and distributes the site or app. |
Content |
||
Producer |
||
Device
|
3.2.18 | Details of the device on which the content and impressions are displayed. |
Geo
|
3.2.19 | Location of the device or user's home base depending on the parent object. |
User
|
3.2.20 | Human user of the device; audience for advertising. |
Data
|
3.2.21 | Collection of additional user targeting data from a specific data source. |
Segment
|
3.2.22 | Specific data point about a user from a specific data source. |
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.4) representing the impressions offered. Only one impression object will be passed. |
app
|
No (either site or app always) | Details via an App object (Section 3.2.14) 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.18) about the user's device to which the impression will be delivered. |
user
|
No | Details via a User object (Section 3.2.20) about the human user of the device; the advertising audience. |
test
|
No | Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. Sent to Advanced Bidders only. |
at
|
Yes | Always set to "1" for MoPub, meaning 1st 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 550ms. For partners connected to our APAC POP, the default value is typically 180 ms. |
wseat
|
No | Allowlist 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. |
bseat
|
No | Block list of buyer seats restricted from bidding on this impression. Seat IDs must be communicated between bidders and the exchange a priori. Omission implies no seat restrictions. |
bcat
|
No | Blocked advertiser categories using the IAB content categories. Refer to section 5.1 of the OpenRTB 2.5 spec. |
badv
|
No | Block list of advertisers by their top-level domains (e.g., "ford.com"). |
bapp
|
No | Block list of applications by their platform-specific exchange-independent application identifiers. On Android, these should be bundle or package names (e.g., "com.foo.mygame"). On iOS, these are numeric IDs. |
source
|
No | A source object that provides data about the inventory source and which entity makes the final decision. |
regs
|
No | A Regs object (Section 3.2.3) 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: source
Attribute | Always Passed | Description |
---|---|---|
pchain
|
yes | Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v1.0. |
3.2.3 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.3.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.4 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) |
metric
|
yes | An array of Metric Object (Section 3.2.5) |
banner
|
only for banner imps | A Banner object (Section 3.2.6); required if this impression is offered as a banner ad opportunity. |
video
|
only for video imps | A Video object (Section 3.2.7); required if this impression is offered as a video ad opportunity. |
native
|
only for native imps | A Native object (Section 3.2.9); required if this impression is offered as a native ad opportunity. |
pmp
|
no | A pmp object (Section 3.2.11) containing any private marketplace deals in effect for this impression. |
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. |
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. |
exp
|
yes | Advisory as to the number of seconds that may elapse between the auction and the actual impression. Fixed value of 14400 = 4 hours * 3600 second/hour. |
ext
|
no | Placeholder for exchange-specific extensions to OpenRTB. |
3.2.4.1 Object: imp.ext
Attribute | Always Passed | Description |
---|---|---|
reward
|
no | Indicates whether this is a opt-in rewarded video. Where 0 = no, 1 = yes. |
networkids
|
yes | IDs associated with Advanced Bidders |
3.2.4.2 Object: imp.ext.networkids
Attribute | Always Passed | Description |
---|---|---|
appid
|
no | Advanced Bidder’s unique identifier for publisher’s Application in bidder’s system, matches what is entered in MoPub UI settings. |
placementid
|
yes | Advanced Bidder’s unique identifier for publisher’s placement in bidder’s system, matches what is entered in MoPub UI settings. |
3.2.5 Object: metric
Object Array: If the inventory supports viewability, the metric object will be present in the bid request. Note that these values do not apply to demand sources that render creative via their own SDK, such as Advanced Bidders.
Attribute | Always Passed | 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.6 Object: banner
Attribute | Always Passed | Description |
---|---|---|
format
|
no | Array of format objects (Section 3.2.10) representing the banner sizes permitted. If none are specified, then use of the h and w attributes is highly recommended. |
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. |
btype
|
yes | Blocked banner ad types. Refer to List 5.10. Set to [4], to reflect our platform-wide prohibition on IFRAMEs |
battr
|
yes | Blocked creative attributes. Refer to List 5.11. Please refer to MoPub's demand side policies for detailed requirements. |
pos
|
yes | Ad position on screen. Refer to List 5.12. Position is set to 1 ("above the fold", i.e. visible) |
api
|
no | List of supported API frameworks for this impression. Refer to List 5.13. 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 |
3.2.7 Object: video
Advanced Bidders may ignore these values as they do not apply to creative rendered by third party SDKs.
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. |
protocols
|
yes | Array of supported video bid response protocols. Refer to List 5.15. 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.17 for additional generic values. MoPub always passes 0. |
placement
|
yes | Placement type for the impression. Refer to List 5.16. |
linearity
|
yes | Indicates if the impression must be linear, nonlinear, etc. Refer to List 5.14. MoPub only supports linear video, i.e., linearity = 1 |
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. |
skipmin
|
yes | Videos of total duration greater than this number of seconds can be skippable; only applicable if the ad is skippable. |
skipafter
|
yes | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. |
battr
|
yes | Blocked creative attributes. Refer to List 5.11. Please refer to MoPub's demand side policies for detailed requirements. |
playbackmethod
|
yes | Allowed playback methods where 1 = on, 2 = off. If none specified, assume all are allowed. |
pos
|
no | Ad position on screen. Refer to List 5.12. |
api
|
n/a | List of supported API frameworks for this impression. Refer to List 5.13. 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.18. Some inventory supports all companion types and others static only. Please target the correct companion types 1,2,3. |
3.2.9 Object: native
Attribute | Always Passed | Description |
---|---|---|
request
|
yes | Request payload complying with the Native Ad Specification. Note that this is a string. Refer to imp.native.request. |
ver
|
yes | Version of the Native Ad Specification to which request complies; highly recommended for efficient parsing. |
battr
|
yes | Blocked creative attributes. Refer to List 5.11. Please refer to MoPub's demand side policies for detailed requirements. |
3.2.10 Object: format
Attribute | Always Passed | Description |
---|---|---|
w
|
no | Width in device independent pixels (DIPS). |
h
|
no | Height in device independent pixels (DIPS). |
3.2.11 Object: pmp
Private Marketplace deals are not available to Advanced Bidders. Therefore, Advanced Bidders should ignore these values.
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.12) objects that convey the specific deals applicable to this impression. |
3.2.12 Object: deal
Private Marketplace deals are not available to Advanced Bidders. Therefore, Advanced Bidders should ignore these values.
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. |
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=1 |
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. |
3.2.14 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. |
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 section 5.1 of the OpenRTB 2.5 spec. These are self declared by publisher. |
ver
|
no | Application version. passed when available |
publisher
|
yes | Details about the Publisher (Section 3.2.15) of the app. |
3.2.15 Object: publisher
Attribute | Always Passed | Description |
---|---|---|
id
|
yes | Exchange-specific publisher ID. |
name
|
yes | Publisher name (may be aliased at the publisher's request). |
3.2.18 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.19). |
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. |
make
|
no | Device make (e.g., “Apple”). |
model
|
no | Device model (e.g., “iPhone”). iOS will show the full device model name e.g. "iPhone 10,1" if known, or just e.g. "iPhone" if not. 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”). |
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 |
pxratio
|
yes | The ratio of physical pixels to device independent pixels. A float value from 0.75 thru 4. |
js
|
yes | Support for JavaScript, where 0 = no, 1 = yes. always = 1 |
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.3 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.19. |
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 |
3.2.18.1 Object: device.ext
Attribute | Always Passed | Description |
ifv | no | IDFV of device in that publisher. Only passed when IDFA is unavailable or all zeros. Currently passed for iOS only. |
atts | no |
(iOS Only) An integer passed to represent the app's app tracking authorization status, where 0 = not determined 1 = restricted 2 = denied 3 = authorized |
3.2.19 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. |
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 |
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 |
3.2.20 Object: user
Attribute | Always Passed | Description |
---|---|---|
buyeruid
|
no | Buyer-specific ID for the user as mapped by the exchange for the buyer. Sent to Advanced Bidders only. Max token size is 1kb. |
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. |
ext
|
no | Placeholder for exchange-specific extensions to OpenRTB. |
3.2.20.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.23 Object: imp.native.request
(4.1 in OpenRTB native subspec)
Note this is a JSON-encoded string.
Attribute | Always Passed | Description |
---|---|---|
plcmttype
|
no | The design/format/layout of the ad unit being offered. Refer to List 5.20. |
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' |
eventtrackers
|
yes | Specifies what type of event tracking is supported. MoPub supports event type “1”, which represents impression tracking, and method “1”, which represents a URL to be inserted as a 1x1 pixel at the time of the event. |
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.23.1 Object: native.request.assets
(4.2 in OpenRTB 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 8 = Sponsored By message where response should contain the brand name of the sponsor. |
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 |
3.2.23.2 Title Object (4.3 in OpenRTB native subspec)
Attribute | Always Passed | Description |
---|---|---|
len
|
yes | Maximum length of the text in the title element. |
3.2.23.3 Image Object (4.4 in OpenRTB 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. Refer to List 5.22., 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. |
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).
|
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).
|
3.2.23.4 Video Object (4.5 in OpenRTB native subspec)
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.15. We support Vast 2.0, 3.0 and wrappers. |
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.23.5 Data Object (4.6 in OpenRTB 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. Refer to List 5.21 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 |
3.2.23.6 Event Trackers Object (4.7 in OpenRTB native subspec)
Attribute | Always Passed | Description |
---|---|---|
event
|
yes | Type of event availbale for tracking. Refer to List 5.23. MoPub supports 1 = impression. |
methods
|
yes | Array of the types of tracking available for the given event. Refer to List 5.24. MoPub supports 1 = image-pixel. |
4. Bid Response Variables and Definitions
This section’s naming follows the OpenRTB 2.5 spec for simplicity, and the types are unchanged from the OpenRTB 2.3 spec. Attribute requirements reflect MoPub requirements and may differ from the OpenRTB 2.5 spec. Any objects and attributes not supported by MoPub are denoted by strikethrough font.
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". |
nbr
|
integer; recommended | Reason for not bidding. Refer to List 5.24 of the OpenRTB 2.5 spec. |
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. |
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) Refer to Section 2.5 on nurl support for changes with nurl and impression tracking in MoPub's RTB 2.3 protocol. |
burl |
string, optional | Billing notice URL called by the exchange when a winning bid becomes billable.. |
lurl |
string, recommended | Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros may be included. Refer to List 4.3 |
adm |
string, required | The mediation adapters will be setup to pass information included in this field to the network. Data must be obfuscated so it is not readable to MoPub. |
adm_native |
Native JSON Response | DSP can choose to pass the native ad JSON object directly into this field instead of serializing it in adm . If using adm_native , do not pass adm (we will ignore). |
adomain |
string array, recommended | Advertiser domain for block list checking (e.g., "ford.com"). App store bundles are not allowed in this field. Please refer to MoPub's demand side policies for detailed requirements on adomain. |
bundle |
string, recommended | 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. |
cid |
string, optional | Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. |
crid |
string, recommended | 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, optional | IAB content categories of the creative. Refer to section 5.1 of the OpenRTB 2.5 spec. |
attr |
integer array, optional | Required when applicable, creative attributes, an array of values taken from List 5.11 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. This field is not required for serving VAST video but is required for serving HTML or MRAID in-banner video. |
api |
integer | API required by the markup if applicable. Refer to List 5.13. |
protocol
|
integer | Video response protocol of the markup if applicable. Refer to List 5.15 |
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 | MoPub Support / Description |
---|---|---|
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 of strings; optional | Array of impression trackers (1st & 3rd Party) to be consistently tracked when MoPub records the billable impression event. Can be used in place of bid.burl. 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. |
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
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
native
|
object, required | top level native object |
4.2.5.1 Object: native
(5.1 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
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; one of imptrackers or eventtrackers required | Array of impression tracking URLs, expected to return a 1x1 image or 204 response - typically only passed when using 3rd party trackers. Can be used in place of `bid.adm_native.native.eventtrackers`. |
eventtrackers
|
array of strings; one of imptrackers or eventtrackers required | Array of tracking objects to run with the ad, in response to the declared supported methods in the request. Can be used in place of `bid.adm_native.native.imptrackers`. |
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. |
4.2.5.2 Object: native.assets
(5.2 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / 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; optional | 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. 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 |
1: asset object may contain only one of img, data or video.
4.2.5.3 Title Object (5.3 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
text
|
string, required | The text associated with the text element. |
4.2.5.4 Image Object (5.4 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
url
|
string; required | URL of the image asset |
h
|
integer; required | Height of the image |
w
|
integer; required | Width of the image |
4.2.5.5 Data Object (5.5 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
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". |
4.2.5.6 Video Object (5.6 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
vasttag
|
string; required | VAST XML per OpenRTB VAST URLs must be submitted as wrapper tags. |
4.2.5.7 Link Object (5.7 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / 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. |
4.2.5.8 Event Tracker Object (5.8 in OpenRTB native subspec)
Attribute | Type; Requirement | MoPub Support / Description |
---|---|---|
event
|
integer; required | Type of event to track. Refer to List 5.23. |
method
|
integer; required | Type of tracking requested. Refer to List 5.24. |
url
|
text; optional | URL of the image or js. MoPub only supports image. |
4.2.6 Object: bid.privacy
Attribute | Type; Requirement | MoPub Support / 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. Not supported in the bidresponse.bid.lurl field. |
${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. Not supported in the bidresponse.bid.lurl field. |
${AUCTION_MBR}
|
Market bid ratio = auction price after all fees / bid price. If auction has no winner, we send “undefined”. Only supported in seatbid.bid.lurl. |
${AUCTION_LOSS}
|
Loss reason codes. Refer to List 5.20. |
${AUCTION_MINIMUM_BID_TO_WIN}
|
The minimum bid that the bidder would have needed to win the auction. |
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.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}
5. Enumerated Lists Specification
5.1 Lists: OpenRTB 2.5 Spec
Refer to the Enumerated Lists section of the OpenRTB 2.5 specification.
5.10 Banner Ad Types
The following table indicates the types of ads that can be accepted by the exchange unless restricted by publisher site settings.
Value | Description |
---|---|
1
|
XHTML Text Ad (usually mobile) |
2
|
XHTML Banner Ad. (usually mobile) |
3
|
JavaScript Ad; must be valid XHTML (i.e., Script Tags Included) |
4
|
iframe |
5.11 Creative Attributes
The following table specifies a standard list of creative attributes that can describe an ad being served or serve as restrictions of thereof.
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 Provides Skip Button (e.g. VPAID-rendered skip button on pre-roll video) |
17
|
Adobe Flash |
5.12 Ad Position
The following table specifies the position of the ad as a relative measure of visibility or prominence. This OpenRTB table has values derived from the Inventory Quality Guidelines (IQG). Practitioners should keep in sync with updates to the IQG values as published on IAB.com. Values “4” - “7” apply to apps per the mobile addendum to IQG version 2.1.
Value | Description |
---|---|
0
|
Unknown |
1
|
Above the Fold |
2
|
DEPRECATED - May or may not be initially visible depending on screen size/resolution. |
3
|
Below the Fold |
4
|
Header |
5
|
Footer |
6
|
Sidebar |
7
|
Full Screen |
5.13 API Frameworks
The following table is a list of API frameworks supported by the publisher.
Value | Description |
---|---|
1
|
VPAID 1.0 |
2
|
VPAID 2.0 |
3
|
MRAID-1 |
4
|
ORMMA |
5
|
MRAID-2 |
6
|
MRAID-3 |
5.14 Video Linearity
The following table indicates the options for video linearity. “In-stream” or “linear” video refers to preroll, post-roll, or mid-roll video ads where the user is forced to watch ad in order to see the video content. “Overlay” or “non-linear” refer to ads that are shown on top of the video content.
Value | Description |
---|---|
1
|
Linear / In-Stream |
2
|
Non-Linear / Overlay |
5.15 Protocols
The following table lists the options for the various bid response protocols that could be supported by an exchange.
Value | Description |
---|---|
1
|
VAST 1.O |
2
|
VAST 2.0 |
3
|
VAST 3.0 |
4
|
VAST 1.0 Wrapper |
5
|
VAST 2.0 Wrapper |
6
|
VAST 3.0 Wrapper |
7
|
VAST 4.0 |
8
|
VAST 4.0 Wrapper |
9
|
DAAST 1.0 |
10
|
DAAST 1.0 Wrapper |
5.16 Video Placement Types
The following table lists the various types of video placements derived largely from the IAB Digital Video Guidelines.
Value | Description |
---|---|
1
|
In-Stream Played before, during or after the streaming video content that the consumer has requested (e.g., Pre-roll, Mid-roll, Post-roll). |
2
|
In-Banner Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery. |
3
|
In-Article Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message. |
4
|
In-Feed - Found in content, social, or product feeds. |
5
|
Interstitial/Slider/Floating Covers the entire or a portion of screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view). Note that a full-screen interstitial (e.g., in mobile) can be distinguished from a floating/slider unit by the imp.instl field. |
5.17 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 Companion Types
The following table lists the options to indicate markup types allowed for companion ads that apply to video and audio ads. This table is derived from VAST 2.0+ and DAAST 1.0 specifications. Refer to www.iab.com/guidelines/digital-video-suite for more information.
Value | Description |
---|---|
1
|
Static Resource |
2
|
HTML Resource |
3
|
Iframe Resource |
5.19 Connection Type
The following table lists the various options for the type of device connectivity.
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.20 Loss Reason Codes
The following table lists the options for an exchange to inform a bidder as to the reason why they did not win an impression.
Value | Description |
---|---|
3
|
Invalid Bid Response |
5
|
Invalid Auction ID |
100
|
Bid was Below Auction Floor |
102
|
Lost to a Higher Bid |
104
|
Buyer Seat Blocked |
204
|
Creative Filtered - Incorrect Creative Format |
205
|
Creative Filtered - Advertiser Exclusions |
206
|
Creative Filtered - App Bundle Exclusions |
207
|
Creative Filtered - Not Secure |
209
|
Creative Filtered - Category Exclusions |
210
|
Creative Filtered - Creative Attribute Exclusions |
1003
|
Invalid File Extension |
1006
|
Blocked Creative |
1008 †
|
Timeout |
1009 †
|
Non-HTTP OK |
1012
|
Invalid PMP Deal ID |
1013
|
Invalid PMP Domain |
1014
|
Invalid Asset |
1017
|
Unexpected Whitespace |
1021
|
Invalid Targeting Package Deal ID |
† Timeout (1008) and Non-HTTP OK (1009) loss codes are not available to network bidders by default. Reach out to your MoPub account team for access.
5.2 Lists: Native Subspec
Refer to the Reference Lists/Enumerations section in the Native 1.2 subspec.
5.20 Placement Type IDs (7.3 in OpenRTB native subspec)
The format of the ad you are purchasing, separate from the surrounding context:
Placement Type ID | Description |
---|---|
1
|
In the feed of content - for example as an item inside the organic feed/grid/listing/carousel. |
2
|
In the atomic unit of the content - IE in the article page or single image page. |
3
|
Outside the core content - for example in the ads section on the right rail, as a banner-style placement near the content, etc. |
4
|
Recommendation widget, most commonly presented below the article content. |
500+
|
To be defined by the exchange |
5.21 Data Asset Types (7.4 in OpenRTB native subspec)
Type ID | Name | Description | Format |
---|---|---|---|
1
|
sponsored | Sponsored By message where response should contain the brand name of the sponsor. Character limit: 25. | 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 |
5.22 Image Asset Types (7.5 in OpenRTB native subspec)
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.23 Event Types Table (7.6 in OpenRTB native subspec)
Type ID | Name | Description |
---|---|---|
1
|
impression | Impression |
2
|
viewable-mrc50 | Visible impression using MRC definition at 50% in view for 1 second |
3
|
viewable-mrc100 | 100% in view for 1 second (ie GroupM standard) |
4
|
viewable-video50 | Visible impression for video using MRC definition at 50% in view for 2 seconds |
500+
|
XXX | Reserved for Exchange specific usage numbered above 500 |
5.24 Event Tracking Methods Table (7.7 in OpenRTB native subspec)
Type ID | Name | Description |
---|---|---|
1
|
img | Image-pixel tracking - URL provided will be inserted as a 1x1 pixel at the time of the event. |
2
|
js | Javascript-based tracking - URL provided will be inserted as a js tag at the time of the event. |
500+
|
XXX | Reserved for Exchange specific usage numbered above 500 |
6. Bid Request and 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":[
"IAB1",
"IAB1-1",
"IAB3",
"books",
"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":1,
"badv":[
"competitor.com",
"advertiser.com",
"test.com"
],
"bapp":[
"com.foo.mygame",
"123456789",
"987654321"
],
"bcat":[
"IAB25",
"IAB26",
"IAB9-9",
"IAB3-7"
],
"device":{
"carrier":"311-480",
"connectiontype":2,
"dnt":0,
"geo":{
"city":"New York",
"country":"USA",
"lat":40.740987,
"lon":-73.999408,
"metro":"501",
"region":"NY",
"zip":"10011"
},
"h":1334,
"ifa":"7RA77E86-4C7D-4BEB-AA39-BD4B87C7140F",
"ip":"8.25.196.26",
"js":1,
"language":"en",
"make":"Apple",
"model":"iPhone10,1",
"os":"iOS",
"osv":"11.4.1",
"pxratio":2.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":750
},
"id":"529c9930-3f78-42a0-9bc8-f6befe6233ff",
"imp":[
{
"banner":{
"api":[
3,
5
],
"battr":[
3,
8,
9,
10,
14,
17,
6,
7
],
"btype":[
4
],
"format":[
{
"h":50,
"w":320
},
{
"h":50,
"w":300
},
{
"h":60,
"w":468
}
],
"h":50,
"pos":1,
"w":320
},
"bidfloor":1.12,
"displaymanager":"mopub",
"displaymanagerver":"5.3.0",
"exp":14400,
"ext":{
"networkids": {
"appid": "network_app_id",
"placementid": "network_placement_id"
},
"reward":0
},
"id":"1",
"instl":0,
"secure":1,
"tagid":"b12ae796186931bfe7aa39471487b980"
}
],
"regs":{
"ext":{
"gdpr":0
}
},
"source":{
"pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
},
"tmax":550,
"user": {
"buyeruid": "network_bid_token"
}
}
6.1.2 Native Bid Request
{
"app":{
"bundle":"com.foo.mygame",
"cat":[
"IAB1",
"IAB1-1",
"IAB3",
"books",
"business"
],
"id":"80e632d0108240949982301571d1aa0f",
"name":"App Name",
"publisher":{
"id":"04241e0b1cc98976858ce16377c7eef4",
"name":"Publisher_Name"
},
"storeurl":"https://play.google.com/store/apps/details?id=com.foo.mygame",
"ver":"4.4.3"
},
"at":1,
"badv":[
"competitor.com",
"advertiser.com",
"test.com"
],
"bapp":[
"com.foo.mygame",
"123456789",
"987654321"
],
"bcat":[
"IAB25",
"IAB26",
"IAB9-9",
"IAB3-7"
],
"device":{
"carrier":"222-77",
"connectiontype":0,
"dnt":0,
"geo":{
"city":"New York",
"country":"USA",
"lat":40.740987,
"lon":-73.999408,
"metro":"501",
"region":"NY",
"zip":"10011"
},
"h":1080,
"ip":"94.133.199.37",
"js":1,
"language":"es",
"make":"Micromax",
"model":"11",
"os":"Android",
"osv":"4.4.2",
"pxratio":1.96875,
"ua":"Mozilla/5.0 (Linux; Android 4.4.2; M8S Build/M8S.BCM4335) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/30.0.0.0 Safari/537.36",
"w":1125
},
"id":"c4c2f0b7-2670-459b-a052-e9d446c79b26",
"imp":[
{
"bidfloor":0.5,
"displaymanagerver":"5.11",
"exp":14400,
"Ext":{
"networkids": {
"appid": "network_app_id",
"placementid": "network_placement_id"
},
"reward":0
},
"id":"1",
"instl":0,
"native":{
"battr":[
8,
9,
10,
14,
6
],
"request":"{\"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\":25,\"type\":1},\"id\":8,\"required\":1},{\"data\":{\"type\":3},\"id\":6,\"required\":0},{\"data\":{\"len\":150,\"type\":2},\"id\":4,\"required\":1},{\"id\":1,\"required\":1,\"title\":{\"len\":50}}],\"eventtrackers\":[{\"event\":1,\"methods\":[1]}],\"plcmttype\":4}",
"ver":"1.2"
},
"secure":1,
"tagid":"9383795c9a344fada567c14b78362c51"
}
],
"regs":{
"ext":{
"gdpr":0
}
},
"source":{
"pchain":"74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
},
"tmax":550,
"user": {
"buyeruid": "network_bid_token"
}
}
6.1.3 Rewarded Video Request
{
"app": {
"bundle": "553834731",
"cat": [
"IAB1",
"IAB1-1",
"IAB3",
"books",
"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":1,
"badv":[
"competitor.com",
"advertiser.com",
"test.com"
],
"bapp":[
"com.foo.mygame",
"123456789",
"987654321"
],
"bcat":[
"IAB25",
"IAB26",
"IAB9-9",
"IAB3-7"
],
"device": {
"carrier": "311-480",
"connectiontype": 2,
"dnt": 0,
"geo": {
"city":"New York",
"country":"USA",
"metro":"501",
"region":"NY",
"zip":"10011"
},
"h": 1334,
"ifa": "7RA77E86-4C7D-4BEB-AA39-BD4B87C7140F",
"ip": "8.25.196.26",
"js": 1,
"language": "en",
"make": "Apple",
"model": "iPhone10,1",
"os": "iOS",
"osv": "11.4.1",
"pxratio": 2.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": 750
},
"id": "ea33701f-9b79-494b-9ded-d11c84aacf37",
"imp": [
{
"banner": {
"api": [
3,
5
],
"battr": [
3,
8,
9,
10,
14,
17
],
"btype": [
4
],
"h": 480,
"pos": 7,
"w": 320
},
"bidfloor": 5.5,
"displaymanager": "mopub",
"displaymanagerver": "5.10.0",
"exp": 14400,
"ext": {
"networkids": {
"appid": "network_app_id",
"placementid": "network_placement_id"
},
"reward": 1
},
"id": "1",
"instl": 1,
"secure": 1,
"tagid": "2rc4dd1bfd5a45b3a08c4td63053abf8",
"video": {
"battr": [
3,
8,
9,
10,
14,
17
],
"companiontype": [
1,
2,
3
],
"h": 480,
"linearity": 1,
"maxduration": 30,
"mimes": [
"video/3gpp",
"video/3gpp2",
"video/mp4",
"video/quicktime",
"video/x-m4v"
],
"minduration": 0,
"placement": 5,
"playbackmethod": [
1
],
"pos": 7,
"protocols": [
2,
5,
3,
6
],
"skip": 0,
"skipafter": 30,
"startdelay": 0,
"w": 320
}
}
],
"regs": {
"ext": {
"gdpr": 0
},
"networkids": {
"appid": "network_app_id",
"placementid": "network_placement_id"
}
},
"source": {
"pchain": "74b46c0ea83967ca:fa167489379c4e78b9e164b22e51965a"
},
"tmax": 550,
"user": {
"buyeruid": "network_bid_token"
}
}
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":"D79978C1D1A4418F8C4CAFBB788E63E1",
"cur":"USD",
"id":"529c9930-3f78-42a0-9bc8-f6befe6233ff",
"seatbid":[
{
"seat":"xyz12345",
"bid":[
{
"adid":"1068395",
"adm":"network_specific_content",
"bundle":"com.foo.mygame",
"adomain":[
"advertiserdomain.com"
],
"h":"50",
"w":"320",
"cat":[
"IAB-3"
],
"cid":"138880",
"crid":"678682",
"burl":"http://burl.com/v1/pixel/rtb/impression/49D757EC10DC4D02?rtbP=${AUCTION_PRICE}&rtbId=${AUCTION_ID}",
"lurl":"http://lurl.com/v1/pixel/rtb/loss/9619/${AUCTION_MBR}",
"nurl":"http://nurl.com/v1/pixel/rtb/win/49D757EC10DC4D0295D03B44A1F2F4F4?rtbP=${AUCTION_PRICE}&rtbId=${AUCTION_ID}",
"id":"9f7d67d1-8f78-4a64-b0a2-64cbc866065a",
"impid":"1",
"price":6.0
}
]
}
]
}
6.2.2 Native Bid Response
{
"bidid":"D79978C1D1A4418F8C4CAFBB788E63E1",
"cur":"USD",
"id":"529c9930-3f78-42a0-9bc8-f6befe6233ff",
"seatbid":[
{
"seat":"xyz12345",
"bid":[
{
"adid":"1068395",
"adm":"network_specific_content",
"bundle":"com.foo.mygame",
"adomain":[
"advertiserdomain.com"
],
"cat":[
"IAB1-6"
],
"cid":"138880",
"crid":"678682",
"burl":"http://burl.com/v1/pixel/rtb/impression/49D757EC10DC4D02?rtbP=${AUCTION_PRICE}&rtbId=${AUCTION_ID}",
"lurl":"http://lurl.com/v1/pixel/rtb/loss/9619/${AUCTION_MBR}",
"nurl":"http://nurl.com/v1/pixel/rtb/win/49D757EC10DC4D0295D03B44A1F2F4F4?rtbP=${AUCTION_PRICE}&rtbId=${AUCTION_ID}",
"id":"9f7d67d1-8f78-4a64-b0a2-64cbc866065a",
"impid":"1",
"price":6.0
}
]
}
]
}
7. Changelog
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 January 11, 2021
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.
© 2020 MoPub (a division of Twitter, Inc.)