Vungle OpenRTB 2.3 Integration Guide v.2.0.0

This is version 2.0.0 (May 2017) of the Vungle OpenRTB 2.3 Integration Guide. This article specifies the details for integrating with Vungle Exchange using OpenRTB 2.3. 

Contents

1. Request and Response

1.1 Entity

All entities in this section are a subset of the OpenRTB 2.3.1 spec; should there be missing fields or requirements, please default requirements to the spec itself.

1.2 Extension

In order to better serve an ad, Vungle Exchange provides information beyond the standard OpenRTB protocol. These extensions do not overlap with, but rather complement, the existing OpenRTB implementation. Extensions are sectioned into individual objects where it makes most sense.

All extension fields are encapsulated in a JSON object by a first-level extension field named 'vungle' under the OpenRTB 'ext' object. For simplicity, the documentation in subsequent sections of this document has omitted the 'vungle' field. The following is a sample of an OpenRTB JSON object containing Vungle extensions:

{
...
"ext": {
"vungle": {
// Individual extension fields at various rows below.
}
}
}

For example, a top-level bid request object may look something like this:

{
"id": "572c3535ab0af400011a721a",
"imp": [{<impression object>}],
"app": {<application object>},
"device": {<device object>},
"user": {<user object>},
"at": 2,
"tmax": 2000,
"cur": ["USD"],
"bcat": ["IAB7-3"],
"badv": ["google.com"],
"ext": {
"vungle": {
"badvid": ["2f00ca35ab0abe4df11da700c"]
}
}
}

1.3 Versioning

Over time, some fields become obsolete, so, to ensure maximum compatibility, Vungle Exchange will respect all "deprecated" fields specified in the most recent Vungle OpenRTB spec. All "deprecated" fields are scheduled for removal at the next specification update, at which point Vungle Exchange is relieved of the responsibility to maintain deprecated fields.

All removed fields will still remain in the specification with a "deleted" label to indicate that the field is no longer supported. We use the "deleted" label to enforce a specification semantic: Every field, once defined, remains unique in the scope for which it was defined for the lifetime of the spec. This means that if the 'id' field ever becomes deprecated and then removed in a particular spec, it will never be resurrected in a future revision with a different meaning.

1.3.1 Semantic Versioning

Specification versioning will also follow Semver 2.0.0 guidelines, namely:

  • A major version update can break backward compatibility; for example, a field that is "deprecated" in version X is "removed" in version X+1.
  • A minor version update should not break backward compatibility; examples include a field that is in use being marked as "deprecated"; or a required field being marked as as non-required and deprecated.
  • A patch version update must not break backward compatibility; for example, correcting a typo in specification description.

1. Request

2.1 Required and Optional Fields

Notes about the Required column in upcoming sections:

  • Yes: Downstream consumption of such a field can always expect a well-formatted, non-empty value based on the type specified.
  • No: Downstream consumption should not expect the existence of such field, or the validity of value. Consumer validation on the value is required, unnecessary for the type.
  • Default: All unmentioned fields in OpenRTB 2.3.1 default to not required.

2.2 Protocol Negotiation

Vungle Exchange supports communicating over HTTP/2 through protocol negotiation; otherwise, the default is HTTP/1.1.

2.3 Request Headers

Each bid request will have the following custom HTTP headers as specified by OpenRTB protocol:

X-OpenRTB-Version: 2.3

In addition to custom HTTP headers, Vungle Exchange also attaches the following standard headers:

Content-Type: application/json; charset=utf-8
Accept: application/json 

Finally, Vungle Exchange attaches a custom header to indicate the Vungle OpenRTB spec revision:

X-Vungle-OpenRTB-Version: 2

2.4 BidRequest Object

Field Type Required Description
id string yes 

Bid request ID generated by Vungle Exchange; for example, '570b0eb14e67c98f761a0ca0'.

imp

object array

yes  See the Impression object.
app object yes See the Application object.
device object yes See the Device object.
at integer yes

Type of auction; for example, '2' for second-price auction. Vungle Exchange only runs second-price auctions, so this value is always '2'.

tmax integer yes

Maximum time in milliseconds to submit a complete bid response; this value is always '250'.

cur string array no 

List of allowed currencies for the auction in ISO-4217-alpha; for example, ["USD", "CNY", "EUR"]. We currently only support "USD".

bcat string array no Refer to OpenRTB 2.3.1 section 5.1.
regs object no Refer to OpenRTB 2.3.1 section 3.2.16.
test integer no

Whether the auction is in test mode (1), or live mode (0);test auctions are not billable.

2.4.1 Impression Object

