Open RTB 2.4 Technical Reference for Chocolate Marketplace







Open RTB 2.4 Technical Reference for Chocolate Marketplace



Table of Content



About This Document

This document lists the detailed specifications Chocolate Marketplace will use going forward.

Target Audience

  • Bidders (Programmatic Demand Partners)
  • AdOps Team
  • Developers

Using This Document

In order to understand the process as whole, it is recommended to go through the manual from start to end. If, you wish to jump to a specific topic or refer a part, use the Table of Content and jump to the topic of interest.

Terminology


  • Chocolate Marketplace - A service that facilitates an auction among bidders for each of impression opportunity
  • Bidder: An entity that takes part in bidding process in real-time to win auction and then provides a campaign detail in an intent to show the ad on publisher’s site or app
  • Publisher: An entity that provides an impression opportunity available on the ad container on its website or app
  • Site/App: Ad supported content including web and mobile applications


Overview – Chocolate Marketplace and Open RTB


What is Open RTB?

Real-time bidding (aka RTB) is a way in which ad inventory is purchased and then sold on in an automated bidding process. The auction is a smart and fair way to ensure maximum usage of web/app space is done while providing a highly beneficial deal for both publisher and advertiser.


In RTB, advertising buyers place their bid on an impression and, if they win, the buyer’s ad campaign detail is sent to the mobile device.


Where Chocolate Marketplace fits?

Chocolate Marketplace is a RTB Exchange that supports the online and automated bidding where the ad campaign detail from the winning bidder is sent to the device. On a larger note, Chocolate Marketplace can be termed as subset of Open RTB standards as it inherits processes and protocols from Open RTB


Figure 1. Chocolate - Chocolate Marketplace

Architecture of Open RTB


Figure 2. RTB Structure

  1. Chocolate Marketplace will receive an ad request from a device and it will forward that request to bidders. Bidders will take part in auction.
  2. Chocolate Marketplace will broadcast a HTTP POST request to all partner bidders and will expect response in 300ms (tmax).
  3. Chocolate Marketplace carries out the auction for all valid bids.
  4. Chocolate Marketplace sends the wining bid's HTML and nURL to the client.
  5. The publisher device sends the notification to the winning bidder after the markup has been rendered.
  6. Type of an object (mandatory, recommended, and optional) may be altered at later stage. General idea is that those mandatory will not be disturbed while an optional or recommended might be upgraded to mandatory status.
  7. Default currency has been set as USD.
  8. Chocolate Marketplace will support both the First Price and Second Price Auctions. For a VAST / VPAID tag based integration, Chocolate marketplace would hold a first price auction whereas for RTB based integrations, Chocolate marketplace would conduct a second price auction.
  9. When no bid is received as response, HTTP 204 will be returned.


Bidder Integration Checklist

In order to integrate your system as a bidder, you will need to provide following information:

Connection Identifier

Unique name of the connection.


Bid Type - It has seven variants to choose from:

    1. Open RTB 2.1 – bid requests and bid responses will be communicated as per Open RTB 2.1
    2. Open RTB 2.2 - bid requests and bid responses will be communicated as per Open RTB 2.2
    3. Open RTB 2.4 - bid requests and bid responses will be communicated as per Open RTB 2.4
    4. VAST Fixed Price - These are fixed price bidders based on VAST server-to-server integration. Chocolate sends the request after populating the VAST Tag macros. The demand partner returns a campaign based on the targeting criteria. The bid price for participating in the auction is constant based on the pricing agreed beforehand.
    5. VAST with Chocolate Extension Price - These are bidders based on VAST server-to-server integration. Chocolate sends the request after populating the VAST Tag macros. The demand partner returns a campaign based on the targeting criteria. The demand side system can vary the bid price using the Chocolate VAST extension for price. (Refer to this article.)
    6. VPAID Fixed Price - These are fixed price bidders based on VPAID server-to-server integration. Chocolate sends the request after populating the VPAID Tag macros. The demand partner returns a campaign based on the targeting criteria. The bid price for participating in the auction is constant based on the pricing agreed beforehand.
    7. VPAID with Chocolate Extension Price - These are bidders based on VPAID server-to-server integration. Chocolate sends the request after populating the VPAID Tag macros. The demand partner returns a campaign based on the targeting criteria. The demand side system can vary the bid price using the Chocolate VAST extension for price. 

