MoPub Advanced Bidding OpenRTB 2.3 Specification

Last Updated: January 2019

This specification is for MoPub’s Advanced Bidding Partners who are beginning the integration process. It uses IAB OpenRTB API Specification v.2.3 (subsequently referred to as “OpenRTB native subspec”) protocols and explains MoPub’s use of flexible fields.

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. For Server-Side Partners: MoPub SDK Functionality

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.3 spec. 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.3 spec available when you consult this spec. Read this specification fully, referring to callouts to the OpenRTB 2.3 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.3 spec 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 Dynamic Native Ads API Specification v.1.0, 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 Shared Bid Request Values Irrelevant to Advanced Bidders

The following values are present in the bid request both for Marketplace and Advanced Bidding, but are irrelevant to Advanced Bidders:

  • 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)
  • brsrclk
  • dlp
  • metric (used for viewability by MPX only)

2.1.2 Shared Bid Response Values Optional for Advanced Bidders

The following bid response values are required for Marketplace bidders but optional for Advanced Bidders:

  • adomain (adomain for blocklist checking)
  • cat (advertiser categories)
  • crid (creative ID)
  • cid (campaign ID)
  • attr (creative attributes)
  • dealid (Private Marketplace field)
  • duration
  • imptrackers
  • iurl
  • 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 the imp object discussed in Section 3.2.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.

  • Optionally use buyeruid, an attribute in the user object, for any custom user 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.3"}
    
  • Any functionality that is custom to the MoPub SDK does not apply if the partner SDK is rendering the creative. Refer to Section 7 below.

2.2 SDK Deployment and Adapter Instructions

Publishers who participate in Advanced Bidding must be on MoPub SDK v.5.0+ 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 the serverExtras map

    • iOS: adMarkup field in the ad request

  • There is a new AdapterConfiguration interface for both Android and iOS. Adapters must create an AdapterConfiguration 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. These adapters are similar to our current adapters, with additional support for Advanced Bidding. 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.3 spec. For simplicity, this section’s naming follows OpenRTB 2.3 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.3 spec specification.

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

Top-level object.

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 the bid response).
imp Yes Array of imp objects (Section 3.2.2) representing the impressions offered. Only one impression object is 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 is delivered.
user No Details via a User object (Section 3.2.13) about the human user of the device; the advertising audience.
test integer;
default 0
Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode.
at Yes Always set to ‘1’ for MoPub meaning 1st price auction.
tmax n.a Maximum time in milliseconds to submit a bid to avoid timeout. This value is commonly communicated offline.
wseat n.a 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.
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 n.a Placeholder for exchange-specific extensions to the OpenRTB 2.3 spec.

3.2.2 Object: imp

Container for the description of a specific impression; at least 1 per request.

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 Passes '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 MoPub Identifier for specific ad placement 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 “ad unit” 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 the OpenRTB 2.3 spec.
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 Object Array: If the inventory supports viewability, the metric object is present in the bid request.
networkids yes IDs associated with Advanced Bidders
3.2.2.1.1 Object: imp.ext.metric
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 is passed. If both are supported, both are passed.
3.2.2.1.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.3 Object: banner

Details for a banner impression (including in-banner video) or video companion ad.

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 the OpenRTB 2.3 spec.

3.2.4 Object: video

Details for a video impression or the video asset of a native impression.

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 reflect what the specific inventory source supports, because some inventory only support 2.0; and others support both 2.0 and 3.0.
w yes Width of the video player in pixels.
h yes Height of the video player in pixels.
startdelay n/a Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. Refer to List5.10. for additional generic values.
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 allows 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 allows 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

Container for a native impression conforming to the Native Ad Spec.

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 the OpenRTB 2.3 spec.

3.2.6 Object: site

Details of the website calling for the impression.

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 is 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 the OpenRTB 2.3 spec.

3.2.7 Object: app

Details of the application calling for the impression.

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 passes the app store ID; Android passes 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 compliance. Only provided on iOS, example: http://itunes.apple.com/app/628677149, 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 the OpenRTB 2.3 spec.

3.2.8 Object: publisher

Entity that controls the content of and distributes the site or app.

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 the OpenRTB 2.3 spec.

3.2.11 Object: device