Field Type Required Description
id string yes  Impression ID generated by Vungle Exchange; for example, '3a06eb14e67c98f761add01'.
displaymanager string yes Supply-side display manager; Vungle uses this field to specify the SDK technology used, because we distinguish between SDK mobile platforms; for example, 'Vungle' for iOS, 'VungleDroid' for Android, and 'VungleWindows' for Windows, followed by the SDK version in the next field.
displaymanagerserver string yes Supply-side display manager version; Vungle uses this to specify the SDK version; for example, '3.3.1'.
bidfloor float yes Minimum bid price for a bid to be eligible; for example, '8.72'.
bidfloorcur string yes Currencies for the impression in ISO-4217-alpha; for example, 'USD'.
video object no  See the Video object.
tagid string no Placement reference ID corresponding to the given impression; for example,, 'placement_name_1af44fda'.
instl integer no Whether the impression represents full screen/interstitial (1), or not (0). Currently, Vungle Exchange supports full screen/interstitial (1) only.
secure integer no Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure and 1 = secure.
ext object no Vungle always requires secure (1) assets and markup.

2.4.2 Video Object

Field Type Required Description
mimes string array yes  Content MIME types supported. Vungle Exchange only supports ["video/mp4"].
h integer yes Height of the video.
w integer yes Width of the video.
minduration integer no  Minimum number of seconds for which the video must play.
maxduration integer no Maximum number of seconds for which the video may play.
delivery integer array no Supported list of video delivery methods: (progressive or streaming). Refer to OpenRTB 2.3.1 section 5.13.
minbitrate integer no Minimum bid rate in kbps. Vungle Exchange currently only supports 250.
maxbitrate integer no Maximum bid rate in kbps; for example, 500.
protocols integer array no Refer to OpenRTB 2.3.1 section 5.8; for example, [2, 3, 5, 6].
boxingallowed integer no Whether boxing the video is allowed (1) or not (0). The value for this is always '1'.
playbackmethod integer array no Refer to OpenRTB 2.3.1 section 5.9.
startdelay integer no Refer to OpenRTB 2.3.1 section 5.10. The value for this is always '0'.

2.4.3 Application Object

Field Type Required Description
id string yes  Exchange-specific ID. For Vungle, this is the app store ID; for example, '3709293'.
This ID may mean nothing to the DSP, but may be used by the DSP to compare and reconcile reporting disputes.
bundle string yes The unique market ID, this is a platform-specific application identifier intended to be unique to the app and independent of Vungle Exchange.
- On Android, this should be a bundle or package name (for example, 'com.supercell.hayday').
- On iOS, it is a numeric ID.
publisher object yes See the Publisher object.
name string no Application name; for example, 'Hay Day'.
storeurl string no App store URL; for example, 'https://itunes.apple.com/us/app/hay-day/id506627515?mt=8#'.
cat string array no Refer toRefer to OpenRTB 2.3.1 section 5.1.
privacypolicy integer no Whether the application has a privacy policy (1), or not (0). Vungle Exchange only supports '1' for this field.
paid integer no Whether the application is paid (1), or not (0).
keywords string no Comma-separated list of tags for the publisher application.
ext object no DESCRIPTION

2.4.4 Application Extension

Field Type Required Description
altid string no  A secondary Vungle Exchange-specific ID uniquely identifying the publisher application; for example, '3a06eb14e67c98f761add01'.
sdk object no See the SDK Extension object.
wtags string array no Publisher application tags whitelist.
btags string array no Publisher application tags blacklist.
bundleid string no Application bundle identifier or package name.
tags string array no Deprecated; use keywords.

2.4.5 SDK Extension

Field Type Required Description
name string yes  A string that identifies an SDK family of the SDK agent installed on the host application. For example, 'VungleDroid', 'Vungle', or 'VungleWindows'.
ver string yes String describing the version of the SDK agent installed on the host application.
plugin string no Name of the SDK plugin with which the SDK agent is built; for example, 'native', 'unity'.
pluginver string no Version of the SDK plugin with which the SDK agent is built; for example, '1.0'.

2.4.6 Publisher Object

Field Type Required Description
id string yes  Publisher ID generated by Vungle Exchange, for example, '570ffeb14e67998f761a791c'.
name string no  Publisher name; for example, 'Supercell Oy'.
cat string array no Refer to OpenRTB 2.3.1 section 5.1.

2.4.7 Device Object

