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.

AttributeTypeExampleDescription
idstring"id": "bcaIDT1Nbv0zU8mn9tXQ6j"A Unity-generated ID. This ID must be returned in the bid response object.
impobjectFor more information, refer to the section on impression objects.Unity supports one imp object per bid request.
pmpobjectFor 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.
appobjectFor more information, refer to the section on app objects.An object describing the project or application.
deviceobjectFor more information, refer to the section on device objects.An object describing the user's device.
userobjectFor more information, refer to the documentation on data privacy.An object representing the human user of the device, or audience of the ad.
atint"at": 1The auction type used. All Unity Exchange auctions are first-price auctions, so the value is always 1.
tmaxint"tmax": 200

Timeout value in milliseconds.

Note: Unity suggests that partners respond within 200 ms to avoid the network connection dropping.

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

Blocked advertiser categories, using IAB taxonomy IDs.

Note: This attribute is supported but optional.

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

sourceobjectFor 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.
regsobjectFor 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
pchainstring"pchain": "12abcd3456789:12345"A payment chain ID string containing embedded syntax described in the TAG Payment ID Protocol v1.0.
omidpnstring"omidpn": "Unity3d"An identifier for the Open Measurement SDK integration. This is the same as the name parameter of the OMID Partner object.
omidpvstring"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.
schainobjectFor 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.

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

nodesobject arrayNeed exampleArray 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.
verstring"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
asistring“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.

sidstring“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.
ridstring"rid": "582f5fb3-0cc6-4944-ab12-1233175675e8-9999-36946"The OpenRTB RequestId of the request as issued by this seller.
hpint"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
bannerobjectFor more information, refer to the section on banner objects.

An object that describes a banner display impression.

Note: Unity only passes this attribute for banner and display ads.

bidfloorfloat"bidfloor": 3.95The minimum CPM bid required to win this impression. Expressed in USD.
displaymanagerstring"displaymanager": "unity sdk"The name of the ad mediation partner, SDK technology, or player responsible for rendering the ad.
displaymanagerverstring4001The version of the ad mediation partner, SDK technology, or player responsible for rendering the ad.
idstring"id": "1"Unity supports one imp object per bid request, so the id value is always 1.
instlint"instl": 1Banner ad requests have a value of 0; all other placements are interstitials, with a value of 1.
secureint"secure": 1Unity requires impressions to have secure HTTPS URL creative assets and markup; the value is always 1.
tagidstring"tagid": "com.this.game-video"Unity passes <appID>-<adType> as the identifier.
videoobjectFor 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.skadnobjectFor 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.skoverlayInteger1

Indicates eligibility for SKOverlay feature.

  • 1 indicates imp is eligible for showing SKOverlay.

  • 0 indicates imp is not eligible for showing SKOverlay.

ext.skadn.productpageInteger1

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

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

hint"h": 600The height of the video player, in device-independent pixels (DIPS).
maxdurationint"maxduration": 30The maximum video ad duration in seconds. This value is always 30.
mimesstring array"mimes": ["video/mp4",”video/webm”]The supported content MIME types, including "video/mp4" and "video/webm".
mindurationint"minduration": 5The minimum video ad duration in seconds. This value is always 5.
placementint"placement": 5

Unity's supported video placement types are:

  • 1 indicates in-stream

  • 5 indicates interstitial

posint"pos": 7The 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.
protocolsint 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.

wint"w": 1024The width of the video player, in device-independent pixels (DIPS).
companiontypeint array“companiontype”: [1,2,3]An array of supported end card types, including StaticResource (1), HTMLResource (2), and IFrameResource (3).
linearityint“linearity”: 1Indicates if the impression must be linear. For Unity Exchange, this value is always 1.
skipint“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.

sequenceint“sequence”: 1If 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
apiint 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.
battrint 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
formatobject 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.

hint"h": 320The height of the banner display, in device-independent pixels (DIPS).
posint"pos": 7The banner ad's position. For a complete list of supported values, refer to table 5.4 in the OpenRTB specification.
wint"w": 480The 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
dealsobject arrayFor more information, refer to the section on deal objects.An array of deal objects that conveys the specific deals applicable to this impression.
private_auctionint"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
atint"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.
idstring"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
bundlestring

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.

idstring"id": "a1b2c3d4e5f6g7h8i9j0123456789abc"The exchange-specific application ID.
namestring"name": "Trash Dash"

The application name.

Note: This attribute might not be passed in circumstances where contractual agreements with the publisher prohibit it.

publisherobject"publisher": "ExamplePublisher"An exchange-specific publisher ID.
storeurlstring"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.

AttributeTypeExampleDescription
idstring"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
connectiontypeint"connectiontype": 1

The network connection type. For a complete list of supported values, refer to table 5.22 in the OpenRTB specification.

devicetypeint"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.
geoobject

“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

hwvstring"hwv": "samsung SM-J200H"The hardware version of the device.
ifastring"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.

ipstring"ip": "12.34.5.6"

The device's IP address.

Note: Unity clears this field where required by COPPA or GDPR compliance.

languagestring"language": "en"The browser language, using ISO-639-1-alpha-2 codes.
lmtint"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.

Note: Unity always passes this attribute when the value is 1, and omits it when the value is 0.

makestring"make": "Apple"The device's make.
modelstring"model": "iPhone7,2"The device's model.
osstring"os": "ios"The device's operating system.
osvstring"osv": "3.1.2"The device's operating system version.
uastring"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.
carrierstring"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
	}
}