Help demand partners structure valid responses that meet auction and ad delivery requirements.
Read time 8 minutesLast updated 2 months ago
Unity supports JSON formats for bid response data. The MIME type for the standard JSON representation is
application/json
and specified in an
HTTP
header field as:
contentType: application/json
After your application receives the bid request to its dedicated endpoint, it must return a bid response or indicate a no-bid within a maximum of 200 milliseconds. Unity sends Accept-Encoding GZIP compression in the request, and the recommended best practice is to compress the response. For more information, refer to section 2.4 of the OpenRTB specification.
Note
The recommended best practice is that DSP servers, including load balancers, activate HTTP Persistent Connections, also known as Keep-Alive, and prevent automatic
IdleConnTimeout
for at least 90 seconds. This has a profound impact on overall performance by reducing connection management overhead and CPU utilization on both sides of the interface.
Response objects and their attributes are detailed in the following section. The description field denotes required attributes. The recommended best practice is that you include all attributes.
response objects
An object class describing the bidder's response to the bid request.
Attribute
Type
Example
Description
id
string
"id":"7jrUifdKuw3HDIR9dbqDVJ"
A Unity-generated ID passed with the bid request and returned with the bid response.
Important
This attribute is required in the response.
cur
string
"cur": "USD"
The currency type, using ISO currency codes. Unity supports U.S. dollars (
USD
), and other currencies such as
CNY
. Make sure this field matches the currency field defined in the
adsource
configuration, and
exchange_rate
is not empty, or else Unity will ignore the bid response.
Important
This attribute is required in the response.
bidid
string
"bidid": "CHYr9b0ODI8OGLpedtfCpuCH"
Bidder-generated response ID to assist with logging and tracking.
nbr
int
"nbr": 6
Reason for declining to bid. For a complete list of supported values, refer to table 5.24 in the OpenRTB API guide. Also refer to the section on No-bid responses.
Billing notice URL called by Unity Exchange when a winning bid becomes billable. This is based on exchange-specific business policy. Substitution macros can be included.
Important
This attribute is a unique Unity Exchange requirement when there is no
imptrackers
attribute in the response.
Note
Unity pings the
bURL
at the time of delivery and replaces the bid price macro (
Means of conveying ad markup in case the bid wins.
Important
This attribute is required in the response.
adomain
string array
Correct:
"adomain": ["yourgame.com"]
"adomain": ["studio.yourgame.com"]
Incorrect:
"adomain": ["yourgame.com/something"]
"adomain": ["www.yourgame.com"]
Advertiser domain for block-list checks. Creatives cannot be rotated, and only one domain is allowed. The format must be the root domain only, with no protocol (note that you can include subdomains if they are not "www").
Important
This attribute is required in the response.
bundle
string
Google example:
"bundle": "com.unityexample.game"
Apple example:
"1198634425"
A platform-specific application identifier (store ID for the Apple App Store or Google Play) that is unique to the advertised app and independent of the exchange. This feature can also be used for ad quality.
Important
This attribute is a unique Unity Exchange requirement for app advertisements.
attr
int array
"attr": [1, 13]
An array of attributes describing the creative. For a complete list of supported values, refer to table 5.3 in the OpenRTB API guide.
w
int
"h": 568
Width of the creative in device-independent pixels (DIPS).
Important
This attribute is required for banner ads, and is recommended for all formats.
h
int
"w": 320
Height of the creative in device independent-pixels (DIPS).
Important
This attribute is required for banner ads, and is recommended for all formats.
api
int
"api":7
The API framework supported for this impression. A value of
7
signifies Open Measurement (OM) support. For more information, refer to the documentation on OM extensions.
bid.ext objects
An object subclass extending the
bid
object.
Important
You must add the ext attribute as an object to support the SKAdNetwork with iOS14.
Attribute
Type
Example
Description
appid
string
"appid": "1234567890123"
App store ID for the app being advertised, if applicable. For more information on locating the App store ID, refer to the Unity Ads Monetization dashboard documentation on Store IDs.
appname
string
"appname": "Example Game"
App name of the app being advertised, if applicable.
Array of impression trackers (first- and third-party) to be consistently tracked as Unity records the billable impression event. Can be used in place of a bid
bURL
.
Important
This attribute is a unique Unity Exchange requirement when there is no
burl
attribute in the response.
length
int
"length": 15
Length of the video in seconds, if applicable.
crtype
string
"crtype": "VAST 3.0"
The creative type of the ad asset. The following types are valid:
VAST
VAST 2.0
VAST 3.0
VAST 4.0
VAST VPAID
MRAID playable
MRAID 2.0
BANNER
HTML
HTML5
JS
Important
These values are case-insensitive. This attribute is required in the response.
ext.skadn.skoverlay.show
Integer
1
Indicates whether to show SKOverlay.
1
indicates yes.
0
indicates no.
Important
Unity shows default values in the case of show = 1 and the rest of the attributes are empty.
ext.skadn.skoverlay.position
Integer
1
Indicates the position of the SKOverlay.
0
indicates bottom.
1
indicates bottomRaised.
Default value is 0.
ext.skadn.skoverlay.dismissable
Integer
1
Indicates whether the SKOverlay can be dismissed by the user.
0
indicates no (static).
1
indicates yes (dismissable).
Default value is 1.
ext.skadn.skoverlay.video_delay
Integer
1
Indicates the time in seconds to delay before showing the SKOverlay, where 0 means immediate.
indicates showing Storekit when the user skips video. Click event will not be sent when opening the Storekit from the skip action.
2
indicates showing Storekit when the user skips video or finishes watching video. Click event will not be sent when opening the Storekit from the skip action.
3
indicates showing Storekit when the user skips video. Click event will be sent when opening the Storekit from the skip action.
4
indicates showing Storekit when the user skips video or finishes watching video.Click event will be sent when opening the Storekit from the skip action.
ext.clickablevideo
Integer
1
Indicates whether to enable Clickable Video experience.
Unity Exchange supports multiple response types for a no-bid. It is important to use one of these responses to explicitly signal your wish to not bid on the impression, otherwise the response might be interpreted as a timeout error.
Response
Example
No content
HTTP 204 No Content
Empty JSON object
{}
Well-formed bid response (with or without a reason code)
, the recommended best practice is that you implement obfuscation for the
${AUCTION_PRICE:BF}
value to keep sensitive price information secure on the client side. This is an optional feature.
Methodology
To obfuscate data, Unity uses Blowfish in ECB mode, with PKCS5 padding (PKCS7 padding with 8 byte block sizes) applied to the input data. The data is then base64 URL-encoded so that the binary data is valid in URLs. Source code is available upon request for troubleshooting.
Unity uses a different encryption key in live production.
Decryption
To decrypt data, the input string is base64 URL-decoded. PKCS5 Padding is then removed from the encrypted data, then the blowfish ECB encryption is reversed.