MoPub OpenRTB 2.5 Integration Guide (BETA)

• 1. Overview
• 2. Important Integration Notes
• 3. Bid Request Variables & Definitions
• 4. Bid Response Variables & Definitions
• 5. Enumerated Lists Specification
• 6. Bid Request / Response Samples (2.5 Examples Coming Soon)
• 8. Changelog

Important: Please review the changelog periodically for updates!

1. Overview

Summary

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

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

Basic Auction on the MoPub Exchange

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

See section 2.4 for more information on nurls and impression tracking

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

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

2. Important Integration Notes

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

2.1 Key Changes from RTB 2.3

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

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

RTB Request

• bidrequest.ext.pchain [Moved] bidrequest.source.pchain
• bidrequest.imp.ext.metric [Moved] bidrequest.metric
• bidrequest.imp.banner.ext.format [Moved] bidrequest.imp.banner.format
• bidrequest.imp.video.ext.skip [Moved] bidrequest.imp.video.skip
• bidrequest.imp.video.ext.videotype [Moved] bidrequest.imp.ext.reward
• bidrequest.bapp [New]
• bidrequest.bseat [New]
• bidrequest.wseat [New]
• bidrequest.imp.exp [New]
• bidrequest.imp.video.protocols [New]
• bidrequest.imp.video.placement [New]
• bidrequest.imp.video.skipmin [New]
• bidrequest.imp.video.skipafter [New]
• bidrequest.imp.video.playbackmethod [New]
• bidrequest.imp.video.pos [New]
• bidrequest.metric.type [New]
• bidrequest.metric.vendor [New]
• bidrequest.imp.banner.format.h [New]
• bidrequest.imp.banner.format.w [New]
• bidrequest.site [Removed]
• bidrequest.ext.pchain [Removed]
• bidrequest.imp.ext.metric [Removed]
• bidrequest.imp.ext.brsclk [Removed]
• bidrequest.imp.ext.dlp [Removed]
• bidrequest.imp.ext.metric.type [Removed]
• bidrequest.imp.ext.metric.vendor [Removed]
• bidrequest.imp.banner.ext.format [Removed]
• bidrequest.device.ext [Removed]
• bidrequest.user.data [Removed]
• bidrequest.user.data.id [Removed]
• bidrequest.imp.banner.ext.format.w [Removed]
• bidrequest.imp.banner.ext.format.h [Removed]
• bidrequest.imp.video.ext.skip [Removed]
• bidrequest.imp.video.ext.videotype [Removed]
• bidrequest.device.devicetype [Removed]
• bidrequest.device.dpidsha1 [Removed]
• bidrequest.device.dpidmd5 [Removed]
• bidrequest.user.data.name [Removed]
• bidrequest.user.data.segment [Removed]
• bidrequest.segment.id [Removed]

RTB Response

• bidresponse.seatbid.bid.burl [New]
• bidresponse.seatbid.bid.lurl [New]
• ${AUCTION_MBR} macro [New]
• bidresponse.seatbid.bid.iurl [Removed]
• bidresponse.seatbid.bid.ext.data [Removed]
• bidresponse.seatbid.bid.ext.crtype [Removed]
• bidresponse.seatbid.bid.ext.duration [Removed]

2.2 burl, nurl, and impression tracking updates

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

1. bidresponse.seatbid.bid.burl - this standard OpenRTB field is one of two options that allows a bidder to submit a single impression tracker that will be sent on the impression / charge event for the ad.
2. bidresponse.seatbid.bid.ext.imptrackers[] - this existing extension field is one of two options that allows a bidder to submit 1 or more impression trackers that will be sent on the impression / charge event for the ad.

Leveraging either field above will ensure bidders (and 3rd parties) minimize discrepancies with MoPub’s invoices. * The logic for sending trackers in these two fields is identical. * This does not apply for native. Bidders are required to use the native.imptrackers array to submit impression trackers instead.

1. bidresponse.seatbid.bid.nurl - this is an optional variable to notify a bidder when they won the auction. This does not guarantee that an impression is served, nor does MoPub charge when this tracker is sent
   • The nurl is fired server side.
2. bidresponse.seatbid.bid.ext.nurls[] - this optional extension field allows a bidder to submit multiple nurl trackers to optionally notify 3rd parties of the win.
   • Note that if both nurl and the array are provided, we will only use what is present in the array field.

2.3 multiple bid responses and multiple seat bids

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

bidresponse.seatbid.seat technical requirements:

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

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

2.4 OpenRTB Native Specification v1.2

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

1. Bidders have two options for returning ad markup:
   1. (preferred method) As a JSON object in the bid.adm_native field
   2. as a serialized string in the bid.adm field (as noted by OpenRTB)
