Quick Help

The knowledgebase is a categorized collection of answers to frequently asked questions (FAQ) and articles. You can read articles in this category or select a subcategory that you are interested in.



 OpenRTB supply-side ad request parameter values

Solution

Last updated on February 2, 2017

To better characterize your inventory, you can send additional data about your ad units to buyers in the PixFuture SSP using OpenRTB 2.3 values. You do not need to pass all OpenRTB values because PixFuture automatically identifies and passes many of them for you.

The openrtb ad request parameter supports a percent-encoded string generated from JSON objects with supported OpenRTB values.

Sample openrtb parameter included in an ad request:

The following ad request shows how you can include various ad request parameters—including the openrtb parameter, which specifies a percent-encoded string.

http://ax-d.pixfuture.net/w/1.0/acj? o=7889550390&callback=OX_7889550390&auid=537627288&res=320x568x32&plg=qt%2Cpm&ch=UTF-8&tz=420&ws=320x50&sd=1&openrtb=%7B%22cur%22%3A%20%5B%22USD%22%5D%2C%20%22site%22%3A %20%7B%22publisher%22%3A%20%7B% 22domain%22%3A%20%22foobar.com%22%2C%20%22cat%22%3A%20%5B%22IAB3-1%22%5D%2C%20%22id%22%3A %20%228953%22%2C%20%22name%22% 3A%20%22foobar.com%22%7D%2C%20%22domain%22%3A%20%22www.example.com%22%2C%20%22page%22%3A%20%22http %3A//www.example.com/1234.html%20%22%2C%20%22id%22%3A%20%22102855%22%2C%20%22cat%22%3A%20%5B%22IAB3-1%22%5D%7D%2C %20%22imp%22%3A%20%5B%7B% 22banner%22%3A%20%7B%22h%22%3A%20250%2C%20%22pos%22%3A%200%2C%20%22w%22%3A%20300%7D%2C%20%22id %22%3A%20%221%22%2C%20% 22bidfloor%22%3A%200.03%7D%5D%2C%20%22at%22%3A%201%2C%20%22device%22%3A%20%7B%22ip%22%3A %20%22123.145.167.10%22%2C%20% 22ua%22%3A%20%22Mozilla/5.0%20%28Macintosh%3B%20Intel%20Mac%20OS%20X %2010_6_8%29%20AppleWebKit/537.13%20%28KHTML%2C% 20like%20Gecko%29%20Version/5.1.7%20Safari/534.57.2%22%7D%2C%20%22id%22%3A %20%2280ce30c53c16e6ede735f123ef6e32361bfc7b22 %22%2C%20%22user%22%3A%20%7B%22id%22%3A%20%2255816b39711f9b5acf3b90e313ed29e51665623f%22%7D%7D

Where:

·       http is the protocol. If your ad space uses SSL/TLS, use https instead.

·       ax-d.pixfuture.net. The hostname delivery server

·       /w. Indicates the web delivery medium

·       /1.0. Indicates version 1.0 of the PixFuture ad request protocol

·       /acj. Asynchronous chain JSON, an asynchronous ad request to serve a structured JSON delivery response which supports chaining

·       ?. Separates the ad request from the ad request parameters

·       auid. The ad unit ID

·       &. Separates each parameter

·       &openrtb=. Indicates the OpenRTB values that follow in a percent-encoded string

Sample JSON object including OpenRTB values

The following JSON object shows the structure of the OpenRTB data before removing unnecessary white space and before percent encoding.

 {'cur':['USD'],  'device':{'ip':'123.145.167.10',              'ua':'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_6_8) AppleWebKit/537.13 (KHTML, like Gecko) Version/5.1.7 Safari/534.57.2'},  'id':'80ce30c53c16e6ede735f123ef6e32361bfc7b22',  'imp':[{'banner':{'h':250,'pos':0,'w':300},            'bidfloor':0.03,            'id':'1'}],  'site':{'cat':['IAB3-1'],           'domain':'www.example.com',           'id':'102855',           'page':'http://www.example.com/1234.html ',           'publisher':{'cat':['IAB3-1'],                         'domain':'example.com',                         'id':'8953',                         'name':'example.com'}}}        

Where:

·       cur. Corresponds to the BidRequest.cur field, which specifies that the currency is in U.S. dollars

·       device. Corresponds to the BidRequest.device field, which specifies a Device object array

·       id. Corresponds to the BidRequest.id field, which specifies the unique ID of the bid request

·       imp. Corresponds to the BidRequest.imp field, which specifies an Imp (impression) object array, which in turn specifies various Banner object fields

·       site. Corresponds to the BidRequest.site field, which specifies a Site object array, which in turn specifies the Publisher object

To improve performance, remove all unneeded white space and line breaks from your JSON object before generating a percent-encoded version of it as shown in the following example.

JSON string prepared for percent-encoding:

{"cur":["USD"],"site":{"publisher":{"domain":"example.com","cat":["IAB3-1"],"id":"8953","name":"example.com"},"domain":  "www.example.com","page":"http://www.example.com/1234.html ","id":"102855","cat":["IAB3-1"]},"imp":[{"banner":{"h":250,  "pos":0,"w":300},"id":"1","bidfloor":0.03}],"device":{"ip":"123.145.167.10","ua": "Mozilla/5.0(Macintosh; Intel Mac OS X  10_6_8) AppleWebKit/537.13(KHTML, like Gecko) Version/5.1.7 Safari/534.57.2"}, "id": "80ce30c53c16e6ede735f123ef6e32361bfc7b22"}

You can pass as many supported OpenRTB fields as you find useful to characterize your inventory except for those that cannot be passed by publishers.

Commonly-targeted OpenRTB fields

PixFuture strongly recommends the following fields because many buyers target them:

·       BidRequest.app.bundle

·       BidRequest.app.name

·       BidRequest.imp.banner.api

·       BidRequest.imp.native.api

Recommended OpenRTB fields

The following fields are recommended because they provide the most value to buyers.

 

Object name

Field name

Data type

Description

BidRequest.app

bundle

string

The unique ID of the app's package (Android), bundle (iOS), or its AppStore ID.

For example: "com.demo.pixfuture" or "123456789"

BidRequest.app

cat

array (string)

The list of IAB content categories for the app, as defined in table 5.1 (Content Categories) of the OpenRTB API specification

BidRequest.app

keywords

string

A comma-separated list of keywords describing the app

BidRequest.app

name

string

The name of the app

BidRequest.app

storeurl

string

The app store URL for this app

BidRequest.app.content

keywords

string

A comma-separated list of keywords describing the app's content

BidRequest.device

carrier

string

The mobile carrier for the user's device as derived from the IP address and expressed by the mobile country code (MCC) and mobile network code (MCC-MNC)

For example: "310-410"

Ad Exchange buyers will expect an MCC-MNC code, so sending the name of the carrier may not be parsed correctly by the buyer's system.

BidRequest.device

connectiontype

integer

Indicates the detected data connection type for the user’s device as defined in table 5.18 (Connection Type) of the OpenRTB specification

BidRequest.device

devicetype

integer

Indicates the detected device category for the user’s device as defined in table 5.17 (Device Type) of the OpenRTB specification

Note: PixFuture OpenRTB uses a devicetype value of1001 to indicate text (SMS).

BidRequest.device

didsha1

string

The SHA-1 hash identifier for the user’s device, such as the UDID for an iOS device

For example: 2b6f0cc904d137be2e1730235f5664094b831186

BidRequest.device

dpidmd5

string

The MD5 hash of the Android ID for the end-user's mobile device

BidRequest.device

dpidsha1

string

The SHA-1 hash of the Android ID for the end-user's mobile device

BidRequest.device

ifa

string

ID for advertisers (also referred to as "IDFA")

This is the ID sanctioned for advertiser use in the clear (not hashed).

BidRequest.device

lmt

integer

If the user’s mobile device is set for private browsing, the LMT (limit tracking) flag is passed.

·       0 = false

·       1 = true (the user does not want to be tracked.)

BidRequest.device

macmd5

string

The MD5 hash of the device's MAC address

BidRequest.device

macsha1

string

The SHA-1 hash of the device's MAC address

BidRequest.device.geo

lat

float

The user’s latitude

For example: 33.684

BidRequest.device.geo

lon

float

The user’s longitude

For example: -117.793

BidRequest.device.geo

type

integer

Indicates the source of the user’s geographic location details, as defined in table 5.16 (Location Type) of the OpenRTB API specification. For example, this field can indicate whether the lat or lon is derived from the device's GPS location or an IP address.

BidRequest.imp

displaymanager

string

The name of the mediation partner or other third party responsible for rendering the ad

BidRequest.imp.banner

api

 

array (integer)

One of the supported API standards or frameworks:

·       1 - VPAID 1.0

·       2 - VPAID 2.0

·       3 - MRAID 1.0

·       4 - ORMMA

·       5 - MRAID 2.0

For example: "1, 2"

For details, see table 5.6 (API Frameworks) of the OpenRTB API specification.

BidRequest.imp.native

api

 

array (integer)

One of the supported API standards or frameworks:

·       1 - VPAID 1.0

·       2 - VPAID 2.0

·       3 - MRAID 1.0

·       4 - ORMMA

·       5 - MRAID 2.0

BidRequest.regs

coppa

integer

Indicates whether the request is subject to Children’s Online Privacy Protection Act (COPPA) regulations

·       0 = false

·       1 = true (the request is subject to COPPA)

BidRequest.regs.ext

sb568

integer

Indicates whether the request is subject to California’s SB-568 regulations

·       0 = false

·       1 = true (the request is subject to SB-568)

BidRequest.site

keywords

string

A comma-separated list of keywords describing the site

BidRequest.site.content

keywords

string

A comma-separated list of keywords describing the site's content

BidRequest.user

keywords

string

A comma-separated list of keywords describing the user's interests

BidRequest.user.geo

lat

float

The user’s latitude

For example: 33.684

BidRequest.user.geo

lon

float

The user’s longitude

For example: -117.793

BidRequest.user.geo

type

integer

Indicates the source of the user’s geographic location details, as defined in table 5.16 (Location Type) of the OpenRTB API specification. For example, this field can indicate whether the lat or lon is derived from the device's GPS location or an IP address.