Details of the device on which the content and impressions are displayed.

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 to not target behaviorally. We 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 usually 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 shows iPhone, iPad, or iPod.
- Android has 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. Shows, for example '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 that this can differ from banner.h.
w no Physical width of the screen in pixels. This may depend 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 is formatted as follows:
{mcc}-{mnc}
For example, '310-053' represents Virgin Mobile US in the United States. When present, this value is passed along to the bidder via the SDK.
connectiontype no Network connection type. Refer to List 5.18. Note: Currently we cannot distinguish among these states and as a result do not pass '4','5', or '6' for this value.
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 on 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 only pass it if ifa is not present and a legacy Android ID or UDID is present.
dpidmd5 no Platform device ID (e.g., Android ID), hashed via MD5. Only pass with legacy IDs. We are deprecating this field and only pass it if ifa is not present and a legacy Android ID or UDID is 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 the OpenRTB 2.3 spec.

3.2.12 Object: geo

Location of the device or user’s home base depending on the parent object.

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 the OpenRTB 2.3 spec 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 the OpenRTB 2.3 spec.

3.2.13 Object: user

Human user of the device; audience for advertising.

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.
buyeruid yes Buyer-specific ID or token for the user as mapped by the bidder SDK at time of initialization. Max token size is 1kb. If not required by network, this field is populated with '1'.
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 n/a Placeholder for exchange-specific extensions to the OpenRTB 2.3 spec.

3.2.14 Object: data

Collection of additional user targeting data from a specific data source.

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 n/a Placeholder for exchange-specific extensions to the OpenRTB 2.3 spec.

3.2.15 Object: segment

Specific data point about a user from a specific data source.

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 the OpenRTB 2.3 spec.

3.2.16 Object: regs

Regulatory conditions in effect for all impressions in this bid request.

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 is only passed when coppa=1.
ext n/a Placeholder for exchange-specific extensions to the OpenRTB 2.3 spec.

3.2.17 Object: pmp

Collection of private marketplace (PMP) deals applicable to this impression.

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. Currently all pmps are considered “private” and pass a value of '1'.
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 the OpenRTB 2.3 spec.

3.2.18 Object: deals

Deal terms pertaining to this impression between a seller and buyer.

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 Allowlist 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. Is passed if publisher is allowlisting 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 the OpenRTB 2.3 spec.

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

Refer to Section 4.1 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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 subspec.
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. Refer Section 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 that 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.
3.2.19.1 Object: native.request.assets (4.2 in OpenRTB Native subspec)

Refer to Section 4.2 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

Attribute Always Passed Description
id yes Unique asset ID, assigned by exchange. Typically a counter for the array.
required yes Set to '1' if asset is required (exchange does not accept a bid without it).
title yes1 Title object for title assets. See TitleObject definition.
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 DataObject 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 OpenRTB native subspec)

Refer to Section 4.3 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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 OpenRTB Native subspec)

Refer to Section 4.4 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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. See "Table Image Asset Types" in the OpenRTB 2.3 spec for commonly used examples. Set to 3 for “main” image; set to 1 for “icon”.
h no Fixed height; set for main image only: always pass 1200.
w no Fixed width; set for main image only: always pass 627.
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. Only set for icon image: set to 80 - require 1:1 aspect ratio.
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. Only set for icon image: set to 80 - require 1:1 aspect ratio.
mimes n/a Allowlist of content MIME types supported. Popular MIME types include, but are not limited to “image/jpg” “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 OpenRTB 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 OpenRTB Native subspec)

Refer to Section 4.6 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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)
- “ctatext” = 12 (text format)
len no Maximum length of the text in the element’s response.
- “text” = 100
- “ctatext” = 15
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. Bid Response Variables and Definitions

This section’s naming follows the OpenRTB 2.3 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.3 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

Top-level object.

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.
ext object Placeholder for bidder-specific extensions to the OpenRTB 2.3 spec.

4.2.2 Object: seatbid

Collection of bids made by the bidder on behalf of a specific seat.

Attribute Type; Requirement MoPub Support / Description
bid object array; required Array of 1+ Bid objects (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. Must be an alphanumeric string, max 40 characters, ideally min 8 char. This should be logged and is primarily 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 the OpenRTB 2.3 spec.

4.2.3 Object: bid

An offer to buy a specific impression under certain business terms.

Attribute Type; Requirement MoPub Support / Description
id string; required Bidder generated bid ID to assist with logging/tracking.
impid string; required ID of the Imp object in the related bid request which should be set to '1'.
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 is sent on the server side when the auction is resolved if winner. See Section 2.5 on nurl support for changes with nurl and impression tracking in MoPub’s RTB 2.3 protocol.
adm string, optional Placement of the creative ad markup. For native ads however, we recommend that you 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, optional 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, optional 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: We recommend that you pass this in addition to adomain for app advertisements. We plan to require 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. Note that this must conform with the Exchange platform policies and is required for banner and native ads. Currently we do not require this for MRAID or VAST.
cid string, recommended Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative.
crid string, optional 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 List 5.1
attr integer array, optional 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, optional 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
h integer, optional Height of the creative in pixels.
w integer, optional Width of the creative in pixels.
ext object Placeholder for bidder-specific extensions to the OpenRTB 2.3 spec.

4.2.4 Object: bid.ext

Attribute Type; Requirement MoPub Support / 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 ignore it). Note: this is formerly admjson in the 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 default to contents of this variable and ignore the bid.nurl value).
imptrackers array, optional Array of impression trackers (1st and 3rd party) to be consistently tracked when MoPub records the billable impression event. This does not apply for native. See native object imptrackers.
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"), or native ('native'). This field is preferred for all other ad formats.

