Ox RTB Api v10

OpenX Market
Real-time Bidding API Reference

Version 10
OpenX Market Real-time Bidding API Reference--Version 10-Updated 04/03/2013

2
2013 OpenX Ltd.
Copyright in this document is the property of OpenX Ltd. and its contents shall be held in strict
confidence by the recipient hereof and shall be used solely for the purposes of doing business
with OpenX Ltd. Neither this document nor its content shall be disclosed to any other person or
used for any other purpose without prior written permission of OpenX Ltd.
OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

3
Overview! 5
How real-time bidding works! 5
About this document! 5
Whats new in this version?! 5
Terms and definitions! 6
What you need to do! 6
Configuring accounts! 6
RTB account attributes! 7
Setting up campaigns ! 8
RTB campaign attributes! 8
Setting up placements ! 9
RTB placement attributes! 9
Setting up creatives! 10
RTB creative attributes! 10
Testing your RTB implementation! 11
Runtime workflow description! 12

BidRequest ! 13
AdId structure! 16
Device structure! 17
Geo structure! 19
Deal structure! 20
DealPricingType! 21
DealExclusivity! 21
ThirdPartyKeyValue! 21

4
Additional HTTP headers! 21
BidResponse! 22
About micros! 22
Bid structure! 24
Macros! 24
About the winning_price macro! 25
Price encrypting scheme! 25
AuctionResults! 25
AuctionResult structure! 26
AuctionStatus structure! 27
User mapping! 28
Using the RTB data URL! 28
Using the cookie-mapping URL! 29

5
Overview
OpenX provides a real-time bidding interface, which allows buyers to make real-time buying
decisions when sourcing mobile or display inventory from OpenX Market.
How real-time bidding works

