Bid Request Objects

Edited

ConnectAd supports Ad-Request integration using OpenRTB 2.5. This document provides Bid Request Objects and Parameters for the OpenRTB Ad Serving integration.

Objects and Parameters Supported

Supported objects and parameters are listed in the following table, with required/optional indicators. Requests that do not contain required objects and parameters will be considered invalid.

Object: BidRequest

Attribute

Type

Description

Scope

id

String

Unique ID of the bid request, provided by the exchange.

Required

imp

Object Array

Array of impression objects representing the impressions offered. At least 1 impression object is required.

Required

site

Object

Details via a site object about the publisher's website.

Required

device

Object

Details via a device object about the user's device to which the impression will be delivered.

Required

user

Object

Details via a user object about the human user of the device; the advertising audience.

Optional

app

Object

Details via an App object about the publisher's app (i.e., non-browser applications). Only applicable and recommended for apps.

Optional

at

Integer

Auction Type
Default = 1
1 = Publisher first price auction
2 = Publisher second price auction

Optional

cur

String Array

Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes.

Optional

bcat

String Array

Blocked advertiser categories using the IAB content categories. (max 25)

Optional

badv

String Array

Block list of advertisers by their domains (max 50)

Optional

regs

Object

A Regs object that specifies any industry, legal, or governmental regulations in force for this request.

Optional

tmax

Integer

The maximum time in milliseconds to submit a bid to avoid timeout.

Optional

Object: Imp

Attribute

Type

Description

Scope

id

String

A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).

Required

tagid

String

Identifier for specific ad placement or ad tag that was used to initiate the auction.

Required

banner

Object

A banner object is required if this impression is offered as a banner ad opportunity.

Required

native

Object

A Native object; required if this impression is offered as a native ad opportunity

Currently not supported

video

Object

A Video object required if this impression is offered as a video ad opportunity.

Currently not supported

bidfloor

Float

Minimum bid for this impression expressed in CPM.

Optional

bidfloorcur

String

Currency specified using ISO-4217 alpha codes.

Optional

iframebuster

String Array

Array of exchange-specific names of supported iframe busters

Optional

secure

Integer

Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure.

Optional

Object: Banner

Attribute

Type

Description

Scope

w

Integer

Width of the impression in pixels.

Required

h

Integer

Height of the impression in pixels.

Required

battr

Integer Array

Blocked creative attributes.

Optional

pos

Integer

Ad position on screen.

Optional

topframe

Integer

Indicates if the banner is in the top frame as opposed to an iframe, where 0 = no, 1 = yes.

Optional

format

Object Array

Array of format objects representing the banner sizes permitted. If non are specified, then use of the h and w attributes is highly recommended.

Recommended

Object: Format

Attribute

Type

Description

Scope

w

Integer

Width in device independent pixels (DIPS).

Required

h

Integer

Height in device independent pixels (DIPS).

Required

Object: App

Attribute

Type

Description

Scope

id

String

Mobile applications ID on the exchange.

Optional

name

String

App name (may be aliased upon request)

Optional

publisher

Object

Details about the Publisher

Optional

bundle

String

Application bundle or package name. Intended to be a unique ID across exchanges.

Optional

domain

String

Domain of the app.

Optional

storeurl

String

App store URL for an installed app; for QAG 1.5 compliance.

Optional

cat

String Array

Array of IAB content categories of the app.

Optional

sectioncat

String Array

Array of IAB content categories that describe the current section of the app.

Optional

pagecat

String Array

Array of IAB content categories that describe the current page or view of the app.

Optional

ver

String

Application version

Optional

privacypolicy

Integer

Indicates if the app has a privacy policy, where 0=no, 1=yes

Optional

paid

Integer

0=app is free, 1=app is a paid version

Optional

keywords

String

comma separated list of keywords about the app

Optional

content

Object

Details of the content in the app.

Optional

Object: Device

Attribute

Type

Description

Scope

ua

String

Browser user agent string.

Required

dnt

Integer

Standard "Do Not Track" flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track

Optional

lmt

Integer

"Limit Ad Tracking" signal commercially endorsed

Optional

devicetype

Integer

The general type of device.

Optional

make

String

Device make

Optional

model

String

Device model

Optional

os

String

Device operating system

Optional

osv

String

Device operating system version

Optional

hwv

String

Hardware version of the device

Optional

h

Integer

Physical height of the screen in pixels.

Optional

w

Integer

Physical width of the screen in pixels.