Ad Format

Please note that Chocolate Marketplace only supports video ad and MRAID banner formats.


Auction Type – there could be two types of prices:


  • First Price Auction- The winner will have to pay the amount bid by the highest bidder.
  • Second Price Auction - The winner will pay the amount the second highest bidder had bid added with $0.01. For example if the highest bid was $10 and second highest bid was $8, then the winner will be $8+$0.01 = $8.01. 
    Note: $0.01 is a fixed addition amount. In case of no bid or the second highest bid being below the floor price, the floor price would be considered as the second highest bid.


Bid Request URL (Mandatory) - URL where the Bid Request is sent to from Chocolate.


Win Notice URL - URL where winner will be informed. If the bidder wins the impression, the client calls this notice URL (a) to inform the bidder of the win and (b) to convey certain information using substitution macros. This URL will be hit by Chocolate when bidder wins.


Frequency Capping / device (optional)- The maximum number of times bidder wants a particualar device id to render it's ad. This feature is only applicable for VAST inventory.


Supported Request Type: (mandatory) - The type of publisher ad requests that are supported by the bidder (VAST, VPAID, MRAID, JS). Only the type of ad requests selected by the bidder would be sent as a bid request.


Supported Bid Request Creative:(optional) - The type of ad response that can be returned by the bidder (VPAID, MRAID 1.0, MRAID 2.0). By default, a bidder can return VAST creatives.


Maximum Bid Request Per Second (QPS) (Mandatory) – A ceiling value for the number of bids per second that can be permitted. This value can be left as unlimited as well.


Device Type:(mandatory) - The type of device for which this connection can recieve ad requests for. Atleast one of the options (Mobile, Tablet, Desktop) has to be selected.


Request Type – A target platform. It can be either Site or an App, or both.


Device OS – Type of device os (applicable only for mobile / tablet) of the user, the bidder wishes to target.


Target Countries (optional)- One or more countries to be targeted for this ad.


Additional Filters:(optional) - following additional filters can be chosen:

  • Ad Size (Desktop)
  • Ad Size (For mobile / tablet)
  • Skippability
  • Sound (on/off)
  • Viewability Measurable
  • Autoplay
  • Incentivized
  • Clickable
  • Integration Type
  • .VDO Formats
  • Has domain / bundle ID
  • Ad unit (only for desktop inventory)
  • Instream
  • Has IFA
  • Has GPS based lat/long


Integration Checklist


  • In the context of this technical documentation,  Chocolate is a supply source, and these are the objects/parameters supported in the bid request


  • Supported Scenarios:
Mobile In-Browser:Mobile In-App:DesktopOther:
Banners: NoBanners: Yes (MRAID)Banners: NoNo
Video: YesVideo: YesVideo: Yes


  • Supported Objects/Parameters:


Object Name

Supported?

Recommended
parameters that
are not supported

Optional parameters
that are supported

Bid Request Object

Y



Impression Object

Y



Banner Object

Y



Video Object

Y



Site Object

Y



App Object

Y



Content Object




Native ObjectY

Device Object

Y



User Object

Y



Publisher Object

Y



Producer Object




Geo Object

Y



Data Object




Segment Object


PMPY

Deal

Y




Changes from Open RTB 2.2 to 2.4


  • Introduction of encryptions by supporting both HTTP and HTTPS
  • Increased location support allowing buyers to know which IP source was used to derive a given geo-location and when the latitude/longitude was last fetched using the device location service
  • Video skippability support for in-stream advertisements
  • In the user object, the buyer ID attribute has been corrected to “buyeruid.”
  • The ${AUCTION_BID_ID} macro has been corrected to be substituted with the “BidResponse.bidid” attribute.
  • Native ad placements must be included directly into the impression object in order to be passed through the bidstream.
  • Allows for the inclusion of metadata (title, urls, data, img files) in the native request. The buy side now has the ability to describe the unit that’s being bid on and the supply side is able to define which fields are available and required in order to assemble the native ad.


Bid Request


Please note

All fields will be populated in the request if available. There will not be a provision of passing the null value

Overview