Field Type Required Description
ua string yes  Device browser user agent string; for example, 'Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1'.
ip string yes Not required when ipv6 field is present. This is the IP address of the impression; for example, '212.14.27.104'.
ipv6 string yes Not required when ip field is present. IPv6 address of the impression; for example, '3ffe:1900:4545:3:200:f8ff:fe21:67cf'.
h integer yes Device screen height in pixels.
w integer yes Device screen width in pixels.
connectiontype string yes Refer to OpenRTB 2.3.1 section 5.18.
ifa string yes ID sanctioned for advertiser use in clear text; for example, 'e4fe9bdecaa047b6908dffba3fa184f2'.
geo object no  See the Geo object.
make string no Device make.
model string no Device model.
os string no Device OS; for example, 'iOS', 'Android'. Enum value of:
- 'iOS'
- 'Android'
- 'Windows'
osv string no Device OS version; for example, '9.1', '8.0'.
dnt integer no Whether the device specifies "Do Not Track" (1), or not (0).
lmt integer no Whether the device specifies "Limited Ad Tracking" (1), or not (0).
devicetype string no Refer to OpenRTB 2.3.1 section 5.17.
language string no Device language in ISO-639-1-alpha-2; for example, 'en'.
carrier string no Carrier or ISP; for example, 'VERIZON'.
ext object no See the Device Extension object.

2.4.8 Device Extension

Field Type Required Description
tz string no  Device timezone settings formatted as zone name in the IANA timezone database; for example, 'America/Los_Angeles'.
vungleua string no Deprecated: Use Application.ext.vungle.sdk
sdcard integer no Whether SD card storage is available for Android devices (1) or not (0).
volume float no Value between 0 and 1 denoting the percentage volume of the device.
muted integer no 0 = false 1 = true; enumeration needed.
idfv string no

ID for vendor on iOS devices; an alphanumeric string that uniquely identifies a device to the app’s vendor; for example, '00000000-0001-4d3a-8f98-233623cd8d12'. 

The same device may contain different IDFV values depending on whether the app in the bid request belongs to a different vendor.

2.4.9 Geo Object

Field Type Required Description
country string yes  Country code in ISO-3166-1-alpha-3; for example, 'USA'.
lat float no Latitude of the device; for example, '[-90, 90]'.
long float no Longitude of the device; for example, '[-180, 180]'.
type integer no Refer to OpenRTB 2.3.1 section 5.16.
region string no Region code in ISO-3166-2; 2-letter state code if USA; for example, 'CA'.
city string no Free-form city name.
zip string no Postal code.
utcoffset integer no Local time as the number +/- of minutes from UTC.

2.4.10 Regs Object

Field Type Required Description
coppa integer no Flag indicating whether this request is subject to the COPPA regulations established by the USA FTC, where 0 = no and 1 = yes.
ext object no Placeholder for Vungle Exchange-specific extensions to OpenRTB.

2.4.11 PMP Object

Field Type Required Description
private_auction integer 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.
deal object array no Array of Deal (Section 3.2.18) objects that convey the specific deals applicable to this impression.
ext object no Placeholder for Vungle Exchange-specific extensions to OpenRTB.

3. Response

3.1 Required and Optional Fields

Notes about the Required column in the Response section:

  • Yes: Vungle Exchange assumes a required field to be always formatted as specified, non-empty, with the type specified; invalid values may result in ineligibility for auction.
  • Recommended: Vungle Exchange will use the field to assist in the auction process if the value of the field is formatted as specified; a missing or invalid field does not negatively impact the eligibility in auction.
  • No: Vungle Exchange does not require that the fields exist.
  • Default: All unmentioned fields in OpenRTB 2.3.1 have a default requirement of 'No'. Additionally, all fields must match the type specified, or they may negatively affect auction eligibility.

3.2 Response Headers

Response headers must contain the "Content-Type" header with one of the accepted values from the request headers above. For example,

Content-Type: application/json 

3.3 Response Status Code

All responses must be either 200 or 204. Any other other HTTP response code can negatively affect the DSP's auction eligibility.

3.4 No-Bid Reason Signaling

DSPs are advised to send no-bid reasons when deciding to not bid. This information can help Vungle Exchange detect and fix potential issues with integration. No-bid signaling should follow the OpenRTB 2.3.1 section 7.4 specification. A well formed no-bid signaling with the no-bid reason should look like this: 


{"id": "1234567890", "seatbid": [], "nbr": 2}

3.5 BidResponse Object

Field Type Required Description
id string yes  BidRequest ID generated by Vungle Exchange; for example, '570ffeb14e67998f761a791c'. This must match the id in the BidRequest object.
bidid string no A unique bidder-generated response ID to assist with logging/tracking.
cur string no Bid currency using ISO-4217 alpha codes. Vungle Exchange currently supports only USD and treats any value as USD.
seatbid object array yes Array of seatbid objects; 1+ required if a bid is to be made.
nbr integer no A reason for not bidding, as listed in 5.19 of the OpenRTB 2.3.1 spec.
ext object no  

3.5.1 SeatBid Object

Field Type Required Description
seat string no  ID of the bidder seat on whose behalf this bid is made. Refer to OpenRTB 2.3.1.
bid object array yes  See the Bid object. At least one bid must exist.


3.5.2 Bid Object