Real-time bidding in OpenX is a server-to-server interaction between OpenX Market and its
bidders. Any available information relevant to the opportunity is passed to a bidder from OpenX
Markets serving infrastructure. OpenX Market communicates with bidders using protocol buffers
(http://code.google.com/p/protobuf/) via HTTP. The following high-level workflow describes how
the process works; for a more detailed description of each step in this process, see Runtime
workflow description.
1. OpenX Market receives an ad request, and selects a set of real-time bidders to solicit bids
from.
2. OpenX Market requests bids from the selected set of real-time bidders.
3. Each bidder receives the request, evaluates the bidding opportunity, and responds to the
request (even if the bidder does not want to place a bid).
4. OpenX Market executes an auction.
5. OpenX Market delivers the ad of the winning bidder.
6. OpenX Market supplies auction result notices to participating bidders.
About this document

This document describes the OpenX Real-time Bidding API, version 10, including required and
optional settings that you can configure in the OpenX Market Advertiser Console, before
participating as a bidder. In addition, it describes the structure of the real-time bid request, the
real-time bid response, and result notifications, including required and optional field
descriptions.
Whats new in this version?
This version includes a new field in the Device structure, idforad_enabled, which indicates if
a user has tracking turned on or off on their device.

6
Terms and definitions
The following terms and definitions are used throughout this document:
Term Definition
Bid request The OpenX Market request (BidRequest), sent to a bidder, which
solicits a bid for an impression (BidResponse).
Bid response The bidders response (BidResponse) to an OpenX Market real-

time bid solicitation (BidRequest).
CPM Cost per mille (thousand).
QPS Queries per second.
RTB Real-Time Bidding: the process of responding to OpenX Market

bid requests in real-time.
What you need to do

If you want OpenX Market to consider your campaigns for real-time bidding, you need to:
1. Configure your advertiser account for real-time bidding.

2. Create at least one campaign for real-time bidding.
3. Create at least one placement within an RTB campaign.
4. Create at least one creative, and assign it to an RTB placement.
Note. In addition, OpenX provides an SSRTB Tester tool, which you can use to verify that your
RTB implementation is set up correctly.
Configuring accounts
If you are a buyer in OpenX Market, and you want to participate in real-time bidding, you need
to configure your account to support it. To do this, you need to set several RTB preferences for
your account through the OpenX Market Advertiser Console. If you do not set these
preferences, OpenX Market will not consider your account for bid requests.

7
RTB account attributes

For each account, you can specify values for the following RTB settings:
Server-side Real-time Bid URL. The URL to which you want OpenX Market to send bid
requests. To reduce latency, you can specify multiple URLs for different global regions, based
on the location of the original ad request. This includes a U.S. West, U.S. East, Europe, and
Japan. OpenX Market will send the request to the URL closest to the location of the original
ad request.
Server-side Real-time Bid Result Notification URL. The URL to which you want OpenX
Market to send bid result notifications (e.g., win/loss notifications). You can specify region-
specific URLs similar to the Bid URL attribute.
RTB Data URL Template. The URL template you can use for mapping user data that OpenX
stores for you. See User mapping for more information.
Cookie-mapping URL Template. The URL you can use for mapping user data that you store.
See User mapping for more information.
In addition, you can set the following preferences, which may affect real-time bidding:
URL Blocklist. The list of publisher URLs to globally block on an account, which affects all
campaigns belonging to the bidder. These URLs are always blocked from consideration when
any of your placements bid on ad inventory, regardless of what campaign they belong to.
Category Blocklist. The list of publisher categories to globally block on an account, which
affects all campaigns belonging to the bidder. These categories are always removed from
consideration when any of your placements bid on ad inventory, regardless of what campaign
they belong to.
For more information about these settings, refer to the OpenX Market Advertiser Console User
Guide.

8
Setting up campaigns
Prior to receiving real-time bid requests, a real-time bidder needs to set-up at least one RTB
campaign in the OpenX Market Advertiser Console. The RTB campaign must also contain at
least one placement and creative. These campaigns, placements, and creatives are similar to
their traditional counterparts; however a URL for bid requests is set, rather than a bid value or
creative, and there are no budget smoothing options available (just spend caps).
RTB campaign attributes

For each RTB campaign, you must specify the following settings:
Campaign Name.The name of the campaign.

Bid Type. The type of bid for all placements in this campaign; set this to Server-side Real-time
for an RTB campaign.
Start Date and End Date.The dates when the campaign starts and ends.
Budget.The amount of money to spend for the campaign, which includes:
Total. The maximum amount of money to spend over the life of the campaign; that is,
within the specified start and end dates for the campaign.
Daily. The maximum amount of money to spend on the campaign in a single day.
In addition, you can specify the following setting, which may affect real-time bidding:
URL Blocklist. A list of URLs to block from a campaign,which affects all placements within the
campaign. These URLs are always blocked from consideration when a placement within the
campaign bids on ad inventory.
Guide.

9
Setting up placements
Within an RTB campaign, you must set up at least one RTB placement in the OpenX Market
Advertiser Console, prior to receiving real-time bid requests.
RTB placement attributes

For each RTB placement, you can specify the following settings:
Note. Required settings are Placement Name, Campaign, Bid Type, and Creative; all other
settings are optional.
Placement Name. The name of the placement.

Campaign. The campaign that the placement belongs to.
Bid Type. The type of bid for this placement, which is inherited by its parent campaign (for
RTB placements, this is set to Server-side Real-time).
Creative. The RTB creative to serve for the placement (the bidding URL is set within the
account).
BrandSafe indicator. Indicates if you want the placement to bid only on ad inventory that
OpenX has designated as BrandSafe.
Frequency cap. The number of times to match the placement to a user over a specified
period of time
RTB data availability indicator. Indicates if you want the placement to bid only on ad
inventory when your RTB data is available.
Basic Targeting. General details that you want the placement to target, which includes the
following settings:
Country. The countries to include or exclude from the placement.
User Language. The user languages to include or exclude from the placement.
Category. The site categories to include or exclude from the placement.
Technical Targeting. Technical targeting details about the users computing environment that
you want the placement to target, which includes the following settings:
Browser. The browser(s) to include or exclude from the placement.
Cookies. Specifies if the placement targets users who accept cookies or who do not
accept cookies.
HTTPS. Specifies if the placement targets sites that user HTTPS or that do not use
HTTPS.
Net Speed. Specifies the user connection speeds that the placement targets.
OS. Specifies the user operating systems that the placement targets.
In addition, you can set the following preferences, which may affect real-time bidding:
Domain Targeting. The websites to include in the placement.

Website ID Targeting. The website IDs to include in the placement.
Guide.

10
Setting up creatives
You must set up at least one RTB creative in the OpenX Market Advertiser Console, and assign
it to an RTB placement, prior to receiving real-time bid requests.
RTB creative attributes

For each RTB creative, you can specify the following settings:
Note. Required settings are Creative Name, Bid Type, Creative Size, Creative Type, and
Content Category; all other settings are optional.
Creative name. The name of the creative.

Bid Type. The type of bid for this creative (for RTB creatives, set this to Server-side Real-
time). You can only assign RTB creatives to RTB placements.
Creative Size. The size of the ad that will be returned by the bidding server.
Creative Type. The type of ad that will be returned by the bidding server (e.g., image, flash,
etc.).
Content Category. The content category of the ad.
Content Attribute. Attributes associated with the ad, which help publishers filter content that
they may not want to appear on their site (the sin categories are contained in this list).
Language. The language of the ad.
Guide.

11
Testing your RTB implementation

OpenX provides the SSRTB Tester tool for testing your RTB implementation. This tool simulates
an ad request and subsequent BidRequest from OpenX Market. You can return a BidResponse
to make sure that your RTB implementation is working properly.
1. Type the following URL in your browser and press Enter.
! http://bid.openx.net/ssrtb_tester/
! This displays the SSRTB Tester form.
2. In the Endpoint box, type in the URL where you want OpenX Market to send bid requests
(Server-side Real-time Bid URL). In this case, OpenX will send a test BidRequest message
to this URL.
3. The remaining fields in the form represent required and optional fields in the BidRequest
message. Make sure there are valid values for the required fields, and any others that you
want OpenX to include in the test BidRequest.
4. Click Go.
OpenX sends a test BidRequest message with the is_test field set. In turn, you can return a
BidResponse message to make sure that your RTB implementation is set up correctly.

12
Runtime workflow description

OpenX Market communicates with with real-time bidders over HTTP, using protocol buffers
(http://code.google.com/p/protobuf/).
The following steps are followed for each real-time bid request from OpenX Market:
1. Real-time bidder selection.

After receiving an ad request from the client, OpenX Market selects a set of real-time
bidders to solicit bid requests from. OpenX Market may limit the number of real-time bid
solicitations it makes for a single ad request. When there is a surplus of bidders, OpenX
Market chooses those that it has determined have the best chance of winning the auction.
2. Bid request from OpenX Market.
OpenX Market sends a bid request to the selected bidders. The bid request contains the
information necessary to technically execute a bid, and may contain optional targeting
information. If a single bidder has multiple matching placements, OpenX Market includes all
of the matching placements in the bid request.
3. Bid response.
The bidder unpacks the request and evaluates the opportunity. The bidder responds with
either a CPM bid, or a no bid response. Bidders must respond to bid requests, as timeouts
will have a negative impact on the number of bid requests sent to the bidder. In the case of a
bidder with multiple matching placements, the bidder must provide a CPM bid or no bid
response for one of the matching placements. (This is so that OpenX Market can attribute
the impression to the appropriate campaign, placement, and creative in reports.) In addition,
bidders may include multiple bids in their BidResponse for a single matching ad.
4. Auction.
Once the bids are received (or after an allotted amount of time) the auction is executed. The
price paid by a winning real-time bidder is determined by a modified Vickrey auction.
Publishers have the ability to set a floor price for their inventory. So, in those cases, any
winning bid must be higher than the publishers floor price.
5. Ad delivery.
Part of the bid response is the HTML of the ad the bidder wants to serve. When the bidder
wins the auction, this HTML is loaded in the browser. Macros for the winning price, and for
tracking clicks can be included in the HTML (see Macros for more information).
6. Result notifications.
OpenX Market sends result notifications, in the form of an AuctionResults message, for each
bid it received for a given auction.

13
BidRequest
When appropriate, OpenX Market will send a BidRequest to the URL specified for the Server-
side Real-time Bid URL setting. If a single bidder has multiple matching ads, OpenX Market
includes all of them in the BidRequest.
The following table describes the required and optional fields in each BidRequest message that
OpenX Market sends to bidders.
Field Name Type Description Required?
api_version int32 Indicates the version of the API that OpenX Yes
Market is using to communicate with the
bidder.
auction_id string A unique ID for the request, which OpenX Yes

Market uses to identify the auction.
For example: 888b4a7a-
d259-11e0-9912-000c29b0c11a.
matching_ad_ids AdId The list of matching ads for which OpenX Yes
Market is soliciting bids from the bidder.
pub_website_id string/integer The unique ID for the publishers website Yes

where the ad for the winning bidder will be
displayed.
For example, this can be one of the following:
A UUID:
3f6b1508-75ee-4283-8de5-3ddadf3a
b338.
An integer:
2428.
ad_height int32 The height of the ad unit where the ad of the Yes
winning bidder will display. If ad_height is
set in the AdId object, then it will override this
value.
For example: 250.
ad_width int32 The width of the ad unit where the ad of the Yes
winning bidder will display. If ad_width is set
in the AdId object, then it will override this
value.
For example: 300.

14
user_cookie_id string A unique ID for the user viewing the webpage. No

To protect the identity of the user, this value is
different for each bidder. For example, OpenX
Market may send a value of 1234 to bidder A,
and a value of 5678 to bidder B, which both
represent the same user. OpenX also sets this
value in the X-OpenX-Id custom HTTP
header.
user_ip_address bytes The IP address for the user viewing the No

webpage. The last octet of the IP address may
be truncated for IP obfuscation purposes.
user_screen_height int32 The height of the users viewing screen, in No

pixels.
For example: 1200.
user_screen_width int32 The width of the users viewing screen, in No

pixels.
For example: 1600.
user_geo_country string The users country location. No

For example: us.
user_geo_state string The users state location. No

For example: california.
user_geo_dma int32 The ID of the users DMA location. For No

example: 5. Refer to the OpenX Market
Dictionary Data ReferenceTool for a list of
possible values.
user_agent string The user agent string for the user. No
user_lang string A list of the users preferred languages. For No

example: en for English. Refer to the OpenX
Market Dictionary Data Reference Tool for a
list of possible values.
url string The URL initiating the ad request. No

For example: http://
www.publisher.com/page.html.
http_referer string The HTTP referer for the webpage generating No

the ad request.
For example: http://www.referer.com/
page.html.

15
ox_cat_tier_1 int32 The ID of the top-level tier of the webpages No

content category. Refer to the OpenX Market
Dictionary Data Reference Tool for a list of
possible values.
ox_cat_tier_2 int32 The ID of the subcategory for the webpages No

content. Refer to the OpenX Market Dictionary
Data Reference Tool for a list of possible
values.
pub_blocked_cat int32 A list of ad category IDs blocked for this No

publisher in the ad request. Refer to the
OpenX Market Dictionary Data Reference Tool
for a list of possible values.
pub_blocked_content int32 A list of blocked content IDs for this publisher No

in the ad request. Refer to the OpenX Market
Dictionary Data Reference Tool for a list of
possible values.
pub_blocked_type int32 A list of blocked ad type IDs for this request. No

Refer to the OpenX Market Dictionary Data
Reference Tool for a list of possible values.
pub_blocked_url string A list of blocked domains from the click URL. No

For example: nike.com.
rtb_data string Bidder-specific user data, generally a bidders No

user ID. OpenX also sets this value in the
X-OpenX-Rtb custom HTTP header.
pub_blocked_ad_lang string The list of languages that the publisher blocks No

uages in ads that display on the webpage. For
example: en or fr. Refer to the OpenX
Market Dictionary Data Reference Tool for a
list of possible values.
market_operator string Indicates which OpenX Market operator is No

representing the publisher. You can use this
value, rather than geographic information of
the end-user, to infer the location of the actual
publisher.This can be one of the following:
FT-FR (Orange France)
FT-GB (Orange UK)
cci (cci/Dentsu)
OX (All others)
device Device Details for the end-users computing No

environment and location.

16
is_test bool Indicates that this is a test BidRequest No

message. If set, bidders must return a valid
BidResponse message, which is used for
validation purposes only, and then discarded.
is_mobile_site bool Indicates that the BidRequest is for an No

impression on a mobile-optimized website.
The default value is False.
is_application bool Indicates that the BidRequest is for an No

impression within a mobile application. The
default is False.
tp_key_val ThirdPartyKey The list of third-party key-value pairs, which No

Value describe the device where the user is viewing
the impression.
AdId structure
The following table describes the AdId structure.
campaign_id int32 The ID for the campaign. Yes
placement_id int32 The ID for the placement. Yes
creative_id int32 The ID for the creative. Yes
deprecated_deal_id string This field is deprecated. Use the Deal format No

instead.
ad_height int32 The height of the ad unit where the ad of the No

winning bidder will display. The value of this
field overrides ad_height if set in the
BidRequest.
For example: 250
ad_width int32 The width of the ad unit where the ad of the No

winning bidder will display. The value of this
field overrides ad_width if set in the
BidRequest.
For example: 300.
deal Deal The direct deal associated with this inventory No

purchase. For example, this may correspond
with a specific deal you have prearranged
directly with a publisher.

17
Device structure
The following table describes the Device structure.
didsha1 string The SHA-1 hash identifier for the users No

device, such as the UDID for an iOS device.
For example:
2b6f0cc904d137be2e1730235f5664094b
831186
dnt int32 Indicates if the user has set the Do Not Track No
(DNT) setting for their devices browser.
0 indicates that DNT is set to false.
1 indicates that their DNT is set to true (that
is, the user does not want to be tracked).
ua string Indicates the user agent string for the users No

browser.
For example: Mozilla/5.0 (Macintosh;
U; Intel Mac OS X 10_6_2; en-us)
AppleWebKit/531.21.8 (KHTML, like
Gecko) Version/4.0.4 Safari/
531.21.10
Note. Use this value rather than the
user_agent set in the BidRequest.
ip string The ipv4 address closest to the users device. No

For example: 238.122.7.1
The last octet of the IP address may be
truncated for IP obfuscation purposes.
user_ip_address set in the BidRequest.
carrier string The mobile carrier for the users device, using No
the Mobile Country Code and the Mobile
Network Code; that is, MCC-MNC.
For example: 310-410.
os string The operating system for the users device. No
osv string The version number for the users operating No

system.
language string The list of two letter codes for the users No
preferred browsing languages on their device.
For example: en
make string The make for the users device. No

For example: Apple or Samsung

18
model string The model for the users device. No

For example: iPhone or Galaxy
connectiontype string Indicates the detected data connection type No

for the users device. This can be one of the
following:
wifi
cell
cell-2G
cell-3G
cell-4G
deprecated_api string This field has been deprecated. Use the No

repeated int32 format instead.
geo Geo Geographic location details for the user. No
browser string The name of the users browser. No
browser_version string The version number for the users browser. No
api int32 The list of supported API standards or No

frameworks. This can be one of the following:
1 - VPAID 1.0
2 - VPAID 2.0
3 - MRAID 1.0
4 - ORMMA
5 - MRAID 2.0
For example: 1, 2
odin1 string The Open Device Identification Number No

(ODIN-1) for the end-user's mobile device.
For example:
e1b33694687ded5475f72f996cf025be3d
d160fe
openudid string The OpenUDID for the end-user's mobile No

device.
For example:
Android (16 char):34a265c3b73e4e
iOS (40 char):
7a5fab3d942494f7e31be4f4eec0e815
6f53c6bf
secureudid string The SecureUDID for the end-user's mobile No

device.
For example: 50647BB4-
DA42-49B4-9A8F-541203150654

19
idforad string The advertising identifier for Apple's iOS 6 No

operating system on the end-user's mobile
device.
For example:
43043FE3-6BA9-4515-8209-6E0AC6AE1A
DF
androidid_md5 string The MD5 hash of the Android ID for the end- No
user's mobile device.
androidid_sha1 string The SHA-1 hash of the Android ID for the end- No
user's mobile device.
macaddress_md5 string The MD5 hash of the MAC (Media Access No

Control) address for the end-user's mobile
device.
macaddress_sha1 string The SHA-1 hash of the MAC (Media Access No

Control) address for the end-user's mobile
device.
idforad_enabled boolean The indicator for whether the users device No

has tracking turned on (true) or turned off
(false).
Geo structure
The following table describes the Geo structure.
lat float The users latitude location. No

For example: 33.684
lon float The users longitude location. No

For example: -117.793
country string The user's country location. No

For example: us
user_geo_country set in the BidRequest.
city string The user's city location. No

For example: los angeles
zip string The user's postal code location. No

For example: 92602

20
type int32 Indicates the source of the users geographic No

location details. This can be one of the
following:
1 - GPS
2 - IP
3 - User Provided
continent string The user's continent location. No

For example: north america
state string The user's state location. No

For example: california
user_geo_state set in the BidRequest.
dma int32 The user's Designated Market Area (DMA) No

location.
For example: 803
user_geo_dma set in the BidRequest.
Deal structure
The following table describes the Deal structure.
deal_id string The ID for the agreement associated with No

this inventory purchase.
deal_cpm_micros int64 The CPM price for the line item associated No
with the deal, expressed in micros. For
example, a value of 1,250,000 micros equals
$1.25
deal_pricing_type DealPricingType Indicates whether the line item associated No

with the deal uses a floor price (auction) or
fixed price.
deal_exclusivity DealExclusivity Indicates whether the line item associated No

with the deal allows the buyer to deliver
other demand even if passing on the deal.

21
DealPricingType
The DealPricingType enumeration indicates if the line item for the prearranged deal uses a fixed
price or a floor price (auction). Possible values are:
fixed = 1
floor = 2
DealExclusivity
The DealExclusivity enumeration indicates if the line item for the prearranged deal allows the
buyer to deliver demand even if it passes on the deal. Possible values are:
other_bids_accepted = 0
deal_bids_only = 1
ThirdPartyKeyValue
The following table describes the ThirdPartyKeyValue structure.
key string Indicates the third-party identifier key. No

For example: adtruth.id
value string Indicates the value for the associated key. No
Additional HTTP headers

OpenX sets the following additional HTTP headers in each RTB request:
Header Description Example
X-OpenX-Id Contains the value of the X-OpenX-Id:

user_cookie_id field in the 09901b84-4918-47aa-b700-a70832a0c875
BidRequest.
X-OpenX-Rtb Contains the value of the X-OpenX-Rtb: <up to 200 bytes>

rtb_data field in the BidRequest.

22
BidResponse
After processing a BidRequest from OpenX Market, each bidder returns a BidResponse
message. In each BidResponse for a given auction, you can submit multiple bids.
Note. Bidders must respond to bid requests even if they do not want to bid on the opportunity,
by returning either:
An empty list of bids,
An HTTP code of 204
An empty protobuf
A list of bids with a cpm_micros_bid of 0
Bidders have 125 milliseconds to successfully submit a bid response to OpenX Market. A
successful submission means that OpenX Market has received and registered the response.
So, if you are sending your response at 124 milliseconds, it is unlikely that it will be received and
registered within the allocated timeframe. Excessive timeouts will reduce the number of bid
requests sent to the bidder from OpenX Market
Note. A bidders response should be kept less than or equal to 1k in size, though responses
greater than 1k will be accepted.
About micros
Multiple fields in the BidResponse, Bid, and AuctionResult structures use micros to express their
values. The conversion for a micro is: $1.00 USD = 1,000,000 micro. For example:
$0.01 = 10,000 micros
$0.10 = 100,000 micros
$1.00 = 1,000,000 micros
$3.27 = 3,270,000 micros

23
The following table describes the required and optional fields in each BidResponse that you
send to OpenX Market.
Note. Some fields in the BidResponse have been deprecated, and are now part of the Bid
structure for each BidResponse.
api_version int32 Indicates the version of the API that you are Yes
using to respond to OpenX Market.
Note. This value must match the
api_version in the BidRequest.
auction_id string The unique ID for the auction, which OpenX Yes
Market generates and uses to identify the
BidRequest that this BidResponse is for. For
example: 888b4a7a-
d259-11e0-9912-000c29b0c11a.
Note. This value should match the
auction_id value in the BidRequest.
bids Bid The list of bids to return for the BidRequest. Yes
You can submit multiple bids for a single
auction.
Note. To submit a no bid response, include
an empty list of bids, a list of bids with a
cpm_bid_micros of 0, an HTTP 204, or an
empty protobuf.
next_highest_bid_mic int64 The next highest bid after the bids in this No
ros response, expressed in micros.
For example, a value of 1,250,000 micros
equals $1.25.

24
Bid structure
The following table describes the required and optional fields for each Bid structure that you
include in a BidResponse, which you can use to submit multiple bids for a matching ad.
matching_ad_id AdId Indicates the matching ad you are placing a Yes

bid for. Carry this structure over from the
BidRequest.
Note. Please do not modify this structure.
cpm_bid_micros int64 The CPM bid price, or bid per 1000 Yes, when
impressions, expressed in micros. bidding
For example, a value of 1,250,000 micros
equals $1.25.
ad_code string The HTML code to serve if the bid wins the Yes, when
auction. You can include various macros in bidding
this field for things like click tracking.
ad_ox_cats int32 The list of OX category IDs appropriate for the No

ad being returned with the bid. Refer to the
OpenX Market Dictionary Data Reference Tool
for a list of possible values.
click_through_urls string The list of destination URLs for the ad, Yes, when
representing the final landing page. bidding
For example: nike.com or http://
events.nike.com/showEvent?id=1.
buyer_id string N/A. Not currently used. No
brand_id string N/A. Not currently used. No
crid string The unique buyer-specific ID for the creative. No
Macros
OpenX Market supports the following macros (which are expressed in fields as
{macro_name}), which you can include in the ad_code field for each Bid in your
BidResponse, and are substituted dynamically before the ad is sent to the end-user:
clickurl_esc - A url-escaped click-through URL.

clickurl - An unescaped click-through URL.
random - A random unsigned 4-byte integer in string format.
techno.page_url - The URL where the creative is served.
techno.domain - The top-level domain where the creative is served.
winning_price - The winning price of the auction, which is sent as an encrypted value (see
the next section).

25
About the winning_price macro

The price is passed in unpadded, web-safe base-64 encoding (RFC 3548). You will need to
convert this to standard base-64 encoding, (RFC 2045) and pad the result. The price is
decrypted with the encryption key, and the integrity of the price is verified with the integrity bits
and the integrity key. Your keys will be supplied during on-boarding, and the message format is:
init_vector (16 bytes), encrypted_price (8 bytes), integrity (4 bytes).
Price encrypting scheme

The price is encrypted using a custom encryption scheme that is designed to minimize size
overhead while ensuring adequate security. The encryption scheme uses a keyed HMAC-SHA1
algorithm to generate a secret pad based on the unique impression event ID.
The encrypted price has a fixed length of 28 bytes. It is comprised of a 16-byte initialization
vector, 8 bytes of ciphertext, and a 4-byte integrity signature. The encrypted price is web-safe
base-64-encoded, according to RFC 3548, with padding characters omitted. Thus, the 28-byte
encrypted price is encoded as a 38 character web-safe base-64 string. The price is encrypted
as:
<price xor HMAC-SHA1(encryption_key, initialization_vector)>
so decryption calculates:
HMAC-SHA1(encryption_key, initialization_vector)
and xor's with the encrypted price to reverse the encryption. The integrity stage takes 4 bytes of
<HMAC-SHA1(integrity_key, price||initialization_vector)>
where || is concatenation.
Use this code snippet at the following link for price decryption:
https://github.com/openx/SSRTBPriceCrypter
AuctionResults
After OpenX Market evaluates bid responses, holds the auction, and serves the winning ad, it
can return an AuctionResults message to the appropriate notification endpoint (Server-side
Real-time Bid Result Notification URL) for each bidder that it solicited for a given auction. You
can use the same endpoint specified for the BidRequest, or set up a separate endpoint for the
AuctionResults. OpenX Market returns a notification for each bid included in a given
BidResponse (in the case of multiple bids), and no notification is sent for a BidResponse with no
actual bid.
The following table describes the required and optional fields in each AuctionResults message
that OpenX Market sends to a bidder.

26
api_version int32 Indicates the version of the API that OpenX Yes
Market is using to communicate with the
bidder.
auction_id string The unique ID for the auction, which OpenX Yes
Market generates and uses to identify the
BidRequest that this notification is for.
For example: 888b4a7a-
d259-11e0-9912-000c29b0c11a.
results AuctionResult The list of information about the results of the Yes
auction.
AuctionResult structure
The following table describes the required and optional fields in the AuctionResult structure for
each AuctionResults message that OpenX Market sends to the bidder. For a given auction,
OpenX Market includes an AuctionResult for each Bid in a bidders BidResponse. That is, if a
bidder submitted five bids for a given auction, then OpenX Market would return five notifications
- one AuctionResult for each Bid.
matching_ad_id AdId This structure will be the same as the one in Yes
the appropriate response message.
status AuctionStatus Indicates if the bidders Bid won or lost the Yes
auction, or if an error occurred.
loss_reason string If the result of the bid is a loss, then this field No
provides a reason for the loss, which can be
one of the following:
price
The Bid price was insufficient to win the
auction.
disqualification
The Bid was filtered out; for example, if the
advertiser was blocked.

27
error_reason string If there was an error processing the bid, then No

this field provides a reason for the error, which
can be one of the following:
TIMEOUT
The original Bid was not received; that is, it
timed out.
ERROR_CONNECT
An error occurred while establishing the http
connection.
ERROR_RECEIVE
An error occurred while receiving the
response.
ERROR_PARSE
An error occurred while parsing the
response.
ERROR_UNKNOWN
Some other, unknown error occurred.
ERROR_EMPTY
An empty response was returned.
ERROR_NXDOMAIN
There wan an error resolving the endpoint
domain.
winning_bid_micros int64 If the result of the bid is a loss, then this field No
indicates the bid price that actually won the
auction. This value is expressed in micros.
clearing_price_micros int64 If the bid won the auction, then this field No
indicates the actual price that the bidder paid
for the impression. This value is expressed in
micros.
AuctionStatus structure
The following table describes the AuctionStatus structure, which OpenX Market includes for
each AuctionResult.
status enum Indicates if the bidders Bid won or lost the Yes
auction, or if an error occurred. This can be
one of the following:
1 (win)
The bidder won the auction.
2 (loss)
The bidder lost the auction.
3 (error)
An error occurred in processing the bid.

28
User mapping
OpenX provides two mechanisms to synchronize your user data for real-time bidding. In one
method, OpenX stores information you provide about each user, and in the other method,
OpenX provides a user ID for you to store. Invoking user synchronization can be done by
dropping the appropriate pixel yourself, or by requesting that OpenX do this, or both to achieve
maximum coverage.
If you plan to drop pixels yourself, you will need to create a simple image pixel and invoke one
of the following URLs:
RTB data URL

Cookie-mapping URL
If OpenX does the drops for you, simply provide the appropriate URL, which will then be
wrapped in an image pixel maintained by OpenX.
Templates for URLs, along with your partner ID, are available in the OpenX Market Advertiser
Console at:
! https://ac.openx.com/account/real-time-bid-settings/base-url/
Using the RTB data URL
In this method, you send user data to OpenX, which stores it for you, and sends it as part of the
RTB bid request, in the rtb_data field.
To use this method, you need to:
1. Set up to 200 bytes of your own data against an OpenX user.

2. Create the RTB data URL using this URL template:
http(s)://r.openx.net/set?pid={pid}&rtb={your data}
where:
{pid} is your assigned partner ID.
{your data} is up to 200 bytes of the data you want to set against an OpenX user.
3. Wrap the URL in an image pixel.
4. Drop the pixel in the appropriate location.
If OpenX is managing the pixel drop, you must provide a URL that first calls your own servers,
and then redirects to the appropriate OpenX URL with the relevant RTB data included.
Note. You can target your placements only to bid on requests that include RTB data.

29
Using the cookie-mapping URL
In this method, OpenX makes its user ID for a given user available to you for storing and
mapping against your own internal information. The OpenX user ID, when available, is included
in every RTB request.
To use this method, you need to:
1. Create the cookie-mapping URL using this URL template:

http(s)://bid.openx.net/cm?pid={pid}&dst={your destination URL}
where:
{pid} is your assigned partner ID.
{your destination URL} is the location of your user data.
2. Wrap the URL in an image pixel.
3. Drop the pixel in the appropriate location, or provide it to OpenX.
The OpenX user ID is appended to the destination URL. Therefore, as a best practice, your
destination URL (the user synchronization endpoint hosted on your servers) should end with an
argument name and the equivalent of an equal sign (=). For example, a destination URL of:
http://myservice.com/usersync/openx?id=
Would result in a redirect to:
http://myservice.com/usersync/openx?id=2370e610-d4dc-11e0-9572-0800200c9a66
Where: 2370e610-d4dc-11e0-9572-0800200c9a66 is the OpenX user ID for the user.

Ox RTB Api v10

Hochgeladen von

Dokumentinformationen

Originaltitel

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Ox RTB Api v10

Hochgeladen von

Copyright:

Verfügbare Formate

OpenX Market

Real-time Bidding API Reference

OpenX Market Real-time Bidding API Reference--Version 10-Updated 04/03/2013

2013 OpenX Ltd.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

About this document! 5

Whats new in this version?! 5

Terms and definitions! 6

What you need to do! 6

Testing your RTB implementation! 11

Runtime workflow description! 12

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

Additional HTTP headers! 21

About the winning_price macro! 25

Price encrypting scheme! 25

Using the RTB data URL! 28

Using the cookie-mapping URL! 29

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

How real-time bidding works

About this document

Whats new in this version?

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

Terms and definitions

Bid response The bidders response (BidResponse) to an OpenX Market real-

CPM Cost per mille (thousand).

QPS Queries per second.

RTB Real-Time Bidding: the process of responding to OpenX Market

What you need to do

1. Configure your advertiser account for real-time bidding.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

RTB account attributes

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

RTB campaign attributes

Campaign Name.The name of the campaign.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

RTB placement attributes

Placement Name. The name of the placement.

Domain Targeting. The websites to include in the placement.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

RTB creative attributes

Creative name. The name of the creative.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

Testing your RTB implementation

1. Type the following URL in your browser and press Enter.

! This displays the SSRTB Tester form.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

Runtime workflow description

1. Real-time bidder selection.

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

Field Name Type Description Required?

auction_id string A unique ID for the request, which OpenX Yes

pub_website_id string/integer The unique ID for the publishers website Yes

OpenX Market Real-time Bidding API Reference--Version 10--Updated 04/03/2013

Field Name Type Description Required?

user_cookie_id string A unique ID for the user viewing the webpage. No

user_ip_address bytes The IP address for the user viewing the No

user_screen_height int32 The height of the users viewing screen, in No

user_screen_width int32 The width of the users viewing screen, in No

user_geo_country string The users country location. No

user_geo_state string The users state location. No

user_geo_dma int32 The ID of the users DMA location. For No

user_agent string The user agent string for the user. No

user_lang string A list of the users preferred languages. For No