1. Help Center
  2. Vungle Exchange
  3. OpenRTB Integration

Vungle Exchange OpenRTB 2.5 Integration Guide

Avatar
Vungle Agent
Follow

Use this guide to participate in the Vungle Exchange using Vungle Exchange OpenRTB 2.5.

In response to iOS 14 privacy changes, we support SKAdNetwork attribution starting with Liftoff Monetize SDK v.6.8. This guide now includes guidelines for DSPs to work with SKAdNetwork on Vungle Exchange.

If a DSP wishes to use our SKAdNetwork solution, after registering with Apple, they should provide Vungle Exchange with their SKAdNetwork ID.

1. Introduction

This article specifies the details for integrating with Vungle Exchange using IAB OpenRTB API Specification Version 2.5. To maintain some parity, we have organized our section numbering to correspond to the IAB OpenRTB spec as much as possible. Because all entities in this article are a subset of the IAB OpenRTB API Specification Version 2.5, there may be gaps in our section numbering where Vungle Exchange does not have a corresponding entity.

2. Request and Response

2.1 Entity

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

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

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

2.3 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.5 default to not required.

2.4 Protocol Negotiation

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

3. Bid Request

3.1 Request Headers

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

X-OpenRTB-Version: 2.5

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

Content-Type: application/json 
Accept: application/json 

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

X-Vungle-OpenRTB-Version: 2.5

3.2 Request Objects

3.2.1 BidRequest Object

Field Type Always Passed 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 App object.
device object yes See the Device object.
at integer yes

Type of auction; for example, '2' for second-price auction. Always send '1'; Vungle Exchange runs first-price auctions.
tmax integer yes

Maximum time in milliseconds to submit a complete bid response.
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 IAB OpenRTB API Specification Version 2.5, List 5.1 "Content Categories."
badv string array no Block list of advertisers by their domains (e.g., “ford.com”)
bapp string array no Block list of applications by their platform-specific, exchange-independent application identifiers. On Android, these should be bundle or package names (e.g., 'com.foo.mygame'). On iOS, these are numeric IDs.
regs object no Refer to IAB OpenRTB API Specification Version 2.5, Section 3.2.3 "Regs."
test integer no

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

Refer to IAB OpenRTB SupplyChain object implementation guide.

3.2.2 BidRequest.Source.ext Object

Field Type Always Passed Description
schain object no This object represents both the links in the supply chain and an indicator whether or not the supply chain is complete.
omidpn String no Identifier of the OM SDK integration. This value will always be passed as vungle.
omidpv String no Version of the OM SDK integration. Reflects the Vungle SDK version.

3.2.2.1 Source.ext.schain Object

Field Type Always Passed Description
complete integer no

Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app, or other medium of the inventory, where

'0' = no

'1' = yes
nodes object array no Array of SupplyChainNode objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction; i.e., the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.
ver String no Version of the supply chain specification in use, in the format of “major.minor”. For example, for version 1.0 of the spec, use the string "1.0".

3.2.2.2 Source.ext.schain.nodes Object

Field Type Always Passed Description
asi String no  The canonical domain name of the SSP, Exchange, Header Wrapper, etc. system to which bidders connect (that is, the domain name of the SSP or exchange facilitating the sale of the impression.) This should be the same value as used to identify sellers in an ads.txt file, if one exists.
sid String no The identifier associated with the seller or reseller account within the advertising system. This must contain the same value used in transactions (i.e., OpenRTB bid requests) in the field specified by the SSP/exchange. Typically, in OpenRTB, this is publisher.id. For OpenDirect, it is typically the publisher’s organization ID. Should be limited to 64 characters in length.
rid String no The OpenRTB RequestId of the request as issued by this seller.
hp integer no Indicates whether this node will be involved in the flow of payment for the inventory. When set to '1', the advertising system in the asi field pays the seller in the sid field, who is responsible for paying the previous node in the chain. When set to '0', this node is not involved in the flow of payment for the inventory. For version 1.0 of SupplyChain, this property should always be '1'.
name String no

The name of the company (the legal entity) that is paid for inventory transacted under the given seller_id. This value is optional and is NOT included if it exists in the advertising system’s  sellers.json file.

3.2.3 Regs Object

Field Type Always Passed Description
coppa integer no

Flag indicating whether this request is subject to the COPPA regulations established by the USA FTC, where '1' = yes.
ext object yes Placeholder for Vungle Exchange-specific extensions to OpenRTB. See Regs Extension.

3.2.3.1 Regs Extension

Field Type Always Passed Description
gdpr integer no

Flag indicating if this request is subject to the GDPR regulations.

'0' = no

'1' = yes
us_privacy string no

Follow the IAB US Privacy string format.

3.2.4 Imp Object

Field Type Always Passed Description
id string yes  Impression ID generated by Vungle Exchange. Starts with 1 and increments; for example, '1'.
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.
displaymanagerver 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'.
banner object no  See the Banner object.
video object no  See the Video object.
native object no  See the Native object.
tagid string yes 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). Omission of field is equivalent to instl=0.
secure integer yes

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where

'0' = non-secure

'1' = secure.

We always pass '1' = secure.
ext object no  

3.2.4.1 Imp Extension

Field Type Always Passed Description
skadn object no

Support for Apple's SKAdNetwork.
deeplink Boolean no

Indicates whether deep linking is supported for this impression.
‘1’ = deep linking is supported
‘0’ = deep linking is not supported

Refer to our Deep Linking article for details.
skpv integer no

Indicates whether the inventory is eligible to show SKPV. Only passed in iOS bid request.
'1' = true; inventory is eligible to show SKPV
'0' = false; inventory is NOT eligible to show SKPV
vxec integer no

Indicates whether or not the inventory is eligible for VX EC
'1' = inventory is eligible for showing VX EC
'0' = inventory is NOT eligible for showing VX EC
pcta integer (not nullable) yes

Indicates whether the impression opportunity is eligible for Persistent CTA.
'1' = The inventory is eligible for showing Persistent CTA
'0' = The inventory is NOT eligible for showing Persistent CTA

3.2.4.1.1 SKAdNetwork Imp Extension: imp.ext.skadn

Field Type Always Passed Description
version string yes Version of SKAdNetwork supported.Always "2.0" or higher. Dependent on both the OS version and the SDK version.
versions string array yes

Array of strings containing the supported SKAdNetwork versions. Always "2.0"or higher. Dependent on both the OS version and the SDK version.
sourceapp string yes

ID of Publisher App in Apple’s App Store. Matches app.bundle.
skadnetids string array yes

A subset of SKAdNetworkItem entries in the publisher app’s Info.plist that are relevant to the DSP. The value can be empty.
ext object no

Placeholder for exchange-specific extensions to OpenRTB.

3.2.6 Banner Object