The supply source initiates a bid request and then the RTB transactions are started. The bid request essentially has a bid request object, at least one impression object, and other objects.

Object list

Objects are listed in the table below:

Please note

The following colors denote types of objects:

Red: Required fields from as per IAB Open RTB Spec

Orange: Recommended fields as per IAB Open RTB Spec

Blue: Optional fields as per IAB Open RTB Spec

Object Name     

Type

Description

Bid request

Required

Top level object

Impression object

Required

At least one impression object is required in a bid request object.

Site object

Recommended for websites

Either a site or app object may be included – not both. Neither is required.

Banner objectRecommended for bannerA banner object may be included in case the ad is shown in banner.

Apps object

Recommended for native apps

Either a site or app object may be included – not both. Neither is required.

Device object

Recommended

This object describes the device the ad impression will be delivered to (e.g., mobile phone, computer, set top box, etc.) and its capabilities (e.g., flash support).


Publisher objectRecommendedEntity that controls the content of and distributes the site or app.

User object

Recommended

This object describes the user, and may include unique identifiers for the user.


PMP objectOptionalCollection of private marketplace (PMP) deals applicable to this impression.
Deal objectOptionalDeal terms pertaining to this impression between a seller and buyer.

Geo object

Optional

Depending on the parent object, this object describes the current geographic location of the device (e.g., based on IP address or GPS), or it may describe the home geo of the user (e.g., based on registration data).


Impression objectRequiredDetails of a Video object

"Bid Request" Object


Object NameTypeDefault ValueDescription
idRequired
Unique ID of the bid request, provided by the exchange

imp

