Follow the OpenRTB 2.5 specifications to connect your DSP or ad platform with the ironSource Exchange for programmatic ad buying.
읽는 시간 11분최근 업데이트: 3달 전
The following article specifies the objects and parameters that are supported by ironSource Exchange, ensure that you have the OpenRTB 2.5 Specification Guide available while reviewing the spec.
Bid request
Request object
Parameter
Type
Always passed
Description
id
String
Yes
Unique id of the bid request. This id must be returned in the bid response object.
imp
Object
Yes
ironSource supports one impression object per bid request. See Impression.
at
integer
Yes
The auction type used. ironSource supports first price auction only.
app
Object
Yes
App description. See App.
device
Object
Yes
Device description. See Device.
user
Object
Yes
User description. See User.
tmax
integer
Yes
Maximum time in milliseconds ironSource allows for bids to be received.
bcat
String array
Yes
Blocked advertiser categories using the IAB content categories.
badv
String array
No
Block list of advertisers by their domains
bapp
String array
No
Block list of applications. On Android, these should be bundle or package names (for example, com.foo.mygame). On iOS, these are numeric IDs.
source
Object
Yes
A Source object that provides data about the inventory source and which entity makes the final decision.
regs
Object
Yes
A Regs object that specifies any industry, legal, or governmental regulations in force for this request.
ext
Object
No
Placeholder for ironSource specific extensions to OpenRTB.
Impression object
Parameter
Type
Always passed
Description
id
String
Yes
ironSource supports a single impression object per Bid request.
video
Object
For Video only
The object is used to describe a video impression. See video.
banner
Object
For Display only
The object is used to describe a display impression. See banner.
instl
integer
No
1 = the ad is interstitial or full screen, 0 = not interstitial.
secure
integer
Yes
ironSource requires the impression to have secure HTTPS URL creative assets and markup.
pmp
Object
Yes
A Pmp object containing any private marketplace deals in effect for this impression
bidfloor
Float
Yes
Minimum bid for this impression expressed in CPM.
bidfloorcur
String
Yes
ironSource accepts USD only
ext
Object
No
Placeholder for ironSource specific extensions to OpenRTB.
Video object
Parameter
Type
Always passed
Description
mimes
String array
Yes
Content mime types supported.
minduration
integer
Yes
Minimum video ad duration in seconds.
maxduration
integer
Yes
Maximum video ad duration in seconds.
protocols
integer array
Yes
Array of supported video protocols
w
integer
Yes
Width of the video player in device independent pixels (DIPS).
h
integer
Yes
Height of the video player in device independent pixels (DIPS).
placement
integer
Yes
Placement type for the impression.
Skip
integer
Yes
Indicates if the player will allow the video to be skipped or not.
battr
integer array
Yes
Blocked creative attributes.
playbackmethod
integer
Yes
Playback methods that may be in use.
pos
integer
Yes
Ad position on screen.
api
integer array
Yes
List of supported API frameworks for this impression
ext.rewarded
integer
Yes
Indicates whether the request is for a rewarded video ad unit. 1 = yes, 0 = no
Banner object
Parameter
Type
Always passed
Description
w
integer
Yes
Width of the video player in device independent pixels (DIPS).
h
integer
Yes
Height of the video player in device independent pixels (DIPS).
pos
integer
Yes
Ad position on screen.
btype
integer array
Yes
Blocked banner ad types.
battr
integer array
Yes
Blocked creative attributes.
api
integer array
Yes
List of supported API frameworks for this impression
Format object
Used when multiple sizes are permitted.
Parameter
Type
Always passed
Description
w
integer
Yes
Width of the video player in device independent pixels (DIPS).
h
integer
Yes
Height of the video player in device independent pixels (DIPS).
App object
Parameter
Type
Always passed
Description
id
String
Yes
ironSource specific application id
bundle
String
Yes
A platform-specific application identifier. On Android, this should be a bundle or package name (for example, com.foo.mygame). On iOS, it is typically a numeric ID.
name
String
Yes
Application name
storeurl
String
Yes
App Store URL
cat
String array
Yes
IAB content categories of the app
Device object
Parameter
Type
Always passed
Description
ua
String
Yes
Browser user agent string.
geo
Object
Yes
Location of the device assumed to be the user’s current location defined by a Geo object/
lmt
integer
Yes
“Limit Ad Tracking” signal, where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
ip
String
Yes
IPv4 address closest to device.
devicetype
integer
Yes
The general type of device.
make
String
Yes
Device make.
model
String
Yes
Device model.
os
String
Yes
Operation system
osv
String
Yes
Operation system version
language
String
Yes
language string Browser language using ISO-639-1-alpha-2.
connectiontype
integer
Yes
Network connection type
ifa
String
Yes
ID sanctioned for advertiser use in the clear (for example, not hashed)
ext.ifv
String
Yes
(iOS Only) The Identifier for Vendors assigned to all apps by one developer. Listed as ifv to match ifa field format.
ext.atts
integer
Yes
(iOS Only) represent the app's app tracking authorization status, where 0 = not determined 1 = restricted 2 = denied 3 = authorized
User object
Parameter
Type
Always passed
Description
id
String
Yes
ironSource-specific ID for the user
ext.impdepth
Float
Yes
An impression count for specific placement in a given app session. The impression depth is reset when the session ends.
Source object
Parameter
Type
Always passed
Description
ext.schain
Object
Yes
Schain object containing sellers.json information
ext.schain.nodes
Object array
Yes
Publisher's Application sellers.json information
ext.header bidding
Integer
Yes
Indicates the waterfall's type, where 1=Bidding, 0=Instances
Regs object
Parameter
Type
Always passed
Description
ext.gdpr
String
Yes
Specifies if the request is subject to GDPR regulations.
Geo object
Parameter
Type
Always passed
Description
lat
Float
Yes
Latitude from -90.0 to +90.0, where negative is south.
lon
Float
Yes
Longitude from -180.0 to +180.0, where negative is west.
type
Integer
Yes
Source of location data
ipservice
Integer
Yes
Service or provider used to determine geolocation from IP address if applicable
country
String
Yes
Country code using ISO-Country code using ISO-3166-1-alpha-3.3166-1-alpha-3.-3
region
String
Yes
Region code using ISO-3166-2; 2-letter state code if USA.
metro
String
Yes
Google metro code.
city
String
Yes
City using United Nations Code for Trade & Transport Locations.
zip
String
Yes
zip string Zip or postal code.
Bid response
Bid response object
Parameter
Type
Requirement
Description
id
String
Required
ironSource request id must be passed back on the Bid Response.
cur
String
Required
ironSource supports USD only; any other ISO currency code will result in the bid response being ignored.
bidid
String
Recommended
Bidder generated response ID to assist with logging/tracking.
nbr
Integer
Recommended
Reason for not bidding. Refer to List 5.22 in OpenRTB 2.3 Spec.
seatbid
Object array
Recommended
Multiple seatbid objects are allowed in a response, however, ironSource currently only uses one seatbid object. The seatbid object chosen will contain:bid.id = impression.id
Seat bid object
Parameter
Type
Requirement
Description
bid
Object array
Required
ironSource expected at least one bid.
Bid object
Parameter
Type
Requirement
Description
id
String
Required
Bidder generated bid ID to assist with logging/tracking.
impid
String
Recommended
ID of the impression to which this bid applies. This value will match the impression id provided in the bid request.
price
Float
Required
Bid price in CPM. A value that is equal to, or less than zero will be ignored.
nurl
String
Recommended
Win notice URL called by ironSource when the bid wins the auction (not necessarily indicative of a delivered, viewed, or billable ad). When burl isn't present, the nurl will replace it, and report Billing notice.
burl
String
Required
Billing notice URL called by ironSource when a winning bid becomes billable.
lurl
String
Recommended
Loss notice URL called by ironSource when a bid is known to have been lost. ironSource supports the
${MIN\_BID\_TO\_WIN}
macro, to indicate the minimum bid required to win the final auction.
cid
String
Recommended
Campaign ID to assist with ad quality checking.
crid
String
Recommended
Creative ID to assist with ad quality checking.
adm
String
Required
Required means of conveying ad markup in case the bid wins.
adomain
String array
Required (if bid.bundle=null)
Advertiser domain for blacklist checking
bundle
String
Required (if bid.adomain=null)
A platform-specific application identifier. On Android, this should be a bundle or package name (for example, "com.foo.mygame"). On iOS, it is typically a numeric ID.
cat
String array
Recommended
IAB content categories of the creative.
attr
Integer array
Recommended
Set of attributes describing the creative.
w
Integer
Required
Width of the creative in device independent pixels (DIPS).
h
Integer
Required
Height of the creative in device independent pixels (DIPS).
No bid response
Bidders can respond with any of the following that will be considered a 'no bid'' within ironSource. It is important to use any of the following responses to explicitly signal you do not want to bid on the impression, otherwise the response may be interpreted as a timeout error. No bid (for example, no demand, no interest in buying the impression):
HTTP 204 No Content
An empty JSON object: ""
A well-formed no bid response (NBR):
{"id": "1234567890", "seatbid": \[\]}
No bid due to an issue
A well-formed no bid response:
{"id": "1234567890", "seatbid": \[\], "nbr": 2}
The list of issue code that can be used for nbr can be found below: