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

1. Overview

2. Instructions for Using This Guide

• 2.1 MoPub Marketplace Spec vs. Advanced Bidding Spec
  • 2.1.1 Optional Bid Request Values for Advanced Bidders
  • 2.1.2 Bid Response Values Optional for Advanced Bidders
  • 2.1.3 Additional Key Differences
• 2.2 SDK Deployment and Adapter Instructions
  • 2.2.1 Changes to Mediation Adapters
  • 2.2.2 After the Auction Process

3. Bid Request Variables and Definitions

• 3.2.1 Object: bidrequest
• 3.2.2 Object: source
  • 3.2.2.1 Object: source.ext
    • 3.2.2.1.1 Object: source.ext.schain
      • 3.2.2.1.1.1 Object: source.ext.schain.nodes
• 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.4.2 Object: imp.ext.networkids
• 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.18.1 Object: device.ext
• 3.2.19 Object: geo
• 3.2.20 Object: user
  • 3.2.20.1 Object: user.ext
• 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.2.6 Object: bid.privacy

• 4.3 Substitution Macros

5. Enumerated Lists Specification

• 5.1 Lists: OpenRTB 2.5 Spec
  • 5.10 Banner Ad Types
  • 5.11 Creative Attributes
  • 5.12 Ad Position
  • 5.13 API Frameworks
  • 5.14 Video Linearity
  • 5.15 Protocols
  • 5.16 Video Placement Types
  • 5.17 Video Start Delay
  • 5.18 Companion Types
  • 5.19 Connection Type
  • 5.20 Loss Reason Codes
• 5.2 Lists: Native Subspec
  • 5.20 Placement Type IDs (7.3 in OpenRTB native subspec)
  • 5.21 Data Asset Types (7.4 in OpenRTB native subspec)
  • 5.22 Image Asset Types (7.5 in OpenRTB native subspec)
  • 5.23 Event Types Table (7.6 in OpenRTB native subspec)
  • 5.24 Event Tracking Methods Table (7.7 in OpenRTB native subspec)

6. Bid Request and Response Samples

• 6.1 Bid Request Examples
  • 6.1.1 Banner Bid Request
  • 6.1.2 Native Bid Request
  • 6.1.3 Rewarded Ad Bid Request
  • 6.1.4 Session Depth Bid Request
• 6.2 Bid Response Examples
  • 6.2.1 Banner Bid Response
  • 6.2.2 Native Bid Response

7. Changelog

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 the imp 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 the userobject, and may contain any custom data a network wishes to receive in the bid request. The ‘buyeruid’ must not be larger than 1kb in size.

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

3.2.1 Object: bidrequest

3.2.2 Object: source

3.2.2.1 Object: source.ext

3.2.2.1.1 Object: source.ext.schain

3.2.2.1.1.1 Object: source.ext.schain.nodes

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.4.1 Object: imp.ext.skadn

3.2.4.2 Object: imp.ext.networkids

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.

3.2.6 Object: banner

3.2.7 Object: video

Advanced Bidders may ignore these values as they do not apply to creative rendered by third party SDKs.

3.2.9 Object: native

3.2.10 Object: format

3.2.11 Object: pmp

Private Marketplace deals are not available to Advanced Bidders. Therefore, Advanced Bidders should ignore these values.

3.2.12 Object: deals

Private Marketplace deals are not available to Advanced Bidders. Therefore, Advanced Bidders should ignore these values.

3.2.14 Object: app

3.2.15 Object: publisher

3.2.18 Object: device

3.2.18.1 Object: device.ext

3.2.19 Object: geo

3.2.20 Object: user

3.2.20.1 Object: user.ext

3.2.23 Object: imp.native.request (4.1 in OpenRTB native subspec)

Note this is a JSON-encoded string.

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

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.

4.2.1 Object: bidresponse

4.2.2 Object: seatbid

4.2.3 Object: bid

4.2.4 Object: bid.ext

4.2.4.1 Object: bid.ext.skadn

4.2.4.1.1 Object: bid.ext.skadn.fidelities

4.2.5 Native Ad Creative JSON

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)

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

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

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.

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.

† 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.21 Device Type

The following table lists the type of device from which the impression originated.

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:

5.21 Data Asset Types (7.4 in OpenRTB native subspec)

5.22 Image Asset Types (7.5 in OpenRTB native subspec)

5.23 Event Types Table (7.6 in OpenRTB native subspec)

5.24 Event Tracking Methods Table (7.7 in OpenRTB native subspec)

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 Ad 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",
         "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":{
	    "api":[
               3,
               5,
               7
            ],
            "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,
	    "companionad":[
               {
                  "w":320,
                  "h":480,
                  "battr":[
                     3,
                     8,
                     9,
                     10,
                     14,
                     17
                  ],
                  "id":"2",
                  "vcm":1,
                  "api":[
                     3,
                     5,
                     6,
                     7
                  ],
                  "format":[
                     {
                        "h":480,
                        "w":320
                     },
                     {
                        "h":568,
                        "w":320
                     },
                     {
                        "h":600,
                        "w":300
                     },
                     {
                        "h":640,
                        "w":360
                     }
                  ],
                  "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.1.4 Session Depth 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,
	 "metric":[
            {
               "type":"session_depth",
               "vendor":"EXCHANGE",
               "value":0.0
            },
            {
               "type":"session_depth_banner",
               "vendor":"EXCHANGE",
               "value":0.0
            },
            {
               "type":"session_depth_full",
               "vendor":"EXCHANGE",
               "value":0.0
            },
            {
               "type":"session_depth_native",
               "vendor":"EXCHANGE",
               "value":0.0
            },
            {
               "type":"session_depth_rewarded",
               "vendor":"EXCHANGE",
               "value":0.0
            },
            {
               "type":"session_depth_medium_rectangle",
               "vendor":"EXCHANGE",
               "value":0.0
            }
         ],
         "ext":{
            "networkids":{
               "appid":"network_app_id",
               "placementid":"network_placement_id"
            },
            "reward":0,
	    "skadn":{
               "version":"2.0",
               "sourceapp":"6138131",
               "skadnetids":[
                  "12339xyzzd.skadnetwork",
                  "321xyzsla.skadnetwork"
               ]
            }
         },
         "id":"1",
         "instl":0,
         "secure":1,
         "tagid":"b12ae796186931bfe7aa39471487b980"
      }
   ],
   "regs":{
      "ext":{
         "gdpr":0
      }
   },
   "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,
	        "ext":{
                  "skadn":{
                     "signature":"TESTCGEKIDKZ6vAtveU3WoWnTESTZQAteuSpYkwIYbyj6l9rI3+A53V9HA/Vl+YSwTESTd4Fo",
                     "network":"12339xyzzd.skadnetwork",
                     "version":"2.0",
                     "nonce":"ababab123-1234-5678-0123-4abctest78ff",
                     "campaign":"2",
                     "timestamp":1619640173056,
                     "itunesitem":"123456789",
                     "sourceapp":"123456789"
                  }
               }
            }
         ]
      }
   ]
}

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.