2. MoPub is adding support for the ‘Sponsored By’ data asset type, the eventtrackers, clicktrackers, and plcmttype fields.
3. MoPub is requiring a minimum width and height of 80x80px for the icon asset. A value of 80 is passed in the bid request assets.img.wmin and assets.img.hmin.
4. Main image and icon image height and width are required in the bid response image object.
5. Current bidders in MoPub’s native ads can map the data fields to the following asset object ids:
   • 1 = title
   • 2 = main image
   • 3 = icon
   • 4 = text
   • 5 = ctatext
   • 6 = starrating
   • 7 = VAST
6. Native video is currently in beta. Please contact your your account team or mopubDSPsuccess@twitter.com if you would like to participate.

3. Bid Request Variables & Definitions

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

Additional notes:

• Below section naming will follow OpenRTB for simplicity
• All fields will be populated in the request if available. We will never pass null values or empty strings. If noted as “always passed”, that parameter will always be present, otherwise it may not be present in all requests. For example, if the request doesn’t contain an SDK version, we will omit the field ver from the request.
• Types and descriptions from OpenRTB aren’t included below
• Any objects and attributes from OpenRTB not supported by MoPub will be noted by a strikethrough

3.2.1 Object: bidrequest

3.2.2 Object: source

3.2.3 Object: regs

3.2.3.1 Object: regs.ext

3.2.4 Object: imp

3.2.4.1 Object: imp.ext

3.2.5 Object: metric

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

3.2.6 Object: banner

3.2.7 Object: video

3.2.8 Object: native

3.2.9 Object: format

3.2.10 Object: pmp

3.2.11 Object: deal

3.2.12 Object: app

3.2.13 Object: publisher

3.2.14 Object: device

3.2.15 Object: geo

3.2.16 Object: user

3.2.16.1 Object: user.ext

3.2.17 Object: imp.native (4.1 in native subspec)

3.2.17.1 Object: native.assets (4.2 in native subspec)

3.2.17.2 Title Object (4.3 in native subspec)

3.2.17.3 Image Object (4.4 in native subspec)

3.2.17.4 Video Object (4.5 in native subspec)

3.2.17.5 Data Object (4.6 in native subspec)

3.2.17.6 Event Trackers Object (4.7 in native subspec)

4. Bid Response Variables & Definitions

Additional notes:

• Below section naming will follow OpenRTB for simplicity
• The types are unchanged from OpenRTB specification
• Attribute requirements reflect MoPub requirements and may differ from OpenRTB
• Any objects and attributes not supported by MoPub will be noted by a strikethrough

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

4.2.5.1 Object: native (5.1 in native subspec)

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

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

4.2.5.3 Title Object (5.3 in native subspec)

4.2.5.4 Image Object (5.4 in native subspec)

4.2.5.5 Data Object (5.5 in native subspec)

4.2.5.6 Video Object (5.6 in native subspec)

4.2.5.7 Link Object (5.7 in native subspec)

4.2.5.8 Event Tracker Object (5.8 in native subspec)

4.2.6 Object: bid.privacy

4.3 Substitution Macros

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}

4.4 Sending nbr when not bidding

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

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

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

5. Enumerated Lists Specification

5.1 Lists: OpenRTB 2.3 Spec

Please refer to the Enumerated Lists section in the OpenRTB 2.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.

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.

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.

5.13 API Frameworks

The following table is a list of API frameworks supported by the publisher.

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.

5.15 Protocols

The following table lists the options for the various bid response protocols that could be supported by an exchange.

5.16 Video Placement Types

The following table lists the various types of video placements derived largely from the IAB Digital Video Guidelines.

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.

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.

5.19 Connection Type

The following table lists the various options for the type of device connectivity.

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.

5.2 Lists: Native Subspec

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

5.20 Placement Type IDs (7.3 in native subspec)

The FORMAT of the ad you are purchasing, separate from the surrounding context

5.21 Data Asset Types (7.4 in native subspec)

5.22 Image Asset Types (7.5 in native subspec)

5.23 Event Types Table (7.6 in native subspec)

5.24 Event Tracking Methods Table (7.7 in native subspec)

6. Bid Request / Response Samples (2.5 Examples Coming Soon)

6.1 Bid Request Examples (2.5 Examples Coming Soon)

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

6.1.2 Video Bid Request

6.1.3 Private Marketplace Bid Request

6.1.4 Native Bid Request

6.1.5 Native Video Request

6.1.6 Rewarded Video Request

6.1.7 Inventory Package Request

6.1.8 Viewability Request

6.1.9 GDPR Consent Request

6.1.9.1 GDPR Non Consent Request

6.1.10 Format Array Bid Request

6.2 Bid Response Examples (2.5 Examples Coming Soon)

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

6.2.1 Banner Bid Response

6.2.2 MRAID Bid Response

6.2.3 Video Bid Response

6.2.4 MRAID Video Bid Response

6.2.5 Private Marketplace Bid Response

6.2.6 Native Bid Response (adm)

6.2.7 Native Bid Response (ext.admnative)

6.2.8 Native Video Bid Response (adm)

6.2.9 Native Video Bid Response (ext.admnative)

6.2.10 Multi-Bid Response

6.2.11 Inventory Package Bid Response

6.2.12 Viewability Bid Response

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