Enable demand partners to interpret and respond to auction signals effectively.
Read time 13 minutesLast updated 19 days ago
When Unity receives an ad request, the SDK sends a bid request to all potential bidders, including data used for personalized ads in cases where the user does not restrict its use (refer to the documentation on data privacy).Unity supports JSON formats for bid request data. The mime type for the standard JSON representation is
Unity sends Accept-Encoding GZIP compression in the request, and highly recommends compressing the response. For more information, refer to section 2.4 of the OpenRTB specification.
Important
Your endpoint must support
HTTPS
protocol to receive bid requests.
Note
Unity passes each of the following bid request attributes when available, unless otherwise noted in the description column.
request objects
The top-level bid request object contains a globally unique ID for the ad request.
A private marketplace container for direct deals between buyers and sellers that might pertain to the impression. The actual deals are represented as a collection of
An object that provides data about the inventory source, and which entity makes the final decision.
regs
object
For more information, refer to the documentation on data privacy.
An object that specifies any industry, legal, or governmental regulations enforced for this request.
source objects
An object class that describes the nature and behavior of the entity that is the source of the bid request upstream from the exchange. The primary purpose of this object is to define post-auction or upstream decision-making when the exchange itself does not control the final decision. For more information, refer to the Object: source section of the OpenRTB guidelines.
An identifier for the Open Measurement SDK integration. This is the same as the
name
parameter of the OMID Partner object.
omidpv
string
"omidpv": "1.3.0"
The version of the Open Measurement SDK integration. This is the same as the
versionString
parameter of the OMID Partner object.
schain
object
For more information, refer to the section on schain objects.
This object represents both the links in the supply chain and an indicator for whether the supply chain is complete.
source.ext.header_bidding
int
"header_bidding": 0
Indicates the auction type, where 1=Bidding, 0=Waterfall.
source.ext.fd
int
"fd": 0
Entity responsible for the final impression sale decision, where 0 = exchange, 1 = upstream source.
schain objects
This object represents both the links in the supply chain and an indicator for whether the supply chain is complete.
Attribute
Type
Example
Description
complete
int
"complete": 1
A 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.
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 (such as 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
"ver": "1.0"
Version of the supply chain specification in use, in the format of
"major.minor"
.
nodes objects
An object that represents an entity involved in the transaction supply chain.
Attribute
Type
Example
Description
asi
string
"asi":"unity.com"
The domain name of the system that bidders connect to. This might be the operational domain of the system, if that is different from the parent corporate domain. This should be the same value as used to identify sellers in an
app-ads.txt
file if one exists.
sid
string
"sid":"1596090"
The ID associated with the seller or reseller account within the advertising system. This must contain the same value used in OpenRTB transactions. This is typically
An object that describes a banner display impression.
Note
Unity only passes this attribute for banner and display ads.
bidfloor
float
"bidfloor": 3.95
The minimum CPM bid required to win this impression. Expressed in USD.
displaymanager
string
"displaymanager": "unity sdk"
The name of the ad mediation partner, SDK technology, or player responsible for rendering the ad.
displaymanagerver
string
4001
The version of the ad mediation partner, SDK technology, or player responsible for rendering the ad.
id
string
"id": "1"
Unity supports one
imp
object per bid request, so the
id
value is always
1
.
instl
int
"instl": 1
Banner ad requests have a value of
0
; all other placements are interstitials, with a value of
1
.
secure
int
"secure": 1
Unity requires impressions to have secure
HTTPS URL
creative assets and markup; the value is always
1
.
tagid
string
"tagid": "com.this.game-video"
Unity passes
<appID>-<adType>
as the identifier.
video
object
For more information, refer to the section on video objects.
An object that describes a video impression.
Note
Unity always passes this attribute for video ads.
ext.skadn
object
For more information, refer to the documentation on iOS 14 support.
If a DSP has at least one
SKAdNetworkItem
in the publisher app's
Info.plist
file, Unity will include this object in the bid request. This provides the information required to create a signature.
ext.skadn.skoverlay
Integer
1
Indicates eligibility for SKOverlay feature.
1
indicates imp is eligible for showing SKOverlay.
0
indicates imp is not eligible for showing SKOverlay.
ext.skadn.productpage
Integer
1
Indicates eligibility for Custom Product Page feature.
1
indicates imp is eligible for showing Custom Product Page.
0
indicates imp is not eligible for showing Custom Product Page.
ext.skadn.ext.ask
Integer
1
Indicates eligibility for Auto Storekit feature.
1
indicates imp is eligible for showing Auto Storekit.
0
indicates imp is not eligible for showing Auto Storekit.
video objects
A subset of the
impression
object class that describes a video ad impression. For more information, refer to section 3.2.7 in the OpenRTB specification.
Attribute
Type
Example
Description
api
int array
"api": [7]
The supported API frameworks for this impression. A value of
7
signifies Open Measurement support. For more information, refer to the documentation on OM extensions.
battr
int array
"battr": [ 1, 3, 5, 6, 8, 9, 13]
An array of blocked creative attributes. For a complete list of supported values, refer to table 5.3 in the OpenRTB specification.
Note
Unity's policy is to block the following by default:
[1]
Audio Ad (auto-play)
[3]
Expandable (automatic)
[5]
Expandable (user initiated - rollover)
[6]
In-Banner video ad (auto-play)
[8]
Pop (for example: Over, Under, or Upon Exit)
[9]
Provocative or Suggestive Imagery
[13]
User Interactive (for example, embedded projects)
h
int
"h": 600
The height of the video player, in device-independent pixels (DIPS).
maxduration
int
"maxduration": 30
The maximum video ad duration in seconds. This value is always
30
.
mimes
string array
"mimes": ["video/mp4","video/webm"]
The supported content MIME types, including
"video/mp4"
and
"video/webm"
.
minduration
int
"minduration": 5
The minimum video ad duration in seconds. This value is always
5
.
placement
int
"placement": 5
Unity's supported video placement types are:
1
indicates in-stream
5
indicates interstitial
pos
int
"pos": 7
The video ad's position. Unity Ads inventory is always set to full screen (
7
). For a complete list of supported values, refer to table 5.4 in the OpenRTB specification.
protocols
int array
"protocols": [2, 3, 5, 6]
An array of supported video protocols. For a complete list of supported values, refer to table 5.8 in the OpenRTB specification.
Note
Unity fully supports VAST 2.0 (
2
) and VAST 2.0 Wrapper (
5
), and might support some features of VAST 3.0 (
3
) and VAST 3.0 Wrapper (
6
). For details, check with your account manager.
w
int
"w": 1024
The width of the video player, in device-independent pixels (DIPS).
companiontype
int array
"companiontype": [1,2,3]
An array of supported end card types, including
StaticResource
(
1
),
HTMLResource
(
2
), and
IFrameResource
(
3
).
linearity
int
"linearity": 1
Indicates if the impression must be linear. For Unity Exchange, this value is always
1
.
skip
int
"skip": 1
Indicates if the video can be skipped, where:
0
indicates the video cannot be skipped.
1
indicates the video can be skipped.
For Unity Exchange, this value is always
1
.
sequence
int
"sequence": 1
If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives. For Unity Exchange, this value is always
1
.
banner objects
A subset of the
impression
object class that describes a banner ad impression. For more information, refer to section 3.2.6 in the OpenRTB specification.
Attribute
Type
Example
Description
api
int array
"api": [6]
The banner API frameworks supported by the publisher. Unity supports MRAID 3.0 (
6
). For a complete list of supported values, refer to table 5.6 API Frameworks in the OpenRTB specification.
battr
int array
"battr": [ 1, 3, 5, 6, 8, 9]
An array of blocked banner creative attributes. For a complete list of supported values, refer to table 5.3 in the OpenRTB specification.
Note
Unity's policy is to block the following by default:
[1]
Audio Ad (auto-play)
[3]
Expandable (automatic)
[5]
Expandable (user initiated - rollover)
[6]
In-Banner video ad (auto-play)
[8]
Pop (for example: Over, Under, or Upon Exit)
[9]
Provocative or Suggestive Imagery
format
object array
"format": [{"w": 728, "h": 90}]
An array of objects representing the banner display sizes supported.Banner creative format supported sizes:
320x50
728x90
Display creative format supported sizes:
250x300
300x250
320x480
1024x768
Note
The
imp.banner
object is only passed for mobile banner and interstitial display requests. If no format is specified, the dimensions default to the
imp.banner.h
and
imp.banner.w
values. If no banner format is specified, the dimensions default to the
h
and
w
values. If you have questions about supporting different dimensions, contact Unity support.
h
int
"h": 320
The height of the banner display, in device-independent pixels (DIPS).
pos
int
"pos": 7
The banner ad's position. For a complete list of supported values, refer to table 5.4 in the OpenRTB specification.
w
int
"w": 480
The width of the banner display, in device-independent pixels (DIPS).
pmp objects
An object class that describes private marketplace attributes for direct deals between buyers and sellers that might pertain to the impression. For more information, refer to section 3.2.11 in the OpenRTB specification.
indicates that bids are restricted to the deals specified and the terms therein.
deal objects
An object class that describes a specific deal that was established between a buyer and seller. Its presence indicates that the impression is available under the terms of that deal. For more information, refer to section 3.2.12 in the OpenRTB specification.
Attribute
Type
Example
Description
at
int
"at": 1
An optional override of the auction type of the bid request:
1
indicates a first-price auction.
2
indicates a second-price auction.
3
indicates that the value passed in
bidfloor
is the agreed-upon deal price.
id
string
"id": "abcdef12345"
A unique identifier for the direct deal.
app objects
An object class that describes the app making the ad request. For more information, refer to section 3.2.14 in the OpenRTB specification.
Attribute
Type
Example
Description
bundle
string
Google example:
"bundle": "com.unityexample.game"
Apple example:
"bundle": "1198634425"
The application bundle or package name, intended to be unique across exchanges.
Android apps pass the Bundle ID.
iOS apps pass the Bundle ID or Store ID.
Note
This attribute might not be passed in circumstances where contractual agreements with the publisher prohibit it.
id
string
"id": "a1b2c3d4e5f6g7h8i9j0123456789abc"
The exchange-specific application ID.
name
string
"name": "Trash Dash"
The application name.
Note
This attribute might not be passed in circumstances where contractual agreements with the publisher prohibit it.
The store URL for an installed app (for QAG 1.5 compliance).This attribute might not be passed in circumstances where contractual agreements with the publisher prohibit it.
publisher objects
An object class that describes the publisher making the ad request. For more information, refer to section 3.2.15 in the OpenRTB specification.
Attribute
Type
Example
Description
id
string
"id": "a1b2c3d4e5f6g7h8i9j0123456789abc"
The exchange-specific publisher ID.
device objects
An object class that describes the end user's device. For more information, refer to section 3.2.18 in the OpenRTB specification.
Attribute
Type
Example
Description
connectiontype
int
"connectiontype": 1
The network connection type. For a complete list of supported values, refer to table 5.22 in the OpenRTB specification.
devicetype
int
"devicetype": 4
The general type of device. For a complete list of supported values, refer to table 5.21 in the OpenRTB specification.Note that separation between phone and tablet was introduced in in OpenRTB version 2.2:
The "Limit Ad Tracking" signal that is commercially endorsed.
0
indicates tracking is unrestricted.
1
indicates tracking must be limited per commercial guidelines.
Unity always passes this attribute when the value is
1
, and omits it when the value is
0
.
make
string
"make": "Apple"
The device's make.
model
string
"model": "iPhone7,2"
The device's model.
os
string
"os": "ios"
The device's operating system.
osv
string
"osv": "3.1.2"
The device's operating system version.
ua
string
"ua": "Mozilla/5.0 (iPhone; CPU iPhone OS 10_0 like Mac OS X)
AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A345"
The web browser user agent string.
carrier
string
"carrier": "Verizon"
The device's service provider.
Example bid requests
VAST bid request
{"id":"bcaIDT1Nbv0zU8mn9tXQ6j","at":1,"tmax":200,"source":{"pchain":"12abcd3456789:12345""omidpn":"Unity3d","omidpv":"1.3.0"},"imp":[{"id":"1","secure":1,"instl":1,"tagid":"com.unity3d.ads.example-vast","bidfloor":3.95,"video":{"mimes":["video/mp4","video/webm","application/javascript"],"minduration":5,"maxduration":30,"placement":5"protocols":[2,3,5,6],"pos":7,"battr":[1,3,5,8,9,13],"w":1024,"h":600,"api":[7],"companiontype":[1,2,3]}"displaymanager":"unity sdk","displaymanagerver":"4001","ext":{"skadn":{"ext":{"ask":1},"skoverlay":1,"productpage":1}}}],"app":{"id":"d01234idnfld234ier6c70930a","name":"Build A Town: All the games","publisher":{"id":"11972001l"},"bundle":"12312312399","storeurl":"https://apps.apple.com/us/app/build-a-town/id12312312399"},"device":{"ifa":"ab12c456-78de-90f1-ghi2-j3kl4567890m","make":"Apple","model":"iPhone","ua":"Mozilla/5.0 (iPhone; CPU iPhone OS 10_0 like Mac OS X) AppleWebKit/602.1.50 (KHTML, like Gecko) Mobile/14A345","os":"ios","ip":"12.34.5.6","devicetype":4,"carrier":"Apple","osv":"10.1","hwv":"iphone6","geo":{"lat":55.5492,"lon":59.0456,"country":"USA","city":"San Francisco","type":2,"utcoffset":180},"connectiontype":3,"language":"en","h":1184,"w":768},"regs":{"coppa":0}}
{"id":"abcIDT1Def0zU8mn9gHI6j","source":{"pchain":"12abcd3456789:12345"},"imp":[{"id":"1","banner":{"w":1024,"h":768,"battr":[1,3,5,6,8,9],"pos":7,"api":[5]},"displaymanager":"unity sdk","displaymanagerver":"4000","instl":1,"tagid":"com.unity-game.trashdash-m3-ios-display","bidfloor":3.95,"secure":1}],"app":{"id":"d01234idnfld234ier6c70930a","name":"Build A Town: All the games","publisher":{"id":"11972001l"},"bundle":"12312312399","storeurl":"https://apps.apple.com/us/app/build-a-town/id12312312399"},"device":{"ifa":"ab12c456-78de-90f1-ghi2-j3kl4567890m","ua":"Mozilla/5.0 (iPad; CPU OS 11_2_2 like Mac OS X) AppleWebKit/604.4.7 (KHTML, like Gecko) Mobile/15C202","geo":{"lat":55.5492,"lon":59.0456,"country":"USA","city":"San Francisco","type":2,"utcoffset":180},"ip":"12.34.5.6","devicetype":5,"model":"iPad5,3","os":"ios","osv":"11.2.2","hwv":"iPad Air 2 (Wi-Fi)","h":768,"w":1024,"language":"en","connectiontype":2},"at":1,"tmax":200,"regs":{},"ext":{}}