4.2.5 Native Ad Creative JSON (5.1 in OpenRTB Native subspec)

Refer to Section 5.1 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

Attribute Type; Requirement MoPub Support / Description
native object, required top level native object
4.2.5.1 Object: native (5.2 in OpenRTB Native subspec)

Refer to Section 5.2 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

Attribute Type; Requirement MoPub Support / 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 link object 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
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 OpenRTB Native subspec)

Refer to Section 5.3 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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 ignores this field for bids.
title object; optional2 Title object for title assets. See TitleObject definition.
img object; optional2 Image object for image assets. See ImageObject definition.
video object; optional2 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; optional2 Data object for ratings, prices etc. See DataObject definition
link object; optional2 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.

2 Asset object may contain only one of: title, img, data, or video.

4.2.5.3 Title Object (5.4 in OpenRTB Native subspec)

Refer to Section 5.4 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

Attribute Type; Requirement MoPub Support / 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 OpenRTB Native subspec)

Refer to Section 5.5 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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
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 OpenRTB Native subspec)

Refer to Section 5.6 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

Attribute Type; Requirement MoPub Support / 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 OpenRTB Native subspec)

Not currently supported

Attribute Type; Requirement MoPub Support / Description
vasttag string; required VAST XML per OpenRTB. VAST URLs must be submitted as wrapper tags.

Refer to Section 5.8 in the OpenRTB Dynamic Native Ads API Specification v.1.0.

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.
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.3 Substitution Macros

MoPub supports the following 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.

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. We only support Base 64 encoding. Bidders requiring the price to be encoded should use the following: ${AUCTION_PRICE:B64}.

5. Enumerated Lists Specification

Refer to the tables in the OpenRTB 2.3 spec and OpenRTB Native subspec.

6. Bid Request and Response Samples

6.1 Bid Request Example

The following bid requests are not fully formed. Please defer to the spec to see additional fields that may be passed.

{
  "app": {
    "cat": [
      "IAB3",
      "business"
    ],
    "id": "60697535e124452896e7acca4cb9df50",
    "name": "iOS Advanced Bidding Test App",
    "publisher": {
      "id": "app_id",
      "name": "Twitter"
    },
    "ver": "1.0"
  },
  "at": 2,
  "bcat": [
    "IAB25",
    "IAB26",
    "IAB7-39",
    "IAB8-18",
    "IAB8-5",
    "IAB9-9"
  ],
  "device": {
    "connectiontype": 2,
    "devicetype": 4,
    "dnt": 1,
    "geo": {
      "lat": 37.332331,
      "lon": -122.03122
    },
    "h": 1136,
    "ifa":"e785aa3f-0b58-4ff1-8758-74ae56a9b2d9"
    "hwv": "iPhone",
    "js": 1,
    "language": "en",
    "lmt": 1,
    "make": "Apple",
    "model": "iPhone",
    "os": "iOS",
    "osv": "6.1.3",
    "pxratio": 2.0,
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 6_1_3 like Mac OS X) AppleWebKit/536.26 (KHTML, like Gecko) Mobile/10B329",
    "w": 640
  },
  "ext": {
    "platformid": "MoPub"
  },
  "id": "f215fcc8-c94c-4564-829c-9a0f988ac5ca",
  "imp": [
    {
      "banner": {
        "api": [
          3,
          5
        ],
        "battr": [
          3,
          8,
          9,
          10,
          14,
          6
        ],
        "btype": [
          4
        ],
        "h": 50,
        "pos": 1,
        "w": 320
      },
      "bidfloor": 0.19,
      "displaymanager": "mopub",
      "displaymanagerver": "4.17.0 bidding",
      "ext": {
        "brsrclk": 1,
        "dlp": 1,
        "metric": [
          {
            "type": "viewability",
            "vendor": "ias"
          },
          {
            "type": "viewability",
            "vendor": "moat"
          }
        ],
        "networkids": {
          "appid": "app_id",
          "placementid": "adunit_id"
        }
      },
      "id": "1",
      "instl": 0,
      "secure": 0,
      "tagid": "52bff1f7ede547549bf85f38819a48de"
    }
  ],
  "user": {
    "buyeruid": "eJxFUMtqwzAQ/BedZSPJ79xkS25E/MKyE0IpJg4OTUlqQxpaKP33ruyWHHd2dmZ2vlEhm11Zb7pmX0m0ohhpqbUqi04JtEIydlIe+akl3Ci0XOGFFo+pb9HUF4nnh9yJOcIoKxOewTka3rtWo4dIo3IDE5sQ6hDGXMaCiHgscFxglXoraw17Sm0yXyVtrZp9J5TmcSZNghkXmy7hFY9VBlsAnx3sYg8HOMKUYMow9TENXoCaS6F4Y6y1rLcqMe4Ax20h5oDH8Wpfx+ne27fDdboMN3vs3452Plb3Xs8Inybr8/zxaiXyZryTWsqiW0v1tG7QCn7GiFdV3KrMxFuCt8Wci8AqrYyLdzix0+N6p0SzRiuHEfM0EM6laQl0/guYZXK+MRkhwWWAMSlr2S2CoTcMPWOGJGShlxbYUo2RG03UvBQyg+kr9Dvf/evNGEAdALs288Hm5xeJU3+M"
  }
}