Optional

ppi

Integer

Screen size as pixels per linear inch.

Optional

pxratio

float

The ratio of physical pixels to device independent pixels.

Optional

js

Integer

Support for JavaScript, where 0=no, 1=yes.

Optional

flashver

string

Version of Flash supported by the browser.

Optional

language

String

Browser language using ISO-639-1-alpha-2.

Optional

geo

Object

Location of the device assumed to be the user's current location defined by a Geo object. This will be given lower priority in respect to user.geo object.

Optional

Ip

String

IPv4 address closest to device as IPv6. Either of ip/ipv6 is required.

Required

Ipv6

String

IP address closest to device as IPv6. Either of ip/ipv6 is required.

Required

ifa

String

ID sanctioned for advertiser use in the clear (i.e., not hashed)

Optional

didsha1

String

Hardware device ID *e.g., IMEI; hashed via SHA1.

Optional

didmd5

String

Hardware device ID *e.g., IMEI; hashed via MD5.

Optional

dpidsha1

String

Platform device ID (e.g., Android ID); hashed via SHA1.

Optional

dpidmd5

String

Platform device ID (e.g., Android ID); hashed via MD5.

Optional

macsha1

String

MAC address of the device; hashed via SHA1.

Optional

macmd5

String

MAC address of the device; hashed via MD5.

Optional

Object: Site

Attribute

Type

Description

Scope

id

String

Exchange-specific site ID.

Required

cat

String Array

Array of IAB content categories of the site.

Optional

page

String

URL of the page where the impression will be shown. ref string Referrer URL that caused navigation to the current page. It must not be encoded.

Required

ref

String

Referrer URL that caused navigation to the current page.

Optional

pagecat

String Array

Array of IAB content categories that describe the current page or view of the site.

Optional

publisher

Object

Details about the Publisher

Optional

content

Object

Details about the content within the site.

Optional

Object: Geo

Attribute

Type

Description

Scope

lat

Float

Latitude from -90.0 to +90.0, where negative is south

Optional

lon

Float

Longitude from -180.0 to +180.0, where negative is west.

Optional

type

Integer

Source of location data; recommended when passing lat/lon.

Optional

country

String

Country code using ISO-3166-1-alpha-3.

Optional

region

String

Region code using ISO-3166-2; 2-letter state code if USA

Optional

metro

String

Google metro code; similar to but not exactly Nielsen DMAs.

Optional

city

String

City using United Nations Code for Trade & Transport Locations. It must not be encoded

Optional

zip

String

Zip or postal code

Optional

Object: User

Attribute

Type

Description

Scope

buyeruid

String

Buyer-specific ID for the user as mapped by the exchange for the buyer.

id or buyeruid required

yob

Integer

Year of birth as a 4-digit integer

Optional

gender

String

Gender, where "M" = male, "F" = female, "O" = known to be other (i.e., omitted is unknown).

Optional

geo

Object

Location of the user's home base defined by a Geo object. This is not necessarily their current location. This will be given higher preference over device.geo object

Optional

id

String

Exchange-specific ID for the user.

id or buyeruid required

eids

Object Array

An array of Extended ID objects.

Optional

Object: User Extension Object

Attribute

Type

Description

Scope

gdpr

Integer

Possible values: 0 or 1 to indicate if the impression is GDPR regulated or not.

Optional

consent

String

If the above flag is 1, then this string gives consent information of various vendors

Optional

Object: Regs

Attribute

Type

Description

Scope

coppa

Integer

Flag indicating if this request is subject to the COPPA regulations established by the USA FTC, where 0 = no, 1 = yes.

Optional

Object: Regs Extension

Attribute

Type

Description

Scope

gdpr

Integer

Possible values: 0 or 1 to indicate whether or not the impression is gdpr regulated.

Optional

JSON

"regs": {"ext": {"gdpr": 1}}‍‍‍‍‍‍‍

Object: Publisher

Attribute

Type

Description

Scope

id

String

Exchange-specific publisher ID

Required

Object: Source

Attribute

Type

Description

Scope

fd

Integer

Entity responsible for the final impression sale decision, where 0=exchange, 1=upstream source.

Optional

tid

String

Transaction ID that must be common across all participants in the bid request (e.g., potentially multiple exchanges)

Optional

pchain

String

Payment ID chain string containing embedded syntax described in the TAG Payment ID Protocol v. 1.0

Optional

ext

Object

laceholder for exchange-specific extensions to OpenRTB

Optional