Id
En Ru
API
Effective date: Jan 2024

1. Bugdet - Xtend-DSP RTB Integration (DSP)

Xtend-DSP RTB Integration

1 Overview

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.

 

2 Steps for Integration

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.

 

3 Real Time Bid

3.1 Data Transmission

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.

 

3.2 HTTP Request

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

3.3 HTTP Response

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.

 

3.4 Display Volume and Cost Calculation

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.

3.5 Precautions

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

4 Real Time Bid RTB Interface Parameter

4.1 Bid Request

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

4.1.1 imp object

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

 

4.1.2 banner object

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

4.1.3 native object

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

 

4.1.4 native request object

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

 

4.1.5 asset request object

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

 

4.1.6 title object

Parameter name

Type

Required?

Description

len

integer

Yes

Maximum title text length. Recommended text length is 25, 90, 140 characters

 

4.1.7 img object

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’

 

4.1.8 video object

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

 

4.1.9 data object

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

 

4.1.10 app object

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

 

4.1.11 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

 

4.1.12 device object

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

 

4.1.13 geo object

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

 

4.1.14 user object

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

 

4.1.15 data object

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

 

4.1.16 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

 

4.2 Bid Response

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

4.2.1 seatbid object

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

 

4.2.2 bid object

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

 

4.2.3 native ad response

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

 

4.2.4 asset response object

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

 

4.2.5 title object

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

 

4.2.6 Img object

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

 

4.2.7 data object

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

 

4.2.8 video object

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

 

4.2.9 link object

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

5 RTB Interface Enumerated Value List

5.1 IAB Category Enumerated Value

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