Bid requests

Read time 47 minutes

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.

request objects

The top-level bid request object contains a globally unique ID for the ad request.

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

bcat
string array
"bcat": ["IAB9-9", "IAB8"]

Blocked advertiser categories, using IAB taxonomy IDs.

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.

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

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

  • 0 indicates no
  • 1 indicates yes.
nodes
object arrayNeed 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.

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

  • 0 indicates that this node is not involved in the payment flow.
  • 1 indicates that 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.

imp objects

An object class that describes the ad impression being auctioned.

AttributeTypeExampleDescription
banner
object

For more information, refer to the section on banner objects.

An object that describes a banner display impression.

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.

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.

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

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.

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.

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.

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

  • [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
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.

AttributeTypeExampleDescription
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 object:

  • 0 (default) indicates that all bids are accepted.
  • 1 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.

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

AttributeTypeExampleDescription
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.
id
string
"id": "a1b2c3d4e5f6g7h8i9j0123456789abc"
The exchange-specific application ID.
name
string
"name": "Trash Dash"

The application name.

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

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.

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

AttributeTypeExampleDescription
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:

  • 4 specifies a phone.
  • 5 specifies a tablet.
geo
object

"geo": { "lat":34.0544, "lon":-118.2441, "type":2, "country":"USA", "region":"CA", "city":"Los Angeles", "utcoffset":-480 }

Location data for the device (assumed to be the user's current location):

  • lat
  • lon
  • type
  • country
  • region
  • city
  • UTCoffset
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).

ip
string
"ip": "12.34.5.6"

The device's IP address.

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.

  • 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": "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
	}
}