6.2 Bid Response Example

The following bid responses are not fully formed and may include optional fields. Please defer to the spec.

{
  "bidid": "8297257243807848103",
  "cur": "USD",
  "id": "f215fcc8-c94c-4564-829c-9a0f988ac5ca",
  "seatbid": [
    {
      "bid": [
        {
          "adm": "{\"type\":\"ID\",\"bid_id\":\"4286570256979209201\",\"placement_id\":\"506317839546454_509738262537745\",\"resolved_placement_id\":\"506317839546454_509738262537745'\",\"sdk_version\":\"4.26.0\",\"device_id\":\"E621E1F8-C36C-495A-93FC-0C247A3E6E5F\",\"template\":4,\"payload\":\"null\"}",
          "id": "4286570256979209201",
          "impid": "banner_test_bid_req_imp_id",
          "nurl": "https://www.Advancedbidder.com/network/nurl/?partner=256699801203835&app=256699801203835&placement=326140227593125&auction=banner_test_bid_req_id&impression=banner_test_bid_req_imp_id&request=8297257243807848103&bid=4286570256979209201&ortb_loss_code=0",
          "price": 0.854516079549
        }
      ]
    }
  ]
}

7. For Server-Side Partners: MoPub SDK Functionality

7.1.1 Native Browser Clicks

Partners may choose to use the native browser click functionality supported by the MoPub SDK, whereby the click URL is opened in the device’s native browser instead of the in-app webview.

You can target this functionality via the imp.ext.brsrclk field on the request (note that this has been moved and changed from imp.banner.ext.nativebrowserclick because it is supported for both video and native). 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 opens the URL in the native OS browser):

mopubnativebrowser://navigate?url=

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

For more information and examples, refer to our article about deep linking.

Beginning with MoPub’s SDK version 3.9, we standardized an improved approach to submitting deep links that ensures a better end user experience and improved buy-side tracking. To leverage deep link plus:

  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

Sample 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**_

7.2 OpenRTB Native Specification v1.0

Our specification includes support for the OpenRTB Dynamic Native Ads API Specification v.1.0.

Important notes:

  • native.request is a String. Note that there is always a leading native object inside the request object to denote a native creative request type.

  • Bidders have two options for returning ad markup:

    • Preferred method: As a JSON object in the ext.admnative field (this is similar to MoPub’s original method of native ad bidding).

    • As a serialized string in the adm field (as noted by the OpenRTB 2.3 spec).

  • MoPub requires 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.

  • Main image and icon image height and width are required in the bid response image object.

  • Bidders can map the data fields to the following asset object ids:

    • 1 = title
    • 2 = main image
    • 3 = icon
    • 4 = text
    • 5 = ctatext
    • 7 = VAST

7.3 SSL

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

7.4 VAST Support

All VAST videos auto-play on iOS and Android when video is enabled. We support linear videos only.

7.4.1 Bid Request

To verify that an ad impression can accept a video ad, a bidder must check that 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 the OpenRTB 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.

7.4.2 Bid Response

VAST videos and opt-in rewarded video bid responses should be identical and follow the requirements below. Refer to 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 OpenRTB 2.3 spec
    • For auto-play video ads, its value is ‘6’

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-paragraph license (c) 2014 OpenRTB Project, All Rights Reserved.

Last updated July 11, 2020

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.)