Bid requests
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 application/json
, and specified in an HTTP header field as:
contentType: application/json
Accept-Encoding: gzip
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.
Attribute | Type | Example | Description |
---|---|---|---|
id | string | "id": "bcaIDT1Nbv0zU8mn9tXQ6j" | A Unity-generated ID. This ID must be returned in the bid response object. |
imp | object | For more information, refer to the section on impression objects . | Unity supports one imp object per bid request. |
pmp | object | For more information, refer to the section on pmp objects . | 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 deal objects . |
app | object | For more information, refer to the section on app objects . | An object describing the project or application. |
device | object | For more information, refer to the section on device objects . | An object describing the user's device. |
user | object | For more information, refer to the documentation on data privacy. | An object representing the human user of the device, or audience of the ad. |
at | int | "at": 1 | The auction type used. All Unity Exchange auctions are first-price auctions, so the value is always 1 . |
tmax | int | "tmax": 200 | Timeout value in milliseconds. Note: Unity suggests that partners respond within 200 ms to avoid the network connection dropping. |
bcat | string array | "bcat": ["IAB9-9", "IAB8"] | Blocked advertiser categories, using IAB taxonomy IDs. Note: This attribute is supported but optional. |
bapp | string array | "bapp": ["com.foo.mygame"] | A list of blocked applications, represented by their specific platform. On Android, these are bundle or package names. On iOS, these are numeric IDs. |
source | object | For more information, refer to the section on source objects . | 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.
Attribute | Type | Example | Description |
---|---|---|---|
pchain | string | "pchain": "12abcd3456789:12345" | A payment chain ID string containing embedded syntax described in the TAG Payment ID Protocol v1.0. |
omidpn | string | "omidpn": "Unity3d" | 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. |
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.
|
nodes | object array | Need example | 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 (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 |
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 publisher.id . Limit this field to 64 characters in length. |
rid | string | "rid": "582f5fb3-0cc6-4944-ab12-1233175675e8-9999-36946" | The OpenRTB RequestId of the request as issued by this seller. |
hp | int | "hp":1 | Indicates whether this node is involved in payment flow for the inventory.
|
imp objects
An object class that describes the ad impression being auctioned.
Attribute | Type | Example | Description |
---|---|---|---|
banner | object | For more information, refer to the section on . | 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.
|
ext.skadn.productpage | Integer | 1 | Indicates eligibility for Custom Product Page feature.
|
ext.skadn.ext.ask | Integer | 1 | Indicates eligibility for Auto Storekit feature.
|
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: |
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:
|
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 ( |
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:
For Unity Exchange, this value is always |
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:
|
format | object array | "format": [{"w": 728, "h": 90}] | An array of objects representing the banner display sizes supported. Banner creative format supported sizes:
Display creative format supported sizes:
Note: The |
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.
Attribute | Type | Example | Description |
---|---|---|---|
deals | object array | For more information, refer to the section on deal objects . | An array of deal objects that conveys the specific deals applicable to this impression. |
private_auction | int | "private_auction": 0 | Indicates auction eligibility for the seats named in the
|
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:
|
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:
Apple example:
| The application bundle or package name, intended to be unique across exchanges.
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. |
publisher | object | "publisher": "ExamplePublisher" | An exchange-specific publisher ID. |
storeurl | string | "storeurl": "https://itunes.apple.com/us/app/trash-dash/id1198634425?mt=8" | The store URL for an installed app (for QAG 1.5 compliance). Note: 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:
|
geo | object |
| Location data for the device (assumed to be the user’s current location):
|
hwv | string | "hwv": "samsung SM-J200H" | The hardware version of the device. |
ifa | string | "ifa": "ab12c456-78de-90f1-ghi2-j3kl4567890m" | The Android Advertising ID (AID) or iOS Identifier for Advertisers (IFA/IDFA) sanctioned for advertiser use in the clear (not hashed). Note: Unity clears this field where required by COPPA or GDPR compliance. |
ip | string | "ip": "12.34.5.6" | The device's IP address. Note: Unity clears this field where required by COPPA or GDPR compliance. |
language | string | "language": "en" | The browser language, using ISO-639-1-alpha-2 codes. |
lmt | int | "lmt": 1 | The "Limit Ad Tracking" signal that is commercially endorsed.
Note: 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
}
}
Banner bid request
{
"id": "bcda7938-14eb-4a46-8dcb-bcd7587a964f",
"imp": [
{
"id": "1",
"banner": {
"w": 320,
"h": 50,
"battr": [
1,
3,
5,
6,
8,
9,
13
]
},
"pmp": {},
"displaymanager": "unity sdk",
"displaymanagerver": "3200",
"tagid": "com.unity3d.ads.opstool-banner",
"bidfloor": 3.95,
"secure": 1
}
],
"app": {
"id": "2aa377f91oo12398465d6af383",
"name": "Example Game: Chapter Two",
"publisher": {
"id": "189857700"
},
"bundle": "com.devexample.thegamebundlename",
"storeurl": "https://play.google.com/store/apps/details?id=com.devexample.thegamebundlename\u0026hl=en"
},
"device": {
"ua": "Mozilla/5.0 (Linux; Android 9; Pixel Build/PQ3A.190705.001; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/75.0.3770.101 Mobile Safari/537.36",
"geo": {
"lat": 37.7958,
"lon": -122.4203,
"type": 2,
"country": "USA",
"region": "CA",
"city": "San Francisco",
"utcoffset": -480
},
"ip": "4.14.109.3",
"devicetype": 4,
"make": "Google",
"model": "Pixel",
"os": "android",
"osv": "9.0",
"hwv": "Google Pixel",
"w": 320,
"h": 50,
"language": "en",
"connectiontype": 2,
"ifa": "d0a77d1b-e974-41f3-84c5-8fe75718ef2d"
},
"at": 1,
"tmax": 500,
"regs": {
"ext": {}
},
"ext": {
"sessionDepth": 1
}
}
Playable bid request
{
"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": {}
}
Interstitial display bid request
{
"id": "ApJv9QAmN3FJjEcTtFDtW3",
"imp": [{
"id": "1",
"banner": {
"w": 480,
"h": 320,
“format”: [
{"w":250,"h":300},
{"w":300,"h":250},
{"w":480,"h":320},
{"w":320,"h":480}
],
"battr": [1, 3, 5, 6, 8, 9, 13],
"pos": 7,
"api": [5]
},
“displaymanager": "unity sdk",
"displaymanagerver": "3750",
"instl": 1,
"tagid": "com.unity3d.ads.example-display",
"bidfloor": 3.95,
"secure": 1
}],
"app": {
"id": "2aa377f91oo12398465d6af383",
"name": "Example Game: Chapter Two",
"publisher": {
"id": "189857700"
},
"bundle": "com.devexample.thegamebundlename",
"storeurl": "https://play.google.com/store/apps/details?id=com.devexample.thegamebundlename\u0026hl=en"
},
"device": {
"ua": "Mozilla/5.0 (Linux; Android 5.1.1; SM-J200H Build/LMY48B; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/64.0.3282.137 Mobile Safari/537.36",
"geo": {
"lat": 55.5492,
"lon": 59.0456,
"country": "USA",
"city": "San Francisco",
"type": 2,
"utcoffset": 180
},
"source": {
"pchain": "12abcd3456789:12345"
},
"ip": "12.34.5.6",
"devicetype": 4,
"make": "samsung",
"model": "SM-J200H",
"os": "android",
"osv": "5.1",
"hwv": "samsung SM-J200H",
"h": 540,
"w": 960,
"language": "ru",
"carrier": "Tele2",
"connectiontype": 2,
"ifa": "dd92e219-68ae-43b9-bcb7-e6fb7557806e"
},
"at": 1,
"tmax": 200,
"regs": {},
"ext": {
"placementType":"nonrewarded",
"Mute":false,
"gameCategory":"Applications",
"subGameCategory":"Tools",
"sessionDepth":0
}
}