1. Bugdet - Xtend-DSP RTB Integration (DSP)
This document provides instructions for the integration of Xtend system with external DSP system. It describes the requirements and steps needed to enable interface connection based on open RTB.
To enable DSP to connect with Midas, the steps include:
● Sign contract: Mutual agreement contract between Xtend and DSP.
● Register DSP account: Contact Xtend Operations PIC to register DSP account in Midas system in order to receive the token. Note: Currently Midas doesn't support auto-registration, and it is necessary to contact Xtend and provide relevant information in order to complete the account registration.
● Proceed to system integration set-up: DSP needs to follow this document to build interface and set up integration. If there is any issue encountered during the process, Midas will provide Product and Tech PIC to support and solve the issue accordingly.
● Test: After integration is set up, DSP and Midas need to arrange testing for the integration and make adjustments when necessary.
● Live: After test completes, Xtend PIC from business team will follow up with official launch of integrated online traffic and start to record cost.
The connection between DSP and Midas follows HTTP communication protocol, to send Bid Request via POST mode as the content for HTTP request, and use data in JSON format.
HTTP POST mode is used to send Bid Request, instead of HTTP GET mode, as it enables more content to be attached and supports binary data better.
Request thread:
Name |
Value |
Remark |
x-openrtb-version |
2.5 |
open rtb version |
If Midas is participating in bid / auction, HTTP response status code should be 200, which allows it to return to Bid Request. If not, HTTP response status code should be 204.
The billing is based on the number of displays reported in the winnotice (default winnotice is in nurl, if the DSP does not support nurl, it is in burl) link statistics when the bid is won, so you need to replace the {AUCTION_PRICE} macro in the winnotice url when the bid is won.
DSP needs to ensure that at most one ad is reported for impression at a time; and that the reported display is within the validity of the impression delay required by Xtend.
Xtend limits the impression delay by using the bidresponse.seatbid.bid.exp field.
If the following fields in the request body are empty, the Xtend platform will consider the request as invalid and will not be populated.
bid.imp[].tagid: DSP's ad space identifier
bid.app.bundle: package name information of the traffic source
bid.device.ifa: unique identifier allowed for advertisers, explicitly stated; Android passes gaid, iOS passes idfa
bid.device.ua: User-Agent field in the HTTP request header of the user's device
bid.device.ip: ip address of the user's current network
bid.device.geo.country: the country of the user's current network, using ISO-3166-1-alpha-3
Parameter name |
Type |
Required? |
Description |
id |
string |
Yes |
The only identification for Bid Request |
imp |
object array |
Yes |
1 request can include only 1 impression object at a time, which represents a specific ad display placement/position. Details can be found in imp object parameter definition below |
app |
object |
Yes |
App object info of DSP, recommended to use only on app instead of website. Details can be found in app object parameter definition below |
device |
object |
Yes |
Device info. Details can be found in device object parameter definition below |
user |
object |
No |
Device user / Ad audience. Details can be found in user object parameter definition below |
at |
integer |
Yes |
Bid settlement auction type. Value of 1 means it follows First-price auction, while value of 2 means it follows Second-price plus auction. |
badv |
string array |
No |
Domain name in blacklist |
bapp |
string array |
No |
App name in blacklist.On Android, these should be bundle or package names (e.g., com.foo.mygame). On iOS, these are numeric IDs. |
regs |
object |
No |
Any industry, legal, or governmental regulations in force |
Parameter name |
Type |
Required? |
Description |
id |
string |
Yes |
The only identification in a Bid Request for the specific display traffic sold. 1 request can include only 1 display traffic at a time |
tagid |
string |
Yes |
Fixed identification of each specific ad display placement/position |
native |
object |
Yes for Native traffic |
Refer to native object (Supports only Native ad placement) |
banner |
object |
Yes for Banner traffic |
Refer to banner object |
video |
object |
Yes for Video traffic |
Refer to video object |
audio |
object |
Yes for Audio traffic |
Refer to audio object |
exp |
integer |
No |
Duration that may elapse between the auction and the actual display / impression.Unit is in seconds |
secure |
integer |
No |
Parameter to indicate if Bid Request needs HTTPS encrypted info and markup to ensure data privacy.Value of 0 means it doesn't need. Value of 1 means it needs. If left blank, means unknown, i.e. it doesn't need encryption |
bid floor |
float |
No |
Minimum CPM bid price for this display traffic |
bidfloorcur |
string |
Yes |
Bid price currency, currently it only supports USD |
Parameter name |
Type |
Required? |
Description |
id |
string |
No |
Unique identifier for this banner object. Recommended when Banner objects are used with a Video object to represent an array of companion ads. Values usually start at 1 and increase with each object; should be unique within an impression. |
w |
integer |
Yes |
Exact width in device independent pixels (DIPS); If not specified wmin and wmax , this value refers to the required display width, otherwise refers to the desired width |
h |
integer |
Yes |
Exact height in device independent pixels (DIPS); If not specified hmin and hmax , this value refers to the required display height, otherwise refers to the desired height |
pos |
integer |
No |
Ad position on screen. Section 5.5 Ad Placement/Position Attribute is the reference of its enumerated values |
mimes |
string array |
Yes |
Content MIME types supported. Popular MIME types may include "application/x-shockwave-flash", “image/jpg”, and “image/gif”。SHAREit support "image/jpg","image/png", and "image/gif" |
ext |
object |
No |
Placeholder for exchange-specific extensions to OpenRTB |
Parameter name |
Type |
Required? |
Description |
request |
string |
Yes |
Request must follow Native ad specification. Refer to native request object for details |
ver |
string |
Yes |
Use Dynamic Native Ads API version, default version is 1.2 |
api |
integer array |
No |
Supported API frame of the display. Section 5.4 API frame is the reference of its enumerated values. Default setting of this parameter is that it doesn't support any enumerated value, unless specified |
battr |
integer array |
No |
Restrictions of material attributes. Section 5.3 Creative attribute list is the reference of its enumerated values |
Parameter name |
Type |
Required? |
Description |
assets |
object array |
Yes |
Use asset request object to show the requirement of Native ad for assets and other elements. All assets and other elements should follow this request object |
ver |
string |
Yes |
Native Markup version, default version is 1.2 |
context |
integer |
No |
Ad context. Section 5.10 Context Type IDs is the reference of its enumerated values |
contextsubtype |
integer |
No |
Ad context in more details. Section 5.11 Context Sub Type IDs is the reference of its enumerated values |
Parameter name |
Type |
Required? |
Description |
id |
integer |
Yes |
The only identification ID of the object |
required |
integer |
Yes |
Indicate if the asset object is a must-have for client (bidder) in order to get a bid accepted. Value of 1 means yes. Value of 0 means it is not necessary |
title |
object |
No |
Title object for title assets. Refer to title object |
img |
object |
No |
Image object for image assets. Refer to img object |
video |
object |
No |
Video object for video assets. Refer to video object |
data |
object |
No |
Data object for data assets, eg. brand, description, rating, pricing etc.Refer to data object |
Parameter name |
Type |
Required? |
Description |
len |
integer |
Yes |
Maximum title text length. Recommended text length is 25, 90, 140 characters |
Parameter name |
Type |
Required? |
Description |
type |
integer |
Yes |
Indicate the specific type of image. Icon image: Value = 1 Large image: Value = 3 |
w |
integer |
No |
Image width |
wmin |
integer |
Yes |
Minimum image width. Unit is in pixels |
h |
integer |
No |
Image height / length |
hmin |
integer |
Yes |
Minimum image height / length. Unit is in pixels |
mimes |
string array |
No |
Supported image mime-type, including but not limited to ‘image/jpg’and ‘image/gif’ |
Parameter name |
Type |
Required? |
Description |
mimes |
string array |
Yes |
Supported content mime-type. Currently it only supports ‘video/mp4’ |
minduration |
integer |
Yes |
Minimum video ad length. Unit is in seconds |
maxduration |
integer |
Yes |
Maximum video ad length. Unit is in seconds |
protocols |
integer array |
Yes |
Applicable video protocol for DSP in Bid Response. Currently it only supports type 3, i.e. vast 3.0 protocol |
Parameter name |
Type |
Required? |
Description |
type |
string array |
Yes |
Indicate data object type ID. Each data object has a specific type. Section 5.12 Data Asset Type is the reference of its enumerated values |
len |
integer |
Yes |
Maximum number of characters allowed |
Parameter name |
Type |
Required? |
Description |
id |
string |
No |
Internal definition of app ID |
name |
string |
No |
Internal definition of app name |
bundle |
string |
Yes |
App package name info |
domain |
string |
No |
App domain name, eg. mygame.foo.com |
cat |
string array |
No |
App IAB category.Section 5.1 IAB category is the reference of its enumerated values |
ver |
string |
No |
App version |
DSP |
object |
Yes |
DSP info.Refer to DSP object |
Parameter name |
Type |
Required? |
Description |
id |
string |
Yes |
DSP ID, to apply for token info |
name |
string |
No |
DSP name |
domain |
string |
No |
DSP's highest domain name, eg. ‘DSP.com’ |
cat |
string array |
No |
App IAB category. Section 5.1 IAB category is the reference of its enumerated values |
Parameter name |
Type |
Required? |
Description |
ua |
string |
Yes |
User-Agent field in HTTP request thread of user device |
ip |
string |
Yes |
ipv4 address of user's current network |
geo |
object |
Yes |
Current geographic info of user. Refer to geo object |
didsha1 |
string |
No |
Hardware device ID (eg. IMEI), via SHA1 hash |
didmd5 |
string |
No |
Hardware device ID (eg. IMEI), via MD5 hash |
dpidsha1 |
string |
No |
Platform device ID (eg. Android ID), via SHA1 hash |
dpidmd5 |
string |
No |
Platform device ID (eg. Android ID), via MD5 hash |
macsha1 |
string |
No |
Device MAC address, via SHA1 hash |
macmd5 |
string |
No |
Device MAC address, via MD5 hash |
make |
string |
No |
Device manufacturer (eg. ‘Apple’) |
model |
string |
No |
Device model (eg. ‘iPhone’) |
os |
string |
Yes |
Operation system (eg. Android, iOS) |
osv |
string |
No |
Operation system version |
language |
string |
No |
Device language, following ISO-639-1-alpha-2. If unknown, put ‘unknown’ |
connectiontype |
integer |
No |
Network connection mode. Section 5.8 Network Connection Mode is the reference of its enumerated values |
devicetype |
integer |
No |
Device type. Section 5.7 Device type is the reference of its enumerated values |
h |
integer |
No |
Screen physical height / length.Unit is in pixels |
w |
integer |
No |
Screen physical width.Unit is in pixels |
js |
integer |
No |
Indicate if js is supported. Value of 0 means not supported. Value of 1 means supported. |
ppi |
integer |
No |
Screen size.Unit is in pixel per inch |
dnt |
integer |
No |
‘Do Not Track’ identification set by browser in HTTP thread. Value of 0 means tracking is not restricted. Value of 1 means tracking is restricted / not allowed. |
lmt |
integer |
No |
Indicate user's authorization for ad tracking. Value of 0 means tracking is not restricted. Value of 1 means tracking is restricted / not allowed. |
ifa |
string |
Yes |
Identification used by client.Andorid: gaid, iOS: idfa |
mccmnc |
string |
No |
Mobile network carrier |
Parameter name |
Type |
Required? |
Description |
lat |
float |
No |
Latitude info, data range is (-90.0,+90.0). Negative value means South |
lon |
float |
No |
Longitude info, data range is (-180.0,+180.0). Negative value means West. |
type |
integer |
No |
Source type of geo info. Value of 1 means by GPS/Location service. Value of 2 means by IP address. Value of 3 means provided by user.Section 5.13 Location Typeis the reference of its enumerated values |
accuracy |
integer |
No |
Accuracy in meters. When latitude/longitude info is obtained by GPS/Location service, this field is reported. |
ipservice |
integer |
No |
IP address provider, applicable for type = 2.Section **5.14 IP Location Type **is the reference of its enumerated values |
country |
string |
Yes |
Country code following ISO-3166-1-alpha-3 |
region |
string |
No |
Region code following ISO-3166-2.If country is USA, 2-letter state code is used |
city |
string |
No |
City code following UN/LOCODE |
zip |
string |
No |
Postal code |
utcoffset |
integer |
No |
Local time difference from UTC time, +/- in minutes |
Parameter name |
Type |
Required? |
Description |
id |
string |
No |
User ID |
buyeruid |
string |
No |
User ID defined by buyer |
gender |
string |
No |
Gender. Value of M means male, F means female, 0 means other gender. |
geo |
object |
No |
User geo info |
yob |
integer |
No |
Year of birth, 4-digit number. |
keywords |
string |
No |
Keywords list of user's interests / intentions list, separated by comma (,) |
customdata |
string |
No |
Customized data |
data |
object array |
No |
Extra user data. Each data object represents a different data source |
Parameter name |
Type |
Required? |
Description |
id |
string |
No |
ID of data provider |
name |
string |
No |
Name of data provider |
segment |
object array |
No |
Data segment that includes the actual data info.Refer to segment object |
Parameter name |
Type |
Required? |
Description |
id |
string |
No |
Segment ID defined by data provider |
name |
string |
No |
Segment name defined by data provider |
value |
string |
No |
Segment value |
Parameter name |
Type |
Required? |
Description |
id |
string |
Yes |
Identification for Bid Request, i.e. request id included in Bid Request section above |
seatbid |
object array |
Yes |
One set of SeatBid object. If a bid is offered, at least one SeatBid is filled in |
bidid |
string |
No |
Response ID generated for each bidder, assisting with logs or tracking transaction |
cur |
string |
No |
Unit of bid currency used, code following ISO-4217. If left blank, USD is used by default |
ext |
object |
No |
Placeholder for bidder-specific extensions to OpenRTB |
Midas only supports 1 seatbid object to be responded at a time, and 1 seatbid only supports 1 bid to be responded.
Parameter name |
Type |
Required? |
Description |
bid |
object array |
Yes |
Array that includes at least 1 bid object. Each object is related to 1 display / impression |
seat |
string |
No |
Seat identification that represents the client (bidder, eg. advertiser, agency) on whose behalf this bid is made |
group |
interger |
No |
Indicate if all bids can win or fail at the same time. Default value is 0, meaning independent bid is allowed. Value of 1 means a group of bids win or fail at the same time. |
ext |
object |
No |
Placeholder for bidder-specific extensions to OpenRTB |
Each bid object must have a corresponding imp id, indicating the bid is offered for the specific impression.
Parameter name |
Type |
Required? |
Description |
id |
string |
Yes |
Bid ID generated for each bidder, used for recording logs or tracking acitivity |
impid |
string |
Yes |
ID of imp object related to a Bid request |
price |
float |
Yes |
CPM price for each display |
adid |
string |
No |
Preloaded ad ID that can be used when a bid offer wins |
nurl |
string |
No |
Nurl link for notification when a bid wins, and will then be used by transaction platform |
burl |
string |
Yes |
Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g.,typically delivered, viewed, etc.).Substitution macros ${AUCTION_PRICE} may be included |
adm |
string |
Yes |
Convey ad content.Native ad uses adm field to return ad content. Refer to native ad response below for more detailsVideo ad uses adm field to return ad content in vast format. Refer to vast video response below for more details |
adomain |
string array |
No |
Domain name of client, used for filtering check |
bundle |
string |
Yes for install ads |
App package name, eg. Android package name: com.foo.mygame, iOS package name: id907394059 |
iurl |
string |
No |
Image link to indicate ad campaign content, used for quality or security tracking |
cid |
string |
No |
Campaign ID, to assist with ad QC. Each cid has one set of creatives, which is the creatives represented by iurl |
crid |
string |
No |
ID of a set of creatives, to assist with ad QC |
cat |
string array |
Yes |
IAB category of creative.Section 5.1 IAB category is the reference of its enumerated values |
attr |
integer array |
No |
Attribute array to describe creative.Section 5.3 Creative attribute list is the reference of its enumerated values |
api |
integer |
No |
Supported API frame of the display. Section 5.4 API frame is the reference of its enumerated values |
protocol |
integer |
No |
Supported video Bid Response protocol. Section 5.6 Video bid response protocol is the reference of its enumerated values |
qagmediarating |
integer |
Yes |
Indicate rating of creative content following IQG standard.Section 5.9 IQG media rating is the reference of its enumerated values |
dealid |
string |
No |
Refer to deal.id****from the bid request if this bid pertains to a private marketplace direct deal |
w |
integer |
No |
Creative width. Unit is in pixels |
h |
integer |
No |
Creative height. Unit is in pixels |
exp |
integer |
No |
Duration that the bidder is willing to wait between the auction and the actual display / impression.Unit is in seconds, with default value of 3600 |
ext |
object |
No |
Placeholder for bidder-specific extensions to OpenRTB |
Native ad response content is saved in adm field, with the content including 1 native object. Native format supports native version 1.2 protocol.
Native object has following attributes:
Parameter name |
Type |
Required? |
Description |
ver |
string |
No |
Native Markup version in use |
assets |
array of objects |
Yes |
List of native ad's assets.Refer to asset response object |
link |
object |
Yes |
Destination link if the ad is clicked.Refer to link object |
imptrackers |
array of string |
Yes |
Array of impression tracking URLs.When a display / impression happens, tracking URLs are reported and used as the reference for cost calculation |
ext |
Object |
No |
Placeholder that may contain custom JSON |
Asset response object must strictly follow asset object in the Bid Request. Each object corresponds to an ID, which matches with the asset request object ID.
Parameter name |
Type |
Required? |
Description |
id |
int |
Yes |
Asset ID that matches with ID in Bid Request |
required |
int |
No |
Set to 1 if asset is required (bidder requires it to be displayed) |
title |
object |
No |
Title object for title assets. Refer to title object |
img |
object |
No |
Image object for image assets. Refer to img object |
video |
object |
No |
Video object for video assets. Refer to video object |
data |
object |
No |
Data object for data assets, eg. rating, pricing.Refer to data object |
ext |
object |
No |
Placeholder that may contain custom JSON |
Parameter name |
Type |
Required? |
Description |
text |
string |
Yes |
Title text |
len |
integer |
No |
Length of title text |
ext |
object |
No |
Placeholder that may contain custom JSON |
Parameter name |
Type |
Required? |
Description |
type |
integer |
No |
Required for assetsurl or dcourl responses, not required for embedded asset responsesIcon image: Value = 1 Large image: Value = 3 |
url |
string |
Yes |
URL of the image asset |
w |
integer |
Yes |
Image width in pixels |
h |
integer |
Yes |
Image height in pixels |
ext |
object |
No |
Placeholder that may contain custom JSON |
Parameter name |
Type |
Required? |
Description |
type |
integer |
No |
Type ID of data element, must follow 5.12 Data Asset Typeif to be submitted |
label |
string |
No |
Name of data element, must follow 5.12 Data Asset Typeif to be submitted |
value |
string |
Yes |
Formatted string of data, based on the requirement of each data type |
ext |
object |
No |
Placeholder that may contain custom JSON |
Video response object uses vasttag parameter for video content in vast format.
Note: Video in native ad response is just one type of assets. Therefore, it doesn't support impression and click tracking that aims only at video. Instead, it can support tracking of the rate of progress when a video is being played.
Parameter name |
Type |
Required? |
Description |
vasttag |
string |
Yes |
Indicate video content in vast format |
Parameter name |
Type |
Required? |
Description |
url |
string |
Yes |
Landing URL of the clickable link |
clicktrackers |
array of strings |
No |
List of third-party tracker URLs tobe fired on click of the URL |
ext |
object |
No |
Placeholder that may contain custom JSON |
Value |
Description |
IAB1 |
Arts & Entertainment |
IAB1-1 |
Books & Literature |
IAB1-2 |
Celebrity Fan/Gossip |
IAB1-3 |
Fine Art |
IAB1-4 |
Humor |
IAB1-5 |
Movies |
IAB1-6 |
Music |
IAB1-7 |
Television |
IAB2 |
Automotive |
IAB2-1 |
Auto Parts |
IAB2-2 |
Auto Repair |
IAB2-3 |
Buying/Selling Cars |
IAB2-4 |
Car Culture |
IAB2-5 |
Certified Pre-Owned |
IAB2-6 |
Convertible |
IAB2-7 |
Coupe |
IAB2-8 |
Crossover |
IAB2-9 |
Diesel |
IAB2-10 |
Electric Vehicle |
IAB2-11 |
Hatchback |
IAB2-12 |
Hybrid |
IAB2-13 |
Luxury |
IAB2-14 |
Minivan |
IAB2-15 |
Motorcycles |
IAB2-16 |
Off-Road Vehicles |
IAB2-17 |
Performance Vehicles |
IAB2-18 |
Pickup |
IAB2-19 |
Road-Side Assistance |
IAB2-20 |
Sedan |
IAB2-21 |
Trucks & Accessories |
IAB2-22 |
Vintage Cars |
IAB2-23 |
Wagon |
IAB3 |
Business |
IAB3-1 |
Advertising |
IAB3-2 |
Agriculture |
IAB3-3 |
Biotech/Biomedical |
IAB3-4 |
Business Software |
IAB3-5 |
Construction |
IAB3-6 |
Forestry |
IAB3-7 |
Government |
IAB3-8 |
Green Solutions |
IAB3-9 |
Human Resources |
IAB3-10 |
Logistics |
IAB3-11 |
Marketing |
IAB3-12 |
Metals |
IAB4 |
Careers |
IAB4-1 |
Career Planning |
IAB4-2 |
College |
IAB4-3 |
Financial Aid |
IAB4-4 |
Job Fairs |
IAB4-5 |
Job Search |
IAB4-6 |
Resume Writing/Advice |
IAB4-7 |
Nursing |
IAB4-8 |
Scholarships |
IAB4-9 |
Telecommuting |
IAB4-10 |
U.S. Military |
IAB4-11 |
Career Advice |
IAB5 |
Education |
IAB5-1 |
7-12 Education |
IAB5-2 |
Adult Education |
IAB5-3 |
Art History |
IAB5-4 |
College Administration |
IAB5-5 |
College Life |
IAB5-6 |
Distance Learning |
IAB5-7 |
English as a 2nd Language |
IAB5-8 |
Language Learning |
IAB5-9 |
Graduate School |
IAB5-10 |
Homeschooling |
IAB5-11 |
Homework/Study Tips |
IAB5-12 |
K-6 Educators |
IAB5-13 |
Private School |
IAB5-14 |
Special Education |
IAB5-15 |
Studying Business |
IAB6 |
Family & Parenting |
IAB6-1 |
Adoption |
IAB6-2 |
Babies & Toddlers |
IAB6-3 |
Daycare/Pre School |
IAB6-4 |
Family Internet |
IAB6-5 |
Parenting - K-6 Kids |
IAB6-6 |
Parenting teens |
IAB6-7 |
Pregnancy |
IAB6-8 |
Special Needs Kids |
IAB6-9 |
Eldercare |
IAB7 |
Health & Fitness |
IAB7-1 |
Exercise |
IAB7-2 |
ADD |
IAB7-3 |
AIDS/HIV |
IAB7-4 |
Allergies |
IAB7-5 |
Alternative Medicine |
IAB7-6 |
Arthritis |
IAB7-7 |
Asthma |
IAB7-8 |
Autism/PDD |
IAB7-9 |
Bipolar Disorder |
IAB7-10 |
|