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 | 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 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; 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 IAB OpenRTB API Specification Version 2.5, List 5.1 "Content Categories." |
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.1 Source.ext.schain Object
Field | Type | Required | 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 Source.ext.schain.nodes Object
Field | Type | Required | 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'. |
3.2.3 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. See Regs Extension. |
3.2.3.1 Regs Extension
Field | Type | Required | 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 | 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. |
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 | 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). |
secure |
integer | no |
Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure and 1 = secure. Vungle always requires secure (1) assets and markup. |
ext |
object | no |
3.2.4.1 Imp Extension
Field | Type | Required | Description |
---|---|---|---|
metric.type |
string | no | Denotes app is enabled for viewability. |
metric.vendor |
string | no |
Denotes viewability vendor. Vungle currently is integrated with Moat. |
skadn |
object | no |
Support for Apple's SKAdNetwork. |
deeplink |
Boolean | no |
Indicates whether deep linking is supported for this impression. Refer to our Deep Linking article for details. |
3.2.4.1.1 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 |
skadnetids |
string array | yes |
A subset of |
ext |
object | no |
Placeholder for exchange-specific extensions to OpenRTB. |
3.2.6 Banner Object
Field | Type | Required | Description |
---|---|---|---|
format |
object array | no | Content MIME types supported. Vungle Exchange only supports ["video/mp4"]. |
w |
integer | yes | Width of the impression in pixels. |
h |
integer | yes | Height of the impression in pixels. |
battr |
integer array | no | Refer to IAB OpenRTB API Specification Version 2.5, List 5.3 "Creative Attributes" for details. |
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 IAB OpenRTB API Specification Version 2.5, List 5.6 "API Frameworks" for details. |
3.2.7 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 IAB OpenRTB API Specification Version 2.5, Section 5.15 "Content Delivery Methods." |
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 IAB OpenRTB API Specification Version 2.5, List 5.8 "Protocols"; for example, [2, 5]. |
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 IAB OpenRTB API Specification Version 2.5, Section 5.10 "Playback Methods." |
startdelay |
integer | no | Refer to IAB OpenRTB API Specification Version 2.5, Section 5.12 "Start Delay." The value for this is always '0'. |
skipafter |
integer | no | Number of seconds a video must play before skipping is enabled; only applicable if the ad is skippable. |
3.2.7.1 Video Extension
Field | Type | Required | Description |
---|---|---|---|
skip |
boolean | yes | Denotes skippable (1) or non-skippable (0) inventory. |
videotype |
string | yes | Used to specify rewarded inventory. If not rewarded, we omit this field. |
rewarded |
boolean | yes | Additional field to denote rewarded (1) or non-rewarded (0) inventory. |
3.2.9 Native Object
Field | Type | Required | Description |
---|---|---|---|
api |
integer | no | List of supported API frameworks for this impression. |
request |
string | yes | Request payload compliant with Native Ad specification (refer to Vungle OpenRTB 2.5 Native Ad Integration for variables, definitions, and extensions). |
battr |
integer array | yes | Refer to IAB OpenRTB API Specification Version 2.5, List 5.3 "Creative Attributes" for details. |
Refer to Vungle OpenRTB 2.5 Native Ad Integration for variables, definitions, and extensions.
3.2.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.2.14 App Object
Field | Type | Required | 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 | 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 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. |
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 |
3.2.15 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 IAB OpenRTB API Specification Version 2.5, List 5.1 "Content Categories." |
3.2.18 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 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'. |
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'. |
ext |
object | no | See the Device Extension object. |
3.2.19 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 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. |
3.2.20 User Object
Field | Type | Required | Description |
---|---|---|---|
ext |
object | no | See the User Extension object. |
3.2.20.1 User Extension
Field | Type | Required | 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 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.5 section 7.4 specification. A well formed no-bid signaling with the no-bid reason should look like this:
{"id": "1234567890", "seatbid": [], "nbr": 2}
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 | 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.24 of the OpenRTB 2.5 spec. |
ext |
object | no |
4.2.2 SeatBid Object
Field | Type | Required | Description |
---|---|---|---|
seat |
string | no | 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 | yes | 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 | no | Billing notice URL called by Vungle Exchange if the bid wins. |
lurl |
string | no | 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. - 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 IAB OpenRTB API Specification Version 2.5, Section 5.1 "Content Categories." |
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.2.3.1 Bid Extension
Field | Type | Required | Description |
---|---|---|---|
skadn |
object | no | Parameters required to support Apple's SKAdNetwork attribution API, via loadProduct() . |
Impression tracker |
string array; one of imptrackers or burl required |
no | |
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. |
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 of the Bid object in the bid response. For example:
"nurl": "http://bidder.com/won?price=${AUCTION_PRICE}"
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+.
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 |
skadnetids |
string array | yes |
A subset of |
ext |
object | no |
Placeholder for exchange-specific extensions to OpenRTB. |
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 skadnetids array in the request. |
campaign |
string | yes | Campaign ID compatible with Apple’s spec. As of 2.0, this should be an integer between 1 and 100, expressed as a string. |
fidelities |
object array | yes | |
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 |
4.4.2.1. Ext.skadn.fidelities
Field | Type | Required | Description |
---|---|---|---|
fidelities |
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 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" } }
5. Examples
5.1 Request Example
{
"id": "5f0417f6354b680001e94518",
"imp": [
{
"id": "1",
"video": {
"mimes": [
"video/mp4"
],
"minduration": 0,
"maxduration": 46,
"protocols": [
2,
5
],
"w": 720,
"h": 1422,
"linearity": 1,
"minbitrate": 250,
"maxbitrate": 15000,
"boxingallowed": 1,
"playbackmethod": [
1,
2,
3,
4
],
"delivery": [
2,
1
],
"pos": 7,
"ext": {
"skip": 0,
"videotype": "rewarded",
"rewarded": 1
}
},
"pmp": {
"private_auction": 0,
"deals": [
{
"id": "5e463ac3413fc600161ca063",
"bidfloor": 2.5,
"bidfloorcur": "USD",
"at": 2
},
{
"id": "5e539622ecaffc0016745c14",
"bidfloor": 2.5,
"bidfloorcur": "USD",
"at": 2
}
]
},
"displaymanager": "VungleDroid",
"displaymanagerver": "6.4.11",
"tagid": "RW_12-7662426",
"bidfloor": 1,
"bidfloorcur": "USD",
"secure": 1,
"ext": {
"openrtb25x": {
"skip": 0
},
"metric": [
{
"type": "viewability",
"vendor": "moat"
}
]
}
}
],
"app": {
"id": "5afa947e9c8119360fba1bea",
"name": "VungleApp123",
"bundle": "com.vungle.bundle",
"storeurl": "https:play.google.com/store/apps/details?id=com.vungle.bundle",
"cat": [
"IAB1",
"IAB9",
"IAB25-7"
],
"privacypolicy": 1,
"publisher": {
"id": "5a9f8641bacdc27c1e009703",
"cat": [
"IAB1",
"IAB9"
]
},
"keywords": "managed",
"sdk": {
"name": "VungleDroid",
"ver": "6.4.11"
},
"bundleid": "com.vungle.bundle",
"accountid": "5a9f8641bacdc27c1e005620"
},
"device": {
"ua": "Mozilla/5.0 (Linux; Android 9; SM-A207F Build/PPR1.180610.011; wv) AppleWebKit/537.36 KHTML, like Gecko) Version/4.0 Chrome/74.0.3729.136 Mobile Safari/537.36",
"geo": {
"lat": -7.2484,
"lon": 112.7419,
"type": 2,
"ipservice": 3,
"country": "IDN",
"region": "JI",
"city": "Surabaya"
},
"dnt": 0,
"lmt": 0,
"ip": "115.178.227.128",
"devicetype": 1,
"make": "samsung",
"model": "SM-A207F",
"os": "android",
"osv": "9",
"h": 1422,
"w": 720,
"language": "id",
"carrier": "Smartfren - Stay Safe | Smartfren",
"connectiontype": 3,
"ifa": "5ef57c14-d642-447f-ace9-543262c458bc",
"ext": {
"vungle": {
"isSdCardAvailable": 1,
"vungleua": "VungleDroid/6.4.11",
"timezone": "Asia/Jakarta",
"tz": "Asia/Jakarta",
"sdcard": 1,
"volume": 0.53333336,
"muted": 1,
"is_sideload_enabled": 0,
"id": "5ef57c14-d642-447f-ace9-543262c458bc",
"id_source": "IFA",
"marketplace": "google"
}
}
},
"user": {
"ext": {
"consent": 1
}
},
"at": 2,
"tmax": 1000,
"cur": [
"USD"
],
"bcat": [
"IAB7-3",
"IAB7-5",
"IAB7-28",
"IAB7-29",
"IAB7-30",
"IAB7-39",
"IAB7-41",
"IAB7-42",
"IAB7-44",
"IAB8-5",
"IAB8-18",
"IAB9-9",
"IAB11",
"IAB14-1",
"IAB14-2",
"IAB14-3",
"IAB14-4",
"IAB14-8",
"IAB18-2",
"IAB23",
"IAB25-1",
"IAB25-2",
"IAB25-3",
"IAB25-4",
"IAB25-5",
"IAB25-6",
"IAB26"
],
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "vungle.com",
"sid": "5a9f8641bacdc27c1e009703",
"rid": "5f0417f6354b680001e94518",
"hp": 1
}
],
"ver": "1.0"
}
}
},
"regs": {
"ext": {
"gdpr": 0,
"us_privacy": "1---"
}
},
"ext": {
"schain": {
"complete": 1,
"nodes": [
{
"asi": "vungle.com",
"sid": "5a9f8641bacdc27c1e009703",
"rid": "5f0417f6354b680001e94518",
"hp": 1
}
],
"ver": "1.0"
},
"moat_sdk": 1
}
}
5.2 Banner Request Example
{
"id": "5f63efce8fbdc346eff7bc4c",
"imp": [{
"id": "1",
"banner": {
"format": [{
"w": 320,
"h": 50
}],
"w": 320,
"h": 50,
"api": [
5
]
},
"displaymanager": "VungleDroid",
"displaymanagerver": "6.7.0",
"instl": 1,
"tagid": "MYFILE_VIDEO1_BANNER-0401902",
"bidfloor": 0.15,
"bidfloorcur": "USD",
"secure": 1,
"ext": {
"openrtb25x": {
"skip": 1
},
"metric": [{
"type": "viewability",
"vendor": "moat"
}],
"skadn": {
"version": "2.0",
"sourceapp": "com.dywx.larkplayer",
"skadnetids": []
}
}
}],
"app": {
"id": "575d1cfa8eee0c91140000be",
"name": "Snaptube",
"bundle": "com.dywx.larkplayer",
"storeurl": "https://play.google.com/store/apps/details?id=com.dywx.larkplayer",
"cat": ["IAB1", "IAB9"],
"privacypolicy": 1,
"publisher": {
"id": "575d1c861295e1447c0000e5",
"cat": ["IAB1", "IAB9"]
},
"keywords": "managed",
"ext": {}
},
"device": {
"ua": "Mozilla/5.0 (Linux; Android 10; SM-A205G Build/QP1A.190711.020; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/85.0.4183.101 Mobile Safari/537.36",
"geo": {
"lat": -29.7,
"lon": -53.75,
"type": 2,
"ipservice": 3,
"country": "BRA",
"region": "RS",
"city": "Sao Jose",
"zip": "95280"
},
"dnt": 0,
"lmt": 0,
"ip": "45.168.96.10",
"devicetype": 1,
"make": "samsung",
"model": "SM-A205G",
"os": "android",
"osv": "10",
"h": 1423,
"w": 720,
"language": "pt",
"carrier": "Vivo",
"connectiontype": 2,
"ifa": "bbfb54b9-8530-443f-b772-15d23886b379",
"ext": {}
},
"user": {
"ext": {
"consent": 1
}
},
"at": 2,
"tmax": 1000,
"cur": ["USD"],
"bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42", "IAB7-44", "IAB8-5", "IAB8-18", "IAB9-9", "IAB11", "IAB14-1", "IAB14-2", "IAB14-3", "IAB14-4", "IAB14-8", "IAB18-2", "IAB23", "IAB25-1", "IAB25-2", "IAB25-3", "IAB25-4", "IAB25-5", "IAB25-6", "IAB26"],
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [{
"asi": "vungle.com",
"sid": "575d1c861295e1447c0000e5",
"rid": "5f63efce8fbdc346eff7bc4c",
"name": "snaptube",
"hp": 1
}],
"ver": "1.0"
}
}
},
"regs": {
"ext": {
"gdpr": 0,
"us_privacy": "1-N-"
}
},
"ext": {
"schain": {
"complete": 1,
"nodes": [{
"asi": "vungle.com",
"sid": "575d1c861295e1447c0000e5",
"rid": "5f63efce8fbdc346eff7bc4c",
"name": "snaptube",
"hp": 1
}],
"ver": "1.0"
},
"moat_sdk": 1
}
}
5.3 MREC Request Example
{
"id": "5f63f075520d3be1ebedea2a",
"imp": [{
"id": "1",
"banner": {
"format": [{
"w": 300,
"h": 250
}],
"w": 300,
"h": 50,
"api": [
5
]
},
"pmp": {
"private_auction": 0,
"deals": [{
"id": "5a396a79d6515f3e2500726e",
"bidfloor": 3,
"bidfloorcur": "USD",
"at": 2
}, {
"id": "5a396ae2d6515f3e2500726f",
"bidfloor": 5,
"bidfloorcur": "USD",
"at": 2
}]
},
"displaymanager": "VungleDroid",
"displaymanagerver": "6.5.3",
"instl": 1,
"tagid": "MRECLOW-6155659",
"bidfloor": 0.1754385964912281,
"bidfloorcur": "USD",
"secure": 1,
"ext": {
"openrtb25x": {
"skip": 1
},
"metric": [{
"type": "viewability",
"vendor": "moat"
}],
"impType": "MREC",
"skadn": {
"version": "2.0",
"sourceapp": "wp.wattpad",
"skadnetids": []
}
}
}],
"app": {
"id": "56b8e577819502560b000033",
"name": "Wattpad Futures - android",
"bundle": "wp.wattpad",
"storeurl": "https://play.google.com/store/apps/details?id=wp.wattpad&hl=en",
"cat": ["IAB1", "IAB9"],
"privacypolicy": 1,
"publisher": {
"id": "56b2844d24342c3622000032",
"cat": ["IAB1", "IAB9"]
},
"keywords": "managed",
"ext": {}
},
"device": {
"ua": "Mozilla/5.0 (Linux; Android 10; HRY-LX1T Build/HONORHRY-LX1T; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/85.0.4183.81 Mobile Safari/537.36",
"geo": {
"type": 2,
"ipservice": 3,
"country": "FIN",
"region": "11",
"city": "Tampere",
"zip": "33200"
},
"dnt": 0,
"lmt": 0,
"ip": "109.240.199.0",
"devicetype": 1,
"make": "HUAWEI",
"model": "HRY-LX1T",
"os": "android",
"osv": "10",
"h": 2139,
"w": 1080,
"language": "en",
"carrier": "Telia FI",
"connectiontype": 3,
"ext": {}
},
"user": {
"ext": {}
},
"at": 2,
"tmax": 1000,
"cur": ["USD"],
"bcat": ["IAB7-3", "IAB7-5", "IAB7-28", "IAB7-29", "IAB7-30", "IAB7-39", "IAB7-41", "IAB7-42", "IAB7-44", "IAB8-5", "IAB8-18", "IAB9-9", "IAB11", "IAB14-1", "IAB14-2", "IAB14-3", "IAB14-4", "IAB14-8", "IAB18-2", "IAB23", "IAB25-1", "IAB25-2", "IAB25-3", "IAB25-4", "IAB25-5", "IAB25-6", "IAB26"],
"source": {
"ext": {
"schain": {
"complete": 1,
"nodes": [{
"asi": "vungle.com",
"sid": "56b2844d24342c3622000032",
"rid": "5f63f075520d3be1ebedea2a",
"hp": 1
}],
"ver": "1.0"
}
}
},
"regs": {
"ext": {
"gdpr": 1,
"us_privacy": "1---"
}
},
"ext": {
"schain": {
"complete": 1,
"nodes": [{
"asi": "vungle.com",
"sid": "56b2844d24342c3622000032",
"rid": "5f63f075520d3be1ebedea2a",
"hp": 1
}],
"ver": "1.0"
},
"moat_sdk": 1
}
}
5.4 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>",
"cid": "554d550b418461cc3700014d",
"crid": "57767c29a63510e75f000073"
}
]
}
]
}