Field Type Always Passed Description
format object array yes  Width and height object, same as w,h.For example: [{w": 320, "h": 50}]
w integer yes Width of the impression in pixels.
h integer yes Height of the impression in pixels.
battr integer array no  Blocked creative attributes. Only passed for In-Line ads. Refer to List 5.1 Creative Attributes.
pos integer no Refer to IAB OpenRTB API Specification Version 2.5, List 5.4 "Ad Position" for details.
api integer array no Refer to the API Frameworks section for details.
mimes string array yes  Content MIME types supported. Vungle Exchange supports ["image/jpg", "image/gif", "text/html"].
id string yes Refer to IAB OpenRTB API Specification Version 2.5, List 3.2.6 "Object: Banner" for details.
vcm integer no

Relevant only for Banner objects used with a Video object (Section 3.2.7) in an array of companion ads. Indicates the companion banner rendering mode relative to the associated video. Only passed for full-screen impressions.

Refer to IAB OpenRTB API Specification Version 2.5, List 3.2.7 "Object: Video" for details.

3.2.7 Video Object

Field Type Always Passed Description
h integer yes Height of the video.
w integer yes Width of the video.
battr integer array no  Blocked creative attributes. Refer to List 5.1 Creative Attributes.
placement integer array yes  Placement type for the impression. Refer to table 5.5 Video Placement Types.
plcmt integer array no  Video placement type for the impression. Refer to table 5.5 Video Placement Types.
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 yes Supported list of video delivery methods:
'1' = streaming
'2' = progressive
Refer to the Content Delivery Methods section for detail.
minbitrate integer yes Minimum bid rate in kbps. Vungle Exchange currently only supports 250.
maxbitrate integer yes Maximum bid rate in kbps; for example, 500. Vungle Exchange currently supports 15000 maximum bit rate.
protocols integer array yes Refer to IAB OpenRTB API Specification Version 2.5, List 5.8 "Protocols"; for example, [2, 5]. Vungle Exchange currently supports [2,3,5,6].
boxingallowed integer yes Whether boxing the video is allowed (1) or not (0). The value for this is always '1'.
playbackmethod integer array yes Refer to IAB OpenRTB API Specification Version 2.5, Section 5.10 "Playback Methods." Vungle Exchange currently supports [1,2,3,4].
skip boolean no  Denotes skippable (1) or non-skippable (0) inventory.
skipafter integer no Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable.
companionad object array no Indicates whether or not the inventory is eligible for a triple page ad when two arrays are present
companiontype integer array no Supported VAST companion ad types. VX supports
'1' = Static Resource
'2' = HTML Resource

3.2.7.1 Video Extension

Field Type Always Passed Description
videotype string no Used to specify rewarded inventory. If not rewarded, we omit this field.
rewarded boolean no Additional field to denote rewarded (1). If not rewarded, we omit this field. Only fill if placement is incentivized.

3.2.9 Native Object

Field Type Always Passed Description
request string yes Request payload compliant with Native Ad specification (refer to Vungle OpenRTB 2.5 Native Ad Integration for variables, definitions, and extensions).
ver string yes Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.
We currently support '1.2' only.

Refer to Vungle OpenRTB 2.5 Native Ad Integration for variables, definitions, and extensions.

3.2.11 PMP Object

Field Type Always Passed 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.

Only send '0' for this field.
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.2.14 App Object

Field Type Always Passed Description
id string yes  Exchange-specific ID. For Vungle, this is the app store ID; for example, '3709293'. The value is also synonymous with the app.id value from the SDK request.

This ID may mean nothing to the DSP, but may be used by the DSP to compare and reconcile reporting disputes.
bundle string no 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 yes IAB content categories. Refer to IAB OpenRTB API Specification Version 2.5, List 5.1 "Content Categories."
privacypolicy integer no Whether the application has a privacy policy (1), or not (0). Vungle Exchange only supports '1' for this field.
keywords string no Comma-separated list of tags for the publisher application.
ext object no  

3.2.15 Publisher Object

Field Type Always Passed Description
id string yes  Publisher ID generated by Vungle Exchange, for example, '570ffeb14e67998f761a791c'.
cat string array no Refer to IAB OpenRTB API Specification Version 2.5, List 5.1 "Content Categories." Vungle Exchange only supports 'IAB-1' and “IAB-9” for this field.

3.2.18 Device Object

Field Type Always Passed 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 IAB OpenRTB API Specification Version 2.5, List 5.22 "Connection Type."
ifa string no ID sanctioned for advertiser use in clear text; for example, 'e4fe9bdecaa047b6908dffba3fa184f2'.
dpidsha1 string no Platform device ID (for example, Android ID), hashed via SHA1.
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'.
hwv string no Hardware version of the device (e.g., “5S” for iPhone 5S).
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 IAB OpenRTB API Specification Version 2.5, List 5.21 "Device Type."
language string no Device language in ISO-639-1-alpha-2; for example, 'en'.
carrier string no Carrier or ISP; for example, 'VERIZON'.

3.2.18.1 Device Extension

Field Type Always Passed Description
ifv string no  IDFV of device in that publisher. Only passed when IDFA is unavailable or all zeros. Currently passed for iOS only. The same value will be passed in this field and the idfvfield.
idfv string no  IDFV of device in that publisher. Only passed when IDFA is unavailable or all zeros. Currently passed for iOS only. The same value will be passed in the  ifvfield.
atts integer no  (iOS Only) An integer passed to represent the app's app tracking authorization status, where
'0' = not determined
'1' = restricted
'2' = denied
'3' = authorized
app_set_id string no  Contains the Android App Set ID. Available on Android 12+ devices on Vungle SDK v.6.10.3+

3.2.19 Geo Object

Field Type Always Passed 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]'.
lon float no Longitude of the device; for example, '[-180, 180]'.
type integer no Refer to IAB OpenRTB API Specification Version 2.5, List 5.20 "Location Type."
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.
ipservice integer yes Service or provider used to determine geolocation from IP address if applicable (e.g., type = 2). Refer to IAB OpenRTB API Specification Version 2.5, List 5.23 "IP Location Services."
Vungle Exchange only supports '3:MaxMind' for this field.

3.2.20 User Object

Field Type Always Passed Description
ext object no See the User Extension object.

3.2.20.1 User Extension

Field Type Always Passed Description
consent integer no

The user consent string is optional, but present if the request is subject to GDPR regulations (that is, Regs.ext.gdpr = 1). The default sense of consent under GDPR is “opt-out”. Therefore an omitted consent string in a request subject to GDPR is interpreted as equivalent to the user fully opting out of all defined purposes for data use by all parties.

'0' = all PII scrubbed

'1' = user has given consent

4. Bid Response

4.1.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.5 have a default requirement of 'No'. Additionally, all fields must match the type specified, or they may negatively affect auction eligibility.

4.1.2 Response Headers

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

Content-Type: application/json 
X-OpenRTB-Version: 2.5

4.1.3 Response Status Code

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

4.1.4 No-Bid Response

DSPs are advised to send no-bid code as 204 with an empty response body when deciding to not bid.

4.2 Response Objects

4.2.1 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 no 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.24 of the OpenRTB 2.5 spec.
ext object no  

4.2.2 SeatBid Object

Field Type Required Description
seat string recommended  ID of the bidder seat on whose behalf this bid is made. Refer to IAB OpenRTB API Specification Version 2.5, Section 4.2.2 "Object: SeatBid."
bid object array recommended See the Bid object. At least one bid must exist.

4.2.3 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 recommended Win notice URL called by Vungle Exchange if the bid wins.
burl string  recommended Billing notice URL called by Vungle Exchange if the bid wins. 
lurl  string  recommended Loss notice URL called by Vungle Exchange when the bid loses. 
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 yes 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. Required for Persistent CTA.
- On Android, this should be a bundle or package name (for example, 'com.supercell.hayday').
- On iOS, it is a numeric ID.
cat string array no  IAB content categories; refer to IAB OpenRTB API Specification Version 2.5, Section 5.1 "Content Categories."
dealid string recommended  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.
api integer no  List of supported API frameworks for this impression. Refer to the API Frameworks section for details. Buyers are required to pass api='7' for Open Measurement.
attr integer array required when applicable 

Set of attributes defining the creative. Refer to the Creative Attributes table.

When submitting VAST video + HTML playable endcard, include "attr": [13] in the seatbid.bid.attr.

When submitting an interactive or animated MRAID creative, include "attr": [13] in the seatbid.bid.attr.
ext object no   

4.2.3.2 Bid Extension

Field Type Required Description
skadn object no Parameters required to support Apple's SKAdNetwork attribution API, via loadProduct().
imptrackers string array no Identify impression track URL from DSP.
clicktrackers string array no Array of click-tracking URLs to be fired on click.
deeplink string no Optional URL directing the user to specific content within the app if the app is already installed. If the app is not already installed and the deep link URL cannot be rendered, we default to the download URL. Refer to our Deep Linking article for more details.
crtype string no

Identifies the creative type of given ADM; for example:

  • 'HTML'
  • 'MRAID 1.0'
  • 'MRAID 2.0'
  • 'native'
  • 'VAST 2.0'
  • 'VAST 3.0'

When serving VAST + an MRAID endcard, please pass the MRAID version as the crtype.
pcta.pctapage1 integer no

Indicates whether or not to add Persistent CTA on the video.

'1' = DSP allows Persistent CTA to be added

'0' = DSP does not allow Persistent CTA to be added

  • The field is not required; if the field is passed, DSP must return '1' or '0' (true or false are not accepted).
  • By default, missing pcta object or pctapage1 pctapage1 field indicates Persistent CTA opt-in.
  • If pcta is passed without a value or with an incorrect datatype, the bid response will be treated as invalid.
vxec integer no Indicates whether or not to add VX EC after the video or after the playable endcard.
'1' = DSP allows VX EC to be added.
'0' = DSP does not allow VX EC to be added.
Not passing this field means '1'.
skpv object no Refer to the StoreKitProductView Object.

4.2.3.3 StoreKitProductView Object

Field Type Required Description
page1onclose integer no

Indicates whether Vungle should show SKPV after the first page.
'1' = true: show SKPV after the first page of the creative).
'0' = false: do not show SKPV after the first page.

Not passing this field means '1'.
page2onclose integer no

Indicates whether Vungle should show SKPV after the second page.
'1' = true: show SKPV after the first page of the creative).
'0' = false: do not show SKPV after the first page.

Not passing this field means '1'.

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

4.3.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">
    <Ad>
        <InLine>
            <AdTitle>
                YOUR_AD_NAME
            </AdTitle>
            <Impression>
                <![CDATA[https://YOUR_IMPRESSION_TRACKING_URL?ttdsp_price=${AUCTION_PRICE}]]>
            </Impression>
            <Creatives>
                <Creative id="YOUR_CREATIVE_ID">
                    <Linear>
                        <Duration>00:00:18</Duration>
                        <TrackingEvents>
                            <Tracking event="start">
                                <![CDATA[https://YOUR_IMPRESSION_TRACKING_URL_START_PLAY]]>
                            </Tracking>
                            <Tracking event="complete">
                                <![CDATA[https://YOUR_IMPRESSION_TRACKING_URL_START_COMPLETE]]>
                            </Tracking>
                        </TrackingEvents>
                        <VideoClicks>
                            <ClickThrough>
                                <![CDATA[https://YOUR_DESTINATION_URL_TO_DOWNLOAD_BY_CLICK]]>
                            </ClickThrough>
                            <ClickTracking>
                                <![CDATA[https://YOUR_CLICK_TRACKING_URL]]>
                            </ClickTracking>
                        </VideoClicks>
                        <MediaFiles>
                            <MediaFile delivery="progressive" type="video/mp4" width="1280" height="720">
                                <![CDATA[https://YOUR_AD_VIDEO.mp4]]>
                            </MediaFile>
                        </MediaFiles>
                    </Linear>
                </Creative>
            </Creatives>
            <Description>Longer description of ad</Description>
        </InLine>
    </Ad>
</VAST>

4.3.2 Macro Substitution

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

"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"

Vungle Exchange supports the following macros:

Name Description
${AUCTION_ID} ID of the bid request; from BidRequest.id attribute
${AUCTION_BID_ID} ID of the bid; from BidResponse.bidid attribute
${AUCTION_SEAT_ID} ID of the bidder seat for whom the bid was made
${AUCTION_AD_ID} ID of the ad markup the bidder wishes to serve; from bid.adid attribute
${AUCTION_PRICE} Clearing price using the same currency and units as the bid.
${AUCTION_LOSS} Loss reason codes. Refer to List 4.5.1.
${AUCTION_CURRENCY} The currency used in the bid (explicit or implied); for confirmation only.
${MIN_BID_TO_WIN} The minimum bid that the bidder would have needed to win the auction against all competing demand sources. Supported via lurl only

4.4 SKAdNetwork

Vungle Exchange supports Apple’s SKAdNetwork versions 2.0, 2.2, and 3.0 to facilitate app install and conversion tracking for our programmatic buyers buying on iOS 14+. We don't pass SKAdNetwork 2.1 in our bid request.

  • Liftoff Monetize iOS SDK v.6.10.0 and higher supports SKAdNetwork v.2.2 on iOS 14.5+.
  • Liftoff Monetize iOS SDK v.6.10.1 and higher supports SKAdNetwork v.3.0 on iOS 14.6+.
  • Liftoff Monetize iOS SDK v.7.1 and higher supports SKAdNetwork v.4.0 on iOS 16.1+.

4.4.1 SKAdNetwork Bid Request Object: BidRequest.imp.ext.skadn

Field Type Required Description
version string yes Version of SKAdNetwork supported.Always "2.0" or higher. Dependent on both the OS version and the SDK version.
versions string array yes

Array of strings containing the supported SKAdNetwork versions. Always "2.0"or higher. Dependent on both the OS version and the SDK version.
sourceapp string yes

ID of Publisher App in Apple’s App Store. Matches app.bundle.
skadnetids string array yes

A subset of SKAdNetworkItem entries in the publisher app’s Info.plist that are relevant to the DSP. The value can be empty.
ext object no

Placeholder for exchange-specific extensions to OpenRTB.

4.4.1.2 Skadn Extension

Field Type Required Description
sko integer yes Indicate if SKOverlay Auto Show is eligible.
'1' = The bid request is eligible for SKOverlay Auto show.
None = The bid request is ineligible for SKOverlay Auto show.

4.4.1.1 SKAdNetwork Bid Request Example

"skadn": {
	"version": "2.2",
	"versions": [
		"2.0",
		"2.2"
			],
	"sourceapp": "123456789",
	"skadnetids": [
	"example123.skadnetwork"
	         	]
		}

4.4.2 SKAdNetwork Bid Response Object: BidResponse.seatbid.bid.ext.skadn

Field Type Required Description
version string yes Version of SKAdNetwork. Must be 2.0 or higher.
itunesitem string yes ID of advertiser’s app in Apple’s app store. Should match BidResponse.seatbid.bid.bundle.
sourceapp string yes ID of publisher’s app in Apple’s app store. Should match BidRequest.imp.ext.skad.sourceapp.
network string yes Ad network identifier used in signature. Should match one of the items in the  skadnetidsarray in the request. 
campaign string yes

Campaign ID compatible with Apple’s spec. As of SKAdNetwork 2.0-3.0, this should be an integer between 1 and 100, expressed as a string. For SKAdNetwork 4.0+, this should be an integer between 0 and 9999.

Both campaignand sourceidentifier fields are supported on SKAN 4.0+.
sourceidentifier string no

A four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+, replaces the campaign field. DSPs must generate signatures in 4.0+ using the Source Identifier. Should be a four-digit integer expressed as a string between 0000 and 9999.

Both campaignand sourceidentifier fields are supported on SKAN 4.0+.
fidelities object array yes The fidelity object block. Refer to the Fidelities Extension.
cpp string no The product page ID (PPID) parameter added to the default product page URL for Apple Custom Product Pages
Notes:
- Supported on SDK v.6.11+ and iOS 15+
- VX receives PPID from ext.skadn.cpp first, then looks to the CTA URL to extract PPID
ext object no Placeholder for exchange-specific extensions to OpenRTB.

4.4.2.1 SKAdNetwork Fidelities Extension: ext.skadn.fidelities

Field Type Required Description
fidelity integer yes The fidelity-type of the attribution to track.
nonce string yes An ID unique to each ad response. Refer to Apple’s documentation for the proper UUID format requirements.
timestamp string yes UNIX time in milliseconds string used at the time of signature.
signature string yes SKAdNetwork signature as specified by Apple.

4.4.2.2 SKAdNetwork Overlay Extension: ext.skadn.ext.skoverlay

Field Type Required Description
show integer yes

Whether to show SKOverlay, where

'0' = no

'1' = yes

It is NOT valid to submit show as false while submitting other attributes in skoverlay.
Must pass App Store ID (skadn.itunesitem) if skoverlay.show=1.
delay integer no Delay before showing the SKOverlay on video, in seconds.
delay='0' means to show the overlay immediately.
Omitting this field means NEVER showing the overlay on video.
Note: Recommend to use a 5s delay or higher (to give the SDK time to prepare the SKO).
companion_delay integer no Delay before showing the SKOverlay on companion ads, in seconds.
Omitting this field means NEVER showing the overlay on endcard.
A value such as 0, 1, or 5, will be understood to mean “show SKO on the endcard after X seconds."
pos integer no

Position of the overlay.

'0' = bottom

'1' = bottomRaised

4.4.2.3 SKAdNetwork 2.2 Bid Response Example

"ext":{
                  "skadn":{
                     "campaign":"50",
                     "fidelities":[
                       {
                           "fidelity":0,
                          "nonce":"dd9bd787-2d01-4ba6-a147-464ed8b3b029",
                           "signature":"MEUCIQDYdJbL￥%……&*90900808=",
                          "timestamp":"1648110176238"
                       },
                       {
                          "fidelity":1,
                          "nonce":"44f6469a-5be4-4679-abb8-03af9b497b12",
                          "signature":"MEUCIDzSRb0Gjen3R/Ax3LTkxkk0Aysz8=",
                          "timestamp":"1648110176239"
                       }
                    ],
                     "itunesitem":"575980917",
                     "network":"example123.skadnetwork",
                    "sourceapp":"1234567890",
                    "version":"2.2"
                 }
               }

4.4.2.4 SKAdNetwork 3.0 Bid Response Example

{
	"version": "3.0",
	"network": "7ug5zh24hu.skadnetwork",
	"campaign": "3",
	"itunesitem": "284815942",
	"sourceapp": "929195587",
	"fidelities": [{
			"fidelity": 0,
			"nonce": "bb425e0d-915a-48d7-bf0f-2677551ddc1c",
			"timestamp": "1686655094322",
			"signature": "MEUCICvoq9qmlrd8Bd4W+am6fetJ+G95F3AuwZVvnrL3yTyaAiEAhJrIR/KPHsNry2E8w0pLHmSKb1T2/QdRw1pOmIgEj48="
		},
		{
			"fidelity": 1,
			"nonce": "6b3587ce-e9f0-449d-9657-4a9f9cce9e49",
			"timestamp": "1686655094322",
			"signature": "MEQCIFlZ7wExUsaIGFx1VJY2h7b/1OTbm5KcqV/mGptwARJBAiB+EsuJuYhICxCuOlNFF37OcWfFyc01JNA2ahbAFBqDjA=="
		}
	]
}

4.4.2.5 SKAdNetwork 4.0 Bid Response Example

{
	"version": "4.0",
	"network": "7ug5zh24hu.skadnetwork",
	"campaign": "1234",
	"itunesitem": "284815942",
	"sourceapp": "929195587",
	"fidelities": [{
			"fidelity": 0,
			"nonce": "bb425e0d-915a-48d7-bf0f-2677551ddc1c",
			"timestamp": "1686655094322",
			"signature": "MEUCICvoq9qmlrd8Bd4W+am6fetJ+G95F3AuwZVvnrL3yTyaAiEAhJrIR/KPHsNry2E8w0pLHmSKb1T2/QdRw1pOmIgEj48="
		},
		{
			"fidelity": 1,
			"nonce": "6b3587ce-e9f0-449d-9657-4a9f9cce9e49",
			"timestamp": "1686655094322",
			"signature": "MEQCIFlZ7wExUsaIGFx1VJY2h7b/1OTbm5KcqV/mGptwARJBAiB+EsuJuYhICxCuOlNFF37OcWfFyc01JNA2ahbAFBqDjA=="
		}
	]
}

5. Enumerated Lists

5.1 Creative Attributes

The following table specifies a standard list of creative attributes that can describe an ad being served or serve as restrictions thereof.

Value Description
1 Audio Ad (Auto-Play)
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 Provides Skip Button (e.g., VPAID-rendered skip button on pre-roll video)
17 Adobe Flash

5.2 Loss Reason Codes

Value Description
0 Bid won
1 Internal error
2 Impression opportunity expired
3 Invalid bid response
4 Invalid Deal ID
5 Invalid Auction ID
6 Invalid (i.e., malformed) advertiser domain
7 Missing markup
8 Missing Creative ID
9 Missing bid price
10 Missing minimum creative approval data
100 Bid was below auction floor
101 Bid was below deal floor
102 Lost to higher bid
103 Lost to a bid for a PMP ceal
104 Buyer seat blocked
200 Creative filtered: General; reason unknown
201 Creative filtered: Pending processing by Exchange (e.g., approval, transcoding, etc.)
202 Creative filtered: Disapproved by Exchange
203 Creative filtered: Size not allowed
204 Creative filtered: Incorrect creative format
205 Creative filtered: Advertiser exclusions
206 Creative filtered: App bundle exclusions
207 Creative filtered: Not secure
208 Creative filtered: Language exclusions
209 Creative filtered: Category exclusions
210 Creative filtered: Creative attribute exclusions
211 Creative filtered: Ad type exclusions
212 Creative filtered: Animation too long
213 Creative filtered: Not allowed in PMP deal
1000 Bid price was too high

5.3 API Frameworks

Value Description
1 VPAID 1.0
2 VPAID 2.0
3 MRAID-1
4 ORMMA
5 MRAID-2
6 MRAID-3
7 OMID-1

5.4 Content Delivery Methods

Value Description
1 Streaming
2 Progressive

5.5 Video Placement Types

Value Description
1 Instream: Pre-roll, mid-roll, and post-roll ads that are played before, during, or after the streaming video content that the consumer has requested. Instream video must be set to “sound on” by default at player start, or have explicitly clear user intent to watch the video content. While there may be other content surrounding the player, the video content must be the focus of the user’s visit. It should remain the primary content on the page and the only video player in-view capable of audio when playing. If the player converts to floating/sticky subsequent ad calls should accurately convey the updated player size.
2 Accompanying Content: Pre-roll, mid-roll, and post-roll ads that are played before, during, or after streaming video content. The video player loads and plays before, between, or after paragraphs of text or graphical content, and starts playing only when it enters the viewport. Accompanying content should only start playback upon entering the viewport. It may convert to a floating/sticky player as it scrolls off the page.
3 Interstitial: Video ads that are played without video content. During playback, it must be the primary focus of the page and take up the majority of the viewport and cannot be scrolled out of view. This can be in placements like in-app video or slideshows
4 No Content/Standalone: Video ads that are played without streaming video content. This can be in placements like slideshows, native feeds, in-content or sticky/floating. Vungle Exchage will always pass this value for In-Feed Ads.

6. Request Examples

6.1 Full Screen Request Example

iOS Static Interstitial Request (Banner Object Only)

                        {
                            "id": "6675a52b8b6dcc1ad5c0389d",
                            "imp": [
                                {
                                    "id": "1",
                                    "banner": {
                                        "format": [
                                            {
                                                "w": 320,
                                                "h": 480
                                            }
                                        ],
                                        "w": 320,
                                        "h": 480,
                                        "pos": 7,
                                        "mimes": [
                                            "image/jpg",
                                            "image/gif",
                                            "text/html"
                                        ],
                                        "api": [
                                            5,
                                            7
                                        ],
                                        "id": "1",
                                        "vcm": 1
                                    },
                                    "video": {
                                        "mimes": [
                                            "video/mp4"
                                        ],
                                        "minduration": 0,
                                        "maxduration": 120,
                                        "protocols": [
                                            2,
                                            5,
                                            3,
                                            6
                                        ],
                                        "w": 320,
                                        "h": 480,
                                        "placement": 5,
                                        "plcmt": 3,
                                        "linearity": 1,
                                        "skip": 1,
                                        "skipafter": 5,
                                        "minbitrate": 250,
                                        "maxbitrate": 15000,
                                        "boxingallowed": 1,
                                        "playbackmethod": [
                                            1,
                                            2,
                                            3,
                                            4
                                        ],
                                        "delivery": [
                                            2,
                                            1
                                        ],
                                        "pos": 7,
                                        "companionad": [
                                            {
                                                "format": [
                                                    {
                                                        "w": 320,
                                                        "h": 480
                                                    }
                                                ],
                                                "w": 320,
                                                "h": 480,
                                                "pos": 7,
                                                "api": [
                                                    5
                                                ],
                                                "id": "6675ae4e428c91f151e6011e-1",
                                                "vcm": 1
                                            }
                                        ],
                                        "api": [
                                            7
                                        ],
                                        "companiontype": [
                                            1,
                                            2
                                        ],
                                        "ext": {}
                                    },
                                    "displaymanager": "Vungle",
                                    "displaymanagerver": "6.12.1",
                                    "instl": 1,
                                    "tagid": "PUBLISHER_PLACEMENT_ID",
                                    "bidfloor": 4,
                                    "bidfloorcur": "USD",
                                    "secure": 1,
                                    "ext": {
                                        "skadn": {
                                            "version": "2.0",
                                            "versions": [
                                                "2.0"
                                            ],
                                            "sourceapp": "123456789",
                                            "skadnetids": [],
                                            "ext": {
                                                "sko": 1
                                            }
                                        },
                                        "deeplink": 1,
                                        "skpv": 0,
                                        "vxec": 0,
                                        "pcta": 1
                                    }
                                }
                            ],
                            "app": {
                                "id": "62d8fb315da899193f643165",
                                "name": "Vungle Test App"",
                                "bundle": "123456789",
                                "storeurl": "https://apps.apple.com/us/app/app_store_url",
                                "cat": [
                                    "IAB1",
                                    "IAB9"
                                ],
                                "ver": "1",
                                "privacypolicy": 1,
                                "publisher": {
                                    "id": "56e0de2215a62b831800002b",
                                    "cat": [
                                        "IAB1",
                                        "IAB9"
                                    ]
                                },
                                "keywords": "managed",
                                "ext": {}
                            },
                            "device": {
                                "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
                                "geo": {
                                    "lat": 28.0109,
                                    "lon": -82.4948,
                                    "type": 2,
                                    "ipservice": 3,
                                    "country": "USA",
                                    "region": "FL",
                                    "city": "Tampa",
                                    "zip": "33614"
                                },
                                "dnt": 0,
                                "lmt": 0,
                                "ip": "199.193.115.73",
                                "devicetype": 4,
                                "make": "Apple",
                                "model": "iPhone",
                                "os": "iOS",
                                "osv": "13.4",
                                "h": 2688,
                                "w": 1242,
                                "language": "en",
                                "connectiontype": 2,
                                "ifa": "00000000-0000-0000-0000-000000000000",
                                "dpidsha1": "b602d594afd2b0b327e07a06f36ca6a7e42546d0",
                                "ext": {
                                    "idfv": "25336879-2A81-4E49-818D-CAE28C2A97BB",
                                    "ifv": "25336879-2A81-4E49-818D-CAE28C2A97BB",
                                    "atts": 0
                                }
                            },
                            "user": {},
                            "at": 1,
                            "tmax": 1000,
                            "cur": [
                                "USD"
                            ],
                            "bcat": [   
                                "IAB26",
                            ],
                            "badv": [
                            ],
                            "bapp": [
                            ],
                            "source": {
                                "ext": {
                                    "schain": {
                                        "complete": 1,
                                        "nodes": [
                                            {
                                                "asi": "vungle.com",
                                                "sid": "56e0de2215a62b831800002b",
                                                "rid": "6675a52b8b6dcc1ad5c0389d",
                                                "hp": 1
                                            }
                                        ],
                                        "ver": "1.0"
                                    },
                                    "omidpn": "vungle",
                                    "omidpv": "6.12.1"
                                }
                            },
                            "regs": {
                                "ext": {
                                    "gdpr": 0,
                                    "us_privacy": "1---"
                                }
                            },
                            "ext": {}
                        }

6.2 Banner Request Example

iOS Banner Bid Request

{
                            "id": "6675c0ace033c70ecb7a48a0",
                            "imp": [
                                {
                                    "id": "1",
                                    "banner": {
                                        "format": [
                                            {
                                                "w": 320,
                                                "h": 50
                                            }
                                        ],
                                        "w": 320,
                                        "h": 50,
                                        "mimes": [
                                            "image/jpg",
                                            "image/gif",
                                            "text/html"
                                        ],
                                        "api": [
                                            5,
                                            7
                                        ],
                                        "id": "1"
                                    },
                                    "displaymanager": "Vungle",
                                    "displaymanagerver": "6.12.1",
                                    "tagid": "PUBLISHER_PLACEMENT_ID",
                                    "bidfloor": 0.1,
                                    "bidfloorcur": "USD",
                                    "secure": 1,
                                    "ext": {
                                        "skadn": {
                                            "version": "3.0",
                                            "versions": [
                                                "2.0",
                                                "2.2",
                                                "3.0"
                                            ],
                                            "sourceapp": "123456789",
                                            "skadnetids": [],
                                            "ext": {
                                                "sko": 0
                                            }
                                        },
                                        "deeplink": 1,
                                        "skpv": 0,
                                        "pcta": 0
                                    }
                                }
                            ],
                            "app": {
                                 "id": "62d8fb315da899193f643165",
                                "name": "Vungle Test App"",
                                "bundle": "123456789",
                                "storeurl": "https://apps.apple.com/us/app/app_store_url",
                                "cat": [
                                    "IAB1",
                                    "IAB9"
                                ],
                                "ver": "70.10.38",
                                "privacypolicy": 1,
                                "publisher": {
                                    "id": "561e8d976b8d90f61a003d96",
                                    "cat": [
                                        "IAB1",
                                        "IAB9"
                                    ]
                                },
                                "keywords": "managed",
                                "ext": {}
                            },
                            "device": {
                                "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 17_5_1 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
                                "geo": {
                                    "type": 2,
                                    "ipservice": 3,
                                    "country": "USA",
                                    "region": "FL",
                                    "city": "Tampa",
                                    "zip": "33614"
                                },
                                "dnt": 1,
                                "lmt": 1,
                                "ip": "199.193.115.73",
                                "devicetype": 4,
                                "make": "Apple",
                                "model": "iPhone",
                                "os": "iOS",
                                "osv": "17.5.1",
                                "hwv": "13",
                                "h": 844,
                                "w": 390,
                                "language": "en",
                                "carrier": "--",
                                "connectiontype": 2,
                                "ifa": "00000000-0000-0000-0000-000000000000",
                                "dpidsha1": "b602d594afd2b0b327e07a06f36ca6a7e42546d0",
                                "ext": {
                                    "idfv": "A8F92314-0B25-47EF-8EAE-4C72B1581A75",
                                    "ifv": "A8F92314-0B25-47EF-8EAE-4C72B1581A75",
                                    "atts": 2
                                }
                            },
                            "user": {},
                            "at": 1,
                            "tmax": 1000,
                            "cur": [
                                "USD"
                            ],
                            "bcat": [
                                "IAB26"
                            ],
                            "badv": [
                            ],
                            "bapp": [
                            ],
                            "source": {
                                "ext": {
                                    "schain": {
                                        "complete": 1,
                                        "nodes": [
                                            {
                                                "asi": "vungle.com",
                                                "sid": "62d8fb315da899193f643165",
                                                "rid": "6675c0ace033c70ecb7a48a0",
                                                "hp": 1
                                            }
                                        ],
                                        "ver": "1.0"
                                    },
                                    "omidpn": "vungle",
                                    "omidpv": "6.12.1"
                                }
                            },
                            "regs": {
                                "ext": {
                                    "gdpr": 0,
                                    "us_privacy": "1-N-"
                                }
                            },
                            "ext": {}
                        }

6.3 MREC Request Examples

iOS MREC Request (Banner and Video Objects)

{
  "id": "6675a52b8b6dcc1ad5c0389d",
  "imp": [
    {
      "id": "1",
      "banner": {
        "format": [
          {
            "w": 300,
            "h": 250
          }
        ],
        "w": 300,
        "h": 250,
        "mimes": [
          "image/jpg",
          "image/gif",
          "text/html"
        ],
        "api": [
          5,
          7
        ],
        "id": "1"
      },
      "video": {
        "mimes": [
          "video/mp4"
        ],
        "minduration": 0,
        "maxduration": 120,
        "protocols": [
          2,
          5,
          3,
          6
        ],
        "w": 300,
        "h": 250,
        "placement": 4,
        "plcmt": 4,
        "linearity": 1,
        "skip": 1,
        "skipafter": 6,
        "minbitrate": 250,
        "maxbitrate": 15000,
        "boxingallowed": 1,
        "playbackmethod": [
          1,
          2,
          3,
          4
        ],
        "delivery": [
          2,
          1
        ],
        "api": [
          7
        ],
        "ext": {}
      },
      "displaymanager": "Vungle",
      "displaymanagerver": "7.3.1",
      "tagid": "PUBLISHER_PLACEMENT_ID",
      "bidfloor": 0.1,
      "bidfloorcur": "USD",
      "secure": 1,
      "ext": {
        "skadn": {
          "version": "2.0",
          "versions": [
            "2.0"
          ],
          "sourceapp": "123456789",
          "skadnetids": [],
          "ext": {
            "sko": 0
          }
        },
        "deeplink": 1,
        "skpv": 0,
        "vxec": 0,
        "pcta": 1
      }
    }
  ],
  "app": {
    "id": "62d8fb315da899193f643165",
    "name": "Vungle Test App",
    "bundle": "123456789",
    "storeurl": "https://apps.apple.com/us/app/app_store_url",
    "cat": [
      "IAB1",
      "IAB9"
    ],
    "ver": "1",
    "privacypolicy": 1,
    "publisher": {
      "id": "56e0de2215a62b831800002b",
      "cat": [
        "IAB1",
        "IAB9"
      ]
    },
    "keywords": "managed",
    "ext": {}
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "geo": {
      "lat": 28.0109,
      "lon": -82.4948,
      "type": 2,
      "ipservice": 3,
      "country": "USA",
      "region": "FL",
      "city": "Tampa",
      "zip": "33614"
    },
    "dnt": 0,
    "lmt": 0,
    "ip": "199.193.115.73",
    "devicetype": 4,
    "make": "Apple",
    "model": "iPhone",
    "os": "iOS",
    "osv": "13.4",
    "h": 2688,
    "w": 1242,
    "language": "en",
    "connectiontype": 2,
    "ifa": "00000000-0000-0000-0000-000000000000",
    "dpidsha1": "b602d594afd2b0b327e07a06f36ca6a7e42546d0",
    "ext": {
      "idfv": "25336879-2A81-4E49-818D-CAE28C2A97BB",
      "ifv": "25336879-2A81-4E49-818D-CAE28C2A97BB",
      "atts": 0
    }
  },
  "user": {},
  "at": 1,
  "tmax": 1000,
  "cur": [
    "USD"
  ],
  "bcat": [
    "IAB23"
  ],
  "badv": [],
  "bapp": [],
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "nodes": [
          {
            "asi": "vungle.com",
            "sid": "56e0de2215a62b831800002b",
            "rid": "6675a52b8b6dcc1ad5c0389d",
            "hp": 1
          }
        ],
        "ver": "1.0"
      },
      "omidpn": "vungle",
      "omidpv": "6.12.1"
    }
  },
  "regs": {
    "ext": {
      "gdpr": 0,
      "us_privacy": "1---"
    }
  },
  "ext": {}
}

iOS Static MREC Request (Banner Object Only)

{
  "id": "6675a52b8b6dcc1ad5c0389d",
  "imp": [
    {
      "id": "1",
      "banner": {
        "format": [
          {
            "w": 300,
            "h": 250
          }
        ],
        "w": 300,
        "h": 250,
        "mimes": [
          "image/jpg",
          "image/gif",
          "text/html"
        ],
        "api": [
          5,
          7
        ],
        "id": "1"
      },
      "displaymanager": "Vungle",
      "displaymanagerver": "6.12.1",
      "tagid": "PUBLISHER_PLACEMENT_ID",
      "bidfloor": 0.1,
      "bidfloorcur": "USD",
      "secure": 1,
      "ext": {
        "skadn": {
          "version": "2.0",
          "versions": [
            "2.0"
          ],
          "sourceapp": "123456789",
          "skadnetids": [],
          "ext": {
            "sko": 0
          }
        },
        "deeplink": 1,
        "skpv": 0,
        "pcta": 1
      }
    }
  ],
  "app": {
    "id": "62d8fb315da899193f643165",
    "name": "Vungle Test App",
    "bundle": "123456789",
    "storeurl": "https://apps.apple.com/us/app/app_store_url",
    "cat": [
      "IAB1",
      "IAB9"
    ],
    "ver": "1",
    "privacypolicy": 1,
    "publisher": {
      "id": "56e0de2215a62b831800002b",
      "cat": [
        "IAB1",
        "IAB9"
      ]
    },
    "keywords": "ios_content-12+,managed",
    "ext": {}
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "geo": {
      "lat": 28.0109,
      "lon": -82.4948,
      "type": 2,
      "ipservice": 3,
      "country": "USA",
      "region": "FL",
      "city": "Tampa",
      "zip": "33614"
    },
    "dnt": 0,
    "lmt": 0,
    "ip": "199.193.115.73",
    "devicetype": 4,
    "make": "Apple",
    "model": "iPhone",
    "os": "iOS",
    "osv": "13.4",
    "h": 2688,
    "w": 1242,
    "language": "en",
    "connectiontype": 2,
    "ifa": "00000000-0000-0000-0000-000000000000",
    "dpidsha1": "b602d594afd2b0b327e07a06f36ca6a7e42546d0",
    "ext": {
      "atts": 0
    }
  },
  "user": {},
  "at": 1,
  "tmax": 980,
  "cur": [
    "USD"
  ],
  "bcat": [
    "IAB26"
  ],
  "badv": [],
  "bapp": [],
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "nodes": [
          {
            "asi": "vungle.com",
            "sid": "56e0de2215a62b831800002b",
            "rid": "6675a52b8b6dcc1ad5c0389d",
            "hp": 1
          }
        ],
        "ver": "1.0"
      },
      "omidpn": "vungle",
      "omidpv": "6.12.1"
    }
  },
  "regs": {
    "ext": {
      "gdpr": 0,
      "us_privacy": "1---"
    }
  },
  "ext": {}
}

iOS Video MREC Request (Video Object Only)

{
  "id": "6675a52b8b6dcc1ad5c0389d",
  "imp": [
    {
      "id": "1",
      "video": {
        "mimes": [
          "video/mp4"
        ],
        "minduration": 0,
        "maxduration": 120,
        "protocols": [
          2,
          5,
          3,
          6
        ],
        "w": 300,
        "h": 250,
        "placement": 4,
        "plcmt": 4,
        "linearity": 1,
        "skip": 1,
        "skipafter": 6,
        "minbitrate": 250,
        "maxbitrate": 15000,
        "boxingallowed": 1,
        "playbackmethod": [
          1,
          2,
          3,
          4
        ],
        "delivery": [
          2,
          1
        ],
        "api": [
          7
        ],
        "ext": {}
      },
      "displaymanager": "Vungle",
      "displaymanagerver": "7.3.1",
      "tagid": "PUBLISHER_PLACEMENT_ID",
      "bidfloor": 0.1,
      "bidfloorcur": "USD",
      "secure": 1,
      "ext": {
        "skadn": {
          "version": "2.0",
          "versions": [
            "2.0"
          ],
          "sourceapp": "123456789",
          "skadnetids": [],
          "ext": {
            "sko": 0
          }
        },
        "deeplink": 1,
        "skpv": 0,
        "vxec": 0,
        "pcta": 1
      }
    }
  ],
  "app": {
    "id": "62d8fb315da899193f643165",
    "name": "Vungle Test App",
    "bundle": "123456789",
    "storeurl": "https://apps.apple.com/us/app/app_store_url",
    "cat": [
      "IAB1",
      "IAB9"
    ],
    "ver": "1",
    "privacypolicy": 1,
    "publisher": {
      "id": "56e0de2215a62b831800002b",
      "cat": [
        "IAB1",
        "IAB9"
      ]
    },
    "keywords": "ios_content-12+,managed",
    "ext": {}
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "geo": {
      "lat": 28.0109,
      "lon": -82.4948,
      "type": 2,
      "ipservice": 3,
      "country": "USA",
      "region": "FL",
      "city": "Tampa",
      "zip": "33614"
    },
    "dnt": 0,
    "lmt": 0,
    "ip": "199.193.115.73",
    "devicetype": 4,
    "make": "Apple",
    "model": "iPhone",
    "os": "iOS",
    "osv": "13.4",
    "h": 2688,
    "w": 1242,
    "language": "en",
    "connectiontype": 2,
    "ifa": "00000000-0000-0000-0000-000000000000",
    "dpidsha1": "b602d594afd2b0b327e07a06f36ca6a7e42546d0",
    "ext": {
      "idfv": "25336879-2A81-4E49-818D-CAE28C2A97BB",
      "ifv": "25336879-2A81-4E49-818D-CAE28C2A97BB",
      "atts": 0
    }
  },
  "user": {},
  "at": 1,
  "tmax": 1000,
  "cur": [
    "USD"
  ],
  "bcat": [
    "IAB26"
  ],
  "badv": [],
  "bapp": [],
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "nodes": [
          {
            "asi": "vungle.com",
            "sid": "56e0de2215a62b831800002b",
            "rid": "6675a52b8b6dcc1ad5c0389d",
            "hp": 1
          }
        ],
        "ver": "1.0"
      },
      "omidpn": "vungle",
      "omidpv": "7.3.1"
    }
  },
  "regs": {
    "ext": {
      "gdpr": 0,
      "us_privacy": "1---"
    }
  },
  "ext": {}
}

6.4 Rewarded Bid Request Example

iOS Rewarded Video (Banner + Video Object)

{
  "id": "6675b2d59676f96c680cbd8a",
  "imp": [
    {
      "id": "1",
      "banner": {
        "format": [
          {
            "w": 320,
            "h": 480
          }
        ],
        "w": 320,
        "h": 480,
        "pos": 7,
        "mimes": [
          "image/jpg",
          "image/gif",
          "text/html"
        ],
        "api": [
          5,
          7
        ],
        "id": "1",
        "vcm": 1,
        "ext": {
          "rewarded": 1
        }
      },
      "video": {
        "mimes": [
          "video/mp4"
        ],
        "minduration": 0,
        "maxduration": 120,
        "protocols": [
          2,
          5,
          3,
          6
        ],
        "w": 320,
        "h": 480,
        "placement": 5,
        "plcmt": 3,
        "linearity": 1,
        "skip": 1,
        "skipafter": 30,
        "minbitrate": 250,
        "maxbitrate": 15000,
        "boxingallowed": 1,
        "playbackmethod": [
          1,
          2,
          3,
          4
        ],
        "delivery": [
          2,
          1
        ],
        "pos": 7,
        "companionad": [
          {
            "format": [
              {
                "w": 320,
                "h": 480
              }
            ],
            "w": 320,
            "h": 480,
            "pos": 7,
            "api": [
              5
            ],
            "id": "6675b2d59676f96c680cbd8a",
            "vcm": 1
          }
        ],
        "api": [
          7
        ],
        "companiontype": [
          1,
          2
        ],
        "ext": {
          "skip": 1,
          "videotype": "rewarded",
          "rewarded": 1
        }
      },
      "displaymanager": "Vungle",
      "displaymanagerver": "6.12.1",
      "instl": 1,
      "tagid": "PUBLISHER_PLACEMENT_ID",
      "bidfloor": 4,
      "bidfloorcur": "USD",
      "secure": 1,
      "ext": {
        "skadn": {
          "version": "2.0",
          "versions": [
            "2.0"
          ],
          "sourceapp": "123456789",
          "skadnetids": [],
          "ext": {
            "sko": 1
          }
        },
        "deeplink": 1,
        "skpv": 1,
        "vxec": 0,
        "pcta": 1
      }
    }
  ],
  "app": {
    "id": "62d8fb315da899193f643165",
    "name": "Vungle Test App",
    "bundle": "123456789",
    "storeurl": "https://apps.apple.com/us/app/app_store_url",
    "cat": [
      "IAB1",
      "IAB9"
    ],
    "ver": "1",
    "privacypolicy": 1,
    "publisher": {
      "id": "56e0de2215a62b831800002b",
      "cat": [
        "IAB1",
        "IAB9"
      ]
    },
    "keywords": "12+,managed",
    "ext": {}
  },
  "device": {
    "ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 13_4 like Mac OS X) AppleWebKit/605.1.15 (KHTML, like Gecko) Mobile/15E148",
    "geo": {
      "lat": 28.0109,
      "lon": -82.4948,
      "type": 2,
      "ipservice": 3,
      "country": "USA",
      "region": "FL",
      "city": "Tampa",
      "zip": "33614"
    },
    "dnt": 0,
    "lmt": 0,
    "ip": "199.193.115.73",
    "devicetype": 4,
    "make": "Apple",
    "model": "iPhone",
    "os": "iOS",
    "osv": "13.4",
    "h": 2688,
    "w": 1242,
    "language": "en",
    "connectiontype": 2,
    "ifa": "00000000-0000-0000-0000-000000000000",
    "dpidsha1": "b602d594afd2b0b327e07a06f36ca6a7e42546d0",
    "ext": {
      "atts": 0
    }
  },
  "user": {},
  "at": 1,
  "tmax": 1000,
  "cur": [
    "USD"
  ],
  "bcat": [
    "IAB26"
  ],
  "badv": [],
  "bapp": [],
  "source": {
    "ext": {
      "schain": {
        "complete": 1,
        "nodes": [
          {
            "asi": "vungle.com",
            "sid": "56e0de2215a62b831800002b",
            "rid": "6675b2d59676f96c680cbd8a",
            "hp": 1
          }
        ],
        "ver": "1.0"
      },
      "omidpn": "vungle",
      "omidpv": "6.12.1"
    }
  },
  "regs": {
    "ext": {
      "gdpr": 0,
      "us_privacy": "1---"
    }
  },
  "ext": {}
}

7. Response Examples

7.1 Standard 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": "<VAST version=\"2.0\"><Ad><InLine><AdTitle>YOUR_AD_NAME</AdTitle><Impression><![CDATA[https://YOUR_IMPRESSION_TRACKING_URL?ttdsp_price=${AUCTION_PRICE}]]></Impression><Creatives><Creative id=\"YOUR_CREATIVE_ID\"><Linear><Duration>00:00:18</Duration><TrackingEvents><Tracking event=\"start\"><![CDATA[https://YOUR_IMPRESSION_TRACKING_URL_START_PLAY]]></Tracking><Tracking event=\"complete\"><![CDATA[https://YOUR_IMPRESSION_TRACKING_URL_START_COMPLETE]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[https://YOUR_DESTINATION_URL_TO_DOWNLOAD_BY_CLICK]]></ClickThrough><ClickTracking><![CDATA[https://YOUR_CLICK_TRACKING_URL]]></ClickTracking></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"1280\" height=\"720\"> <![CDATA[https://YOUR_AD_VIDEO.mp4]]></MediaFile></MediaFiles></Linear></Creative></Creatives><Description>Longer description of ad</Description></InLine></Ad></VAST>",
          "adomain": "advertiserdomain.com"
          "bundle": "bundleid"          
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

7.2 Video With Playable Endcard 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": "<VAST version=\"2.0\"><Ad><InLine><AdTitle>YOUR_AD_NAME</AdTitle><Impression><![CDATA[https://YOUR_IMPRESSION_TRACKING_URL?ttdsp_price=${AUCTION_PRICE}]]></Impression><Creatives><Creative id=\"YOUR_CREATIVE_ID\"><Linear><Duration>00:00:18</Duration><TrackingEvents><Tracking event=\"start\"><![CDATA[https://YOUR_IMPRESSION_TRACKING_URL_START_PLAY]]></Tracking><Tracking event=\"complete\"><![CDATA[https://YOUR_IMPRESSION_TRACKING_URL_START_COMPLETE]]></Tracking></TrackingEvents><VideoClicks><ClickThrough><![CDATA[https://YOUR_DESTINATION_URL_TO_DOWNLOAD_BY_CLICK]]></ClickThrough><ClickTracking><![CDATA[https://YOUR_CLICK_TRACKING_URL]]></ClickTracking></VideoClicks><MediaFiles><MediaFile delivery=\"progressive\" type=\"video/mp4\" width=\"1280\" height=\"720\"><![CDATA[https://YOUR_AD_VIDEO.mp4]]></MediaFile></MediaFiles></Linear></Creative><Creative><CompanionAds><Companion><HTMLResource><![CDATA[<div>Your end card content</div> // Content can not be empty <script src="></script>]]></HTMLResource><TrackingEvents><Tracking event='creativeView'>< ![CDATA[https://endcard_tracking]]> // Required </Tracking></TrackingEvents></Companion></CompanionAds></Creative></Creatives><Description>Longer description of ad</Description></InLine></Ad></VAST>",
          "adomain": "advertiserdomain.com",
          "attr": [
        13
      ],
          "bundle": "bundleid",
          "cid": "554d550b418461cc3700014d",
          "crid": "57767c29a63510e75f000073"
        }
      ]
    }
  ]
}

7.3 MRAID Playable Example

{
  "id": "614abfbfc92e1f61f41c712c",
  "seatbid": [
    {
      "bid": [
        {
          "id": "8",
          "impid": "1",
          "price": 98,
          "nurl": "http://kraken-ext1-apiqa-kraken.apiqa.svc.cluster.local:7700/win?price=${AUCTION_PRICE}",
          "burl": "http://kraken-apiqa-kraken.apiqa.svc.cluster.local:7700/win?aid=kraken-test-aid&impid=kraken-test-impid&price=100.001",
          "lurl": "http://kraken-qa1-apiqa-kraken.apiqa.svc.cluster.local:7700/lurl",
          "adm": "",
          "adomain": [
            "domain1.com"
          ],
          "bundle": "bundleid",
          "cat": [
            "Movies",
            "Music"
          ],
          "api": 7,
          "ext": {
            "skadn": {
              "version": "2.0",
              "network": "cDkw7geQsH.skadnetwork",
              "campaign": "45",
              "itunesitem": "880047117",
              "nonce": "473b1a16-b4ef-43ad-9591-fcf3aefa82a7",
              "sourceapp": "123456789",
              "timestamp": "1594406341",
              "signature": "MEQCIEQlmZRNfYzK",
              "ext": {}
            },
            "deeplink": "zalora://my//seg_s/m/",
            "imptrackers": [
              "https://us-event.app-install.bid/rtb/impr?id=123",
              "https://us-event.app-install.bid/rtb/impr?id=YnRyAgMAAAF6dACeAwAGRREAAAAwHZlv1LjyQ6eKNFvVILh75gACdXMB&price=${AUCTION_PRICE}"
            ],
            "crtype": "MRAID 2.0"
          }
        }
      ]
    }
  ],
  "bidid": "8",
  "cur": "USD"
}

Questions?

Need further assistance, feel free to reach out to us, we’re here to help!

Submit a request
Was this article helpful?