Field Type Required Description
id string yes  Bid ID generated by individual DSPs.
impid string yes Impression ID with respect to the bid request's impression for which it is bidding. Must match the ID in the bid request Impression object.
price float yes Bid price expressed in unit of CPM; for example, '10.30'.
nurl string no  Win notice URL called by Vungle Exchange if the bid wins.
adm string yes Ad markup to serve after winning auction. See the Ad Markup Specification section.
cid string recommended Campaign ID proxied by DSP.
crid string recommended Creative ID proxied by DSP.
adomain string array recommended Advertiser domains for block list checking; for example, ["supercell.com"].
bundle string recommended The unique market ID, this is a platform-specific application identifier intended to be unique to the app and independent of the Vungle Exchange.
- On Android, this should be a bundle or package name (for example, 'com.supercell.hayday').
- On iOS, it is a numeric ID.
h integer recommended Height of the creative.
w integer recommended Width of the creative.
cat string array no  IAB content categories; Refer to OpenRTB 2.3.1 section 5.1.
iurl string no  Lost notification URL.
dealid string no  Reference to the deal.id from the BidRequest object if this bid pertains to a private marketplace direct deal.
adid string no  ID of a preloaded ad to be served if the bid wins.
ext object no   

4. Examples

4.1 Request Example


{
    "id": "58ed309efa8936087efd1349",
    "imp": [{
        "id": "58ed309efa8936087efd134a",
        "video": {
            "mimes": ["video/mp4"],
            "minduration": 5,
            "maxduration": 30,
            "protocols": [2, 3, 5, 6],
            "w": 1080,
            "h": 1920,
            "startdelay": 0,
            "linearity": 1,
            "minbitrate": 250,
            "maxbitrate": 2500,
            "boxingallowed": 1,
            "playbackmethod": [1, 2, 3, 4],
            "delivery": [1, 2],
            "pos": 7
        },
        "displaymanager": "Vungle",
        "displaymanagerver": "3.3.5",
        "instl": 1,
        "bidfloor": 15,
        "bidfloorcur": "USD"
    }],
    "app": {
        "id": "56b8e577819502560b000033",
        "name": "test-pub-app-name",
        "bundle": "1045826890",
        "storeurl": "https://itunes.apple.com/us/app/id1234567?mt=8",
        "cat": [
            "IAB1"
        ],
        "privacypolicy": 1,
        "publisher": {
            "id": "test-pub-app-id",
            "name": "test-pub-app-name",
            "cat": [
                "IAB1"
            ]
        },
        "ext": {
            "vungle": {
                "altid": "5fff577819502560b000033",
                "btags": ["real money gambling", "social casino"],
                "wtags": ["targeted tag", "social"]
            }
        }
    },
    "device": {
        "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 8_4 like Mac OS X) AppleWebKit/600.1.4 (KHTML, like Gecko) Mobile/12H141",
        "geo": {
            "lat": 47.46,
            "lon": -122.16,
            "type": 1,
            "country": "USA",
            "region": "WA",
            "city": "San Francisco",
            "zip": "94103"
        },
        "dnt": 0,
        "lmt": 0,
        "ip": "192.168.1.1",
        "devicetype": 1,
        "make": "Samsung",
        "model": "SM-J200G",
        "connectiontype": 2,
        "os": "iOS",
        "osv": "8.0",
        "w": 1080,
        "h": 1920,
        "js": 1,
        "language": "en",
        "ifa": "test-ifa",
        "ext": {
            "vungle": {
                "isSdCardAvailable": 1,
                "vungleua": "VungleDroid/3.3.5",
                "tz": "Europe/Kaliningrad",
                "sdcard": 1,
                "volume": 0.13333334,
                "muted": 1
            }
        }
    },
    "bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42"],
    "at": 2,
    "cur": ["USD"],
    "tmax": 250
}

4.2 Response Example


{
  "id": "58ed309efa8936087efd1349",
  "bidid": "5508",
  "cur": "USD",
  "seatbid": [
    {
      "seat": "7735",
      "bid": [
        {
          "id": "5508",
          "impid": "58ed309efa8936087efd134a",
          "price": 50,
          "nurl": "http://bidder.com/won?price=${AUCTION_PRICE}",
          "adm": "http://bidder.com/vast?id=${AUCTION_ID}",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

5. Ad Markup Specification

Vungle Exchange supports primarily three types of markups: VAST, MRAID, and proprietary Vungle Ad Markup. While each has its high-level specification, to be considered as a valid markup for performance reasons, it must also comply with the additional requirements below.

5.1 VAST

The following tag must appear in the first 100 bytes of the 'adm' field, or the payload of the 'nurl' response:

<VAST version="2.0">

5.2 Macro Substitution

Vungle Exchange supports a macro substitution for the auction price in the nurl field of the Bid object in the bid response. For example:


"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
Have more questions? Submit a request

Comments