Required
Array of Imp objects representing the impressions offered. At least 1 Imp object is required.
siteRequired for sites
Details via a Site object about the publisher’s website. Only applicable and recommended for websites.
appRequired for apps
Details via an App object about the publisher’s app (i.e., non-browser ap
deviceRecommended
Details via a Device object about the user’s device to which the impression will be delivered.
userRecommended
Details via a User object about the human user of the device; the advertising audience.
atRequired
Auction type, where 1 = First Price, 2 = Second Price Plus.  
tmaxRecommended
Maximum time in milliseconds to submit a bid to avoid timeout
allimpsOptional0Flag 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. 
bcatOptional
Blocked advertiser categories using the IAB content categories.
badvOptional
Block list of advertisers by their domains
regsOptional
A Regs object that specifies any industry, legal, or governmental regulations in force for this request.



"id" Object

This field denotes the unique ID of the bid request, provided by the exchange. This is mandatory.

"imp" Object

The “imp” field tells about the impression being auctioned. A single bid request may include multiple numbers of “imp” fields. Each “imp” has a required ID so that bids can reference them individually. An exchange can also do private auctions as part of their policy.


Field

Scope

Default

Description

id

Required

-

Id is a unique identifier for this impression within the context of the bid request.

Instl

Optional

0

Signifies whether the ad is an interstitial or full screen.

banner

Needed for banner impressions

-

Sets a reference to a banner object. Either a banner or video object.

displaymanagerOptional-Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.
displaymanagerverOptional-Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps.
secureOptional0Flag 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.
expOptional-Advisory as to the number of seconds that may elapse between the auction and the actual impression.

video

Needed for video impressions

-

Sets a reference to a video object. Either a banner or video object.

Bidfloor

Optional

0

Bid floor for this impression (in CPM of bidfloorcur). This is a float value

Bidfloorcur

Optional

USD

If multiple currencies supported per bid request, then currency should be specified here using ISO-4217 alphabetic codes.

"imp.ext" Object


FieldScopeDefaultDescription
viewabilitymeasurabilityOptional

1 - Viewability Measurable

2 - Viewability Non-Measurable



"video" Object

The “video” object is included directly in the impression object if the impression offered for auction is an in-stream video ad opportunity.


Field

Scope

Default

Description

linearity

Optional


Indicates whether the ad impression is linear or non-linear.

1 - Linear/In-stream

2 - Non-Linear/Overlay

This field is optional. The following should be the interpretation of the bidder based upon the presence or absence of the field in the bid request:

• If no value is set, any ad (linear or not) can be present in the response.

• If a value is set, only ads of the corresponding type can be present in the response.

startdelayOptional

Indicates the start delay in seconds for preroll, midroll, postroll ad placement.

Generic values if not present:

0 - preroll

-1 - Generic mid-roll

-2 Generic post-roll

mimes

Required


Content MIME types supported.

Popular MIME types include, but are not limited to, “video/x-ms- wmv” for Windows Media and "application/javascript" for VPAID

minduration

Required

15

Minimum video ad duration in seconds

maxduration

Required

30

Maximum video ad duration in seconds

protocol

Required

5

Video bid response protocols.

wRecommended
Width of the player in pixels.
hRecommended
Height of the player in pixels.

sequence

Recommended

1

If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creative.

playbackmethodOptional

List of allowed playback methods. If blank, assume that all are allowed.

1 - Auto-play sound on

2 - Auto-play sound off

3 - Click-to-play

4 - Mouse-over (Not applicable for mobile)

apiRequired for api supported inventory
List of supported API frameworks for this impression
posRecommended-Ad position on screen
minbitrateOptional200Minimum bit rate in Kbps.
maxbitrateOptional1500Maximum bit rate in Kbps


"video.ext" Object

FieldScopeDefaultDescription
skippabilityOptional

1 - Skippable

2 - Non-Skippable

incentivizedOptional

1 - Incentivized

2 - Non-Incentivized

clickabilityOptional

1 - Clickable

2 - Non-Clickable

instreamOptional

1 - In-Stream

2 - Non-In-Stream


"banner" Object

The “banner” object is included directly in the impression object if the impression offered for auction is a MRAID opportunity.

Field

Scope

Default

Description

battroptional6
Blocked creative attributes.
1 - Audio Ad
2 - Audio Ad (User Initiated)
3 - Expandable (Automatic)
4 - Expandable (User Initiated - Click)
5 - Expandable (User Initiated - Rollover)
6 - In-Banner Video Ad (Auto Play)
7 - In-Banner Video Ad (User Initiated)
8 - Pop (e.g., Over, Under, or upon Exit)
9 - Provocative or Suggestive Imagery
10 - Shaky, Flashing, Flickering, Extreme Animation, Smileys
11 - Surveys
12 - Text Only
13 - User Interactive (e.g.,Embedded Games)
14 - Windows Dialog or Alert Style
15 - Has audio on/off button
16 - Ad can be skipped (e.g., skip button on preroll video)
topframeoptional0
Specify if the banner is delivered in the top frame or in an iframe.
“0” - means it is not in the top frame,
“1”  - means that it is
wrecommended
Width of the impression in pixels.
hrecommended
Height of the impression in pixels
idrecommended
Unique identifier for this banner object.
apioptional
List of supported API frameworks for this banner.
1 - VPAID 1.0
2 - VPAID 2.0
3 - MRAID - 1
4 - ORMMA
5 - MRAID - 2

"site" Object

A "site" object is included if the supported ad is a part of a website.


Field

Scope

Default

Description

domain

Optional


Domain of the site, used for advertiser side blocking.

nameOptional
Site name

page

Recommended


URL of the page where the impression will be shown e.g. www.basketball-shoes.com/shoe-model-001.html

publisher

Optional


The publisher object itself and all of its parameters are optional, so default values are not provided. If an optional parameter is not specified, it should be considered unknown.

idRequired
Exchange-specific site ID.
catOptional
Array of IAB content categories of the site.
refOptional
Referrer URL that caused navigation to the current page.
contentOptional
Details about the Content within the site.

"app" Object

An “app” object is included if the ad content is part of a mobile application (as opposed to a mobile website). A bid request must not contain both an “app” object and a “site” object.


Field

Scope

Default

Description

domain

Optional


Domain of the application (e.g., “mygame.foo.com”).

publisher

Optional


See Publisher Object

id

Recommended


Application ID on the exchange.

nameOptional
App name
bundleOptional
A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name
catOptional
Array of IAB content categories of the app
publisherOptional
Details about the Publisher of the app

storeurl

Optional


For QAG 1.5 compliance, an app store URL for an installed app should be passed in the bid request.

contentOptional
Details about the Content within the app

"publisher" Object

Field

Scope

Default

Description

id

Recommended


Site ID on the exchange.

nameRecommended
Publisher name
catRecommended
Array of IAB content categories that describe the publisher

"device" Object

The “device” object provides details related to the device in question. Information includes platform, hardware, location, and carrier.

In general, the most essential fields are either the IP address or geo information.


Field

Scope

Default

Description

geo

Recommended


The geo object itself and all of its parameters are optional, so default values are not provided. If an optional parameter is not specified, it should be considered unknown.

dntRecommended
If “0”, then do not track Is set to false, if “1”, then do no track is set to true.
carrierOptional
Carrier or ISP derived from the IP address. Should be specified using Mobile Network Code (MNC).
http://en.wikipedia.org/wiki/Mobile_Network_Code
osvOptional
Device operating system version (e.g., “3.1.2”).
osOptional
Device operating system (e.g. "iOS").
ifaOptional
Native identifier for advertisers; an opaque ID assigned by the device or browser for use as an advertising identifier. (e.g. Apple's IDFA, Android's Google Advertising ID, etc)

ip

Recommended


IPv4 address closest to device.

jsOptional
“1” if the device supports JavaScript; else “0”.
languageOptional
Browser language; use alpha-2/ISO 639-1 codes.
modelOptional
Device model (e.g., “iPhone”).

ua

Recommended


Browser user agent string.

makeOptional
Device make (e.g. "Apple").
devicetypeOptional

Return the device type being used.

1 - Mobile/Tablet

2 - Personal Computer

3 - Connected TV

4 - Phone (New for Version 2.2.)

5 - Tablet (New for Version 2.2.)

6 - Connected Device (New for Version 2.2.)

7 - Set Top Box (New for Version 2.2.)

dpidmd5

Optional


The MD5 of the RAW_IFA, if the IFA is available.

dpidsha1Optional
The SHA1 of the RAW_IFA, if the IFA is available.

"geo" Object


Field

Scope

Default

Description

zipOptional
Zip/postal code

country

Recommended


Country using ISO-3166-1 Alpha-3.

city

Recommended


City using United Nations Code for Trade and Transport Locations

metroOptional
Pass the metrocode (see http://code.google.com/apis/adwords/docs/appendix/metrocodes.html).  Metro codes are similar to but not exactly the same as Nielsen DMAs.
latOptional

Latitude from -90 to 90. South is negative.

lonOptional
Longitude from -180 to 180. West is negative.
regionOptional
Region using ISO 3166-2.
typeRecommended

Indicate the source of the geo data (GPS, IP address, user provided). Type should be provided when lat/lon is provided.

1 - GPS/Location Services

2 - IP Address

3 - User provided (e.g. registration data)

"user" Object

The “user” object contains information known or derived about the human user of the device.


Field

Scope

Default

Description

Id

Recommended


Unique consumer ID of this user on the exchange.

genderOptional

M - Male

F - Female

O - Other

Null - Unknown


"PMP" Object

The “pmp” object contains a parent object for usage withi n the context of private marketplaces and the use of the RTB protocol to execute Direct Deals.

Field

Scope

Default

Description

private_auction

optional

 0

An integer flag indicating that this impression is a private auction eligible only to seats named in the Direct Deals object.
0 = all bids are accepted
1 - bids for this impression are restricted to the deals specified and the terms thereof
 deals optional
A collection of “deal” objects encapsulating a list of direct deals eligible for this impression. 

"Deals" Object

A “deal” object constitutes a deal struck a priori between a buyer and a seller and indicates that this impression is available under the terms of that deal


Field

Scope

Default

Description

id

required


A unique identifier for the direct deal
bidfloor optional0
Bid floor for this impression (in CPM of bidfloorcur)
bidfloor cur optionalUSDThe bid floor currency
wseatoptional
Array of buyer seats allowed to bid on this Direct Deal
atoptional

Auction type:

If “1”, then first price auction

If “2”, then second price auction

If “3”, the passed bidfloor indicates the apriori agreed upon deal price

"at" Object

The "at" object indicates the Auction Type. “1” denotes the first price auction while “2”denotes the second price auction.

"allimps" Object

Flag to indicate whether Exchange can verify that all impressions offered represent all of the impressions available in context. A true value should only be passed if the exchange is aware of all impressions in context for the publisher. “0” means the exchange cannot verify, and “1” means that all impressions represent all impressions available.

"tmax" Object

This field denotes the suggested maximum amount of time in milliseconds to submit a bid. The suggested value will be 250ms. Please note that Chocolate may close the auction before/after tmax to maximize yield.

Samples

Video - App


{
    "app": {
        "storeurl": "https://itunes.apple.com/us/app/kill-shot/id839703707?mt=8",
        "domain": "meetme.com",
        "cat": [
            "IAB24"
        ],
        "name": "MeetMe",
        "publisher": {
            "ext": {},
            "domain": "meetme.com",
            "id": "8688"
        },
        "id": "2cab41c994f8421fe7d2dbc5036c4bc8",
        "bundle": "com.myyearbook.m"
    },
    "cur": [
        "USD"
    ],
    "at": 2,
    "allimps": 0,
    "tmax": 350,
    "regs": {},
    "id": "80816352-3322-443b-a5a0-8ae6170110f5",
    "user": {
        "id": "6dbc05b4-c2e8-4f39-aecb-941541bf96f8"
    },
    "imp": [
        {
            "ext": {
                "viewabilitymeasurability": 2
            },
            "bidfloor": 5.33,
            "bidfloorcur": "USD",
            "id": "1",
            "video": {
                "boxingallowed": 1,
                "ext": {
                    "skippability": 1,
                    "incentivized": 2,
                    "clickability": 1,
                    "instream": 2
                },
                "sequence": 1,
                "protocol": 2,
                "maxduration": 30,
                "w": 320,
                "h": 480,
                "playbackmethod": [
                    2
                ],
                "protocols": [
                    2,
                    5
                ],
                "minduration": 15,
                "mimes": [
                    "video/mp4"
                ]
            },
            "instl": 1
        }
    ],
    "device": {
        "ext": {
            "ifa": "6dbc05b4-c2e8-4f39-aecb-941541bf96f8"
        },
        "os": "Android",
        "ifa": "6dbc05b4-c2e8-4f39-aecb-941541bf96f8",
        "ip": "74.138.197.73",
        "js": 1,
        "language": "en",
        "ua": "Mozilla/5.0 (Linux; Android 5.0.2; SM-G925R6 Build/LRX22G; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/43.0.2357.121 Mobile Safari/537.36",
        "devicetype": 4,
        "geo": {
            "zip": "40160",
            "country": "USA",
            "city": "Radcliff",
            "metro": "529",
            "lon": -85.96095,
            "region": "US-KY",
            "type": 1,
            "lat": 37.854744
        },
        "carrier": "Time Warner Cable",
        "dpidmd5": "788cf925013d23e68090b15e3b8a5089",
        "osv": "5.0",
        "model": "Android 5.0",
        "make": "Generic",
        "dpidsha1": "55cbc2c3436dfe07ae85f5bd263c187a1d141212"
    }
}


Video - Site


{
    "cur": [
        "USD"
    ],
    "site": {
        "ref": "http://adslevel.com/?q=902c05cdf404416680fe7e088aaca336",
        "domain": "justataste.com",
        "cat": [
            "IAB1"
        ],
        "name": "justataste.com",
        "publisher": {
            "ext": {},
            "domain": "adslevel.com",
            "id": "9148"
        },
        "id": "21447995ae6f8f3f786f08af274d2471",
        "page": "http://www.justataste.com"
    },
    "at": 2,
    "allimps": 0,
    "tmax": 350,
    "regs": {},
    "id": "6f3df944-8b05-4868-a8b2-5c2f2bdaef13",
    "user": {},
    "imp": [
        {
            "ext": {
                "viewabilitymeasurability": 2
            },
            "bidfloor": 4.67,
            "bidfloorcur": "USD",
            "id": "1",
            "video": {
                "boxingallowed": 1,
                "ext": {
                    "skippability": 1,
                    "incentivized": 2,
                    "clickability": 1,
                    "instream": 2
                },
                "sequence": 1,
                "protocol": 2,
                "maxduration": 30,
                "w": 492,
                "h": 517,
                "playbackmethod": [
                    2
                ],
                "protocols": [
                    2,
                    5
                ],
                "minduration": 15,
                "mimes": [
                    "video/mp4"
                ]
            },
            "instl": 1
        }
    ],
    "device": {
        "geo": {
            "zip": "EX17",
            "country": "GBR",
            "city": "Crediton",
            "metro": "0",
            "lon": -3.649994,
            "region": "GB-D4",
            "type": 2,
            "lat": 50.783295
        },
        "carrier": "BT",
        "osv": "8.3",
        "os": "iOS",
        "ip": "86.131.112.151",
        "js": 1,
        "model": "iPad",
        "ua": "Mozilla/5.0 (iPad; CPU OS 8_3 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12F69",
        "make": "Apple",
        "devicetype": 5
    }
}

Banner - App (MRAID)

{
    "app": {
        "domain": "com.fivemobile.thescore",
        "name": "theScore",
        "publisher": {
            "ext": {
                "direct": 2
            },
            "domain": "memeglobal.com",
            "id": "9991"
        },
        "id": "86482dc961387b50736a5795b954935a",
        "bundle": "com.fivemobile.thescore"
    },
    "ext": {
        "output": "xhtml",
        "ssp": "Chocolate"
    },
    "audienceSegment": 0,
    "cur": ["USD"],
    "at": 2,
    "allimps": 0,
    "tmax": 350,
    "regs": {},
    "id": "e085b875-d689-442e-a329-67e866d8efd5",
    "user": {
        "ext": {
            "AudienceData": []
        },
        "buyeruid": "d5ad8931-205e-44aa-9fcd-6e14b3947e57",
        "id": "b43cbe01-4cd6-4aeb-a04b-c63a95805b1f"
    },
    "imp": [{
        "ext": {
            "viewabilitymeasurability": 1
        },
        "displaymanager": "placeIQ",
        "displaymanagerver": "3.3",
        "bidfloor": 2,
        "banner": {
            "battr": [6],
            "topframe": 0,
            "w": 320,
            "h": 480,
            "id": "1",
            "api": [5, 3]
        },
        "bidfloorcur": "USD",
        "id": "1",
        "video": {
            "boxingallowed": 1,
            "ext": {
                "skippability": 1,
                "incentivized": 2,
                "clickability": 1,
                "instream": 2
            },
            "linearity": 1,
            "h": 480,
            "playbackmethod": [2],
            "minduration": 15,
            "mimes": ["video/mp4"],
            "sequence": 1,
            "protocol": 2,
            "maxduration": 30,
            "w": 320,
            "startdelay": 0,
            "protocols": [2, 5]
        },
        "instl": 1
    }],
    "device": {
        "ext": {
            "ifa": "30e67e18-1255-4359-aab7-9e258c8c2e51"
        },
        "os": "Android",
        "ifa": "30e67e18-1255-4359-aab7-9e258c8c2e51",
        "ip": "152.206.0.0",
        "js": 1,
        "language": "en",
        "ua": "Mozilla/5.0 (Linux; U; Android 4.0.3; ko-kr; LG-L160L Build/IML74K) AppleWebkit/534.30 (KHTML, like Gecko) Version/4.0 Mobile Safari/534.30",
        "devicetype": 1,
        "geo": {
            "country": "USA",
            "city": "San Francisco",
            "metro": "0",
            "lon": 77.31671,
            "region": "US-CA",
            "type": 3,
            "lat": 28.433304
        },
        "carrier": "T-Mobile, USA",
        "osv": "4.0.3",
        "model": "Samsung",
        "make": "Galaxy",
        "did": "3028030a-2fb5-47eb-a1c2-ec2c5e06c390"
    }
}

Bid Response

Object list

No-Bids on all impressions should be indicated as a HTTP 204 response. For no-bids on specific impressions, the bidder is expected to omit these from the bid response.


Object Name     

Type

Description

Id

Required

This must be the top level ID of the bid request that this is a response for.

bidid

Required

Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross reference.

seatbid

Required

An array of all seats for this bidder endpoint. There must be at least one seat present. Please note that Chocolate Marketplace will only use one seat here.

seatbid object

A bid response can contain multiple “seatbid” objects, each on behalf of a different bidder seat. Chocolate Marketplace will only allow one seat though.


Object Name     

Type

Description

seat

Optional

ID of the bidder seat on whose behalf this bid is made.

bid

Required

At least one bid object is required in a bid set object.

"bid" Object


Object Name     

Type

Description

iurl

Optional

Sample image URL (without cache busting) for content checking

adomain

Optional

Advertiser’s primary or top-level domain for advertiser checking. This can be a list of domains if there is a rotating creative. However, exchanges may mandate that only one landing domain is allowed.

crid

Required

Creative ID for reporting content issues or defects. This could also be used as a reference to a creative ID that is posted with an exchange.

impid

Required

ID of the impression object to which this bid applies.

Price

Required

Bid price in CPM. WARNING/Best Practice Note: Although this value is a float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.

adid

Optional

ID that references the ad to be served if the bid wins

nurl

Optional

Win notice URL. Please note that Chocolate marketplace does NOT support serving of ad markup via nurl.

adm

Optional

Actual ad markup. XHTML if responses to a banner object, or VAST XML if a response to a video object.

Id

Required

ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.

cid

Optional

Campaign ID or similar that appears within the ad markup

dealidOptional
A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a dealid in the request object it is required in the response object.


Sample

Video

{
    "id": "934f5cae-742e-4e01-ae90-4530ecbf2a9c",
    "bidderId": "abc-xyz",
    "seatbid": [
        {
            "bid": [
                {
                    "id": "934f5cae-742e-4e01-ae90-4530ecbf2a9c.1",
                    "impid": "1",
                    "price": 4.57,
                    "adid": "grlKP4xfdHYkFojNblR8",
                    "nurl":"http://adserver.com/winnotice?impid=102",
                    "adm": "ADMARKUP",
                    "adomain": [
                        "sap.com"
                    ],
                    "cid": "XnLhD5VOWMMicfhoMMkl",
                    "iurl":"http://adserver.com/pathtosampleimage",
                    "crid": "bbd3a9fb64ab7c5602eb1bc82961d7f5",
                    "ext": {}
                }
            ],
            "group": 0
        }
    ],
    "bidid": "934f5cae-742e-4e01-ae90-4530ecbf2a9c",
    "cur": "USD"
}



Substitution Macros

In order for the exchange to convey certain information to the winning bidder, a number of substitution macros can be inserted into the win notice URL definition. Prior to calling a win notice URL, the exchange will search the specified URL for any of the defined macros and replace them with the appropriate data. Note that the substitution is simple in the sense that wherever a legal macro is found, it will be replaced without regard for syntax correctness. Furthermore, if the source value is an optional parameter that was not specified, the macro will simply be removed (i.e., replaced with a zero-length string).

Auction Macros

  • ${AUCTION_ID} ID - of the bid request; from the top level “id” in the bid response
  • ${AUCTION_BID_ID} ID - of the bid; From the “bidid” attribute passed in the bid response
  • ${AUCTION_IMP_ID} ID - of the impression won; From the “impid” attribute in the bid response
  • ${AUCTION_SEAT_ID} ID - of the bidder’s seat for whom bid was made; from the “seat” attribute in the bid response
  • ${AUCTION_AD_ID} ID - of the ad markup; From the “adid” attribute in the bid response
  • ${AUCTION_PRICE} Settlement - price from the auction (i.e., what the DSP will be
  • charged for that impression)
  • ${AUCTION_CURRENCY} The - currency used in the bid (explicit or implied); For confirmation only.


Appendix

References

This documents stands aligned with the IAB. Refer to following resources for additional details

IAB Site

http://www.iab.net/guidelines/rtbproject

IAB Specification document

https://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-4-FINAL.pdf

General Questions

  • How do you identify InView inventory?
    • You can use the following parameters and values:
      • video w == 300
      • video h == 250
      • viewabilitymeasurability == 1

     
  • How do you respond to a deal id
    • The response should contain the deal id in the bid object. Without deal id bids will not be prioritized over open market

  • How do you send MRAID inventory?
    • We send both video and banner object in the request because we can deliver a video or banner, but not both


  • How do you respond to MRAID inventory?
    • Respond with XHTML in adm field if banner. Respond with VAST XML in adm field if video. Chocolate will process accordingly and deliver either javascript banner or VAST video to app




[1] Definition source - Wikipedia