Yieldlab

RTB Demand Specification Version 1.5.5 5/2012

Yieldlab RTB Specification

Content
Content ................................................................................................................................................... 1 The Yieldlab System ................................................................................................................................ 2 User Matching ......................................................................................................................................... 2 Auction .................................................................................................................................................... 4 Notification placeholders ........................................................................................................................ 6 Response times ....................................................................................................................................... 6 Programming interfaces Yieldlab Analytics API .................................................................................... 6 API for Authentication ............................................................................................................................ 7 API for Advertiser Information ................................................................................................................ 8 API for Filters ........................................................................................................................................... 9 API for Reporting Data .......................................................................................................................... 10

Page 1 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

The Yieldlab System

Yieldlab offers potential buyers of display ad spaces (Demand Partners) the opportunity of submitting specific bids for individual ad impressions. The following specification has been created to facilitate integrating your systems with the Yieldlab platform. Should you have any questions, please dont hesitate to contact the Yieldlab Team.

User Matching
Since Demand Partners own cookies are not visible until the advertising media are supplied, i.e. not at the time the bid is submitted, user matching between Yieldlab and the Demand Partner must take place. This enables Yieldlab to make information on the Demand Partner cookie available to the Demand Partner for the bid. Ideally, the user matching should take place on the Demand Partner side in conjunction with matching at Yieldlab. Matching on Demand Partner side The simplest way to effect matching on the Demand Partner side is to integrate the following IMG tag into the Demand Partners advertising media tags or tracking tags, where ext_id is the Demand Partners user ID, and dm_id is the Demand Partners customer ID (the latter value will be provided by Yieldlab).
<img width="0" height="0" src="http://ad.yieldlab.net/m?dm_id=99&ext_id=ABC"/>

In the case where the demand partner supports multiple agencies, the following IMG tag should be used instead. Note that again ext_id is the Demand Partners user ID, and dt_id is the Demand Partners technology ID used by the partners agencies (the latter value will be provided by Yieldlab).
<img width="0" height="0" src="http://ad.yieldlab.net/m?dt_id=215&ext_id=ABC"/>

Matching on Yieldlab side When a user sends a request to the Yieldlab system (1), Yieldlab initiates a pixel request for the Demand Partner (2) that contains the Yieldlab-internal user ID for any user that has not been matched previously. The Demand Partner can then read the cookie that it had set for the user and transmit the DemandUserID to Yieldlab via a redirect (3). From that point in time, Yieldlab maintains a mapping between the two IDs (4).

From this point in time, the Demand Partner is notified of the DemandUserID in the course of the bidding process. Should the Demand Partner store its user data in the cookie rather than on the server, it is possible for up to 1 KB of cookie content to be maintained in the Yieldlab system. These cookie contents will be transmitted to the Demand Partner with the bid request in addition to the DemandUserID.
Page 2 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

The Demand Partner API may include the following parameters (GET Request):

Parameter
dm_id yl_id url type

Transmission Required
URL parameter URL parameter URL parameter URL parameter No No No No

Description
Unique ID (Yieldlab customer number) of Demand Partner Internal Yieldlab user cookie ID Callback URL for Yieldlab Type of return

Values
js (JavaScript), fr (IFrame), rd (HTTP redirect)

User Matching Callback to Yieldlab

Parameter
ext_id dm_id exp ddata_XXX

Transmission
URL parameter URL parameter URL parameter URL parameter

Required Description
Yes Yes No No External user cookie ID / DemandCookieID Demand Partners ID Expiry date of matching or of user-defined data Individual parameters to store user-specific attributes

Notes
Max. 1 KB. Every parameter that begins with ddata_ is treated as an individual user-specific attribute and stored in the Yieldlab system. The term ddata_ is automatically deleted to provide the parameter name. The transmitted attribute ddata_Gender, for instance, will be stored in the Yieldlab system as Gender.

In addition to HTTP redirects, matching via JavaScript and iframes is also supported.
HTTP Redirect (recommended)

Example of a request by Yieldlab to the Demand Partner

<img width="0" height="0" src="http://demandpartner.com/usermatch?yl_id=123&dm_id=99&type=rd&url=http%3A%2F%2Fad.yieldlab.net%2Fm"/>

Response by the Demand Partner

http://ad.yieldlab.net/m?dm_id=99&ext_id=ABC

JavaScript

Example of a request by Yieldlab to the Demand Partner

<script type="text/javascript" src="http://demandpartner.com/usermatch?yl_id=123&dm_id=99&type=js&url=http%3A%2F%2Fad.yieldlab.net%2Fm"> </script>

Response by the Demand Partner

document.write('<img width="0" height="0" src="http://ad.yieldlab.net/m?dm_id=99&ext_id=ABC"/>');

IFrame

Example of a request by Yieldlab to the Demand Partner

<iframe width="0" height="0" border="0" frameborder="0" src="http://demandpartner.com/usermatch?yl_id=123&dm_id=99&type=fr&url=http%3A%2F%2Fad.yieldlab.net%2Fm"> </iframe>

Response by the Demand Partner

<html> <body> <img width="0" height="0" src="http://ad.yieldlab.net/m?dm_id=99&ext_id=ABC/> </body> </html>

Page 3 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

Auction
The auction within the Yieldlab system takes the following course: Yieldlab receives a request from the publishers ad server and selects Demand Partners for the ad impression on the basis of various algorithms. Each Demand Partner receives a (bidding) request via the server-side API that contains details about the ad impression as well as information for user matching (2). The Demand Partner responds with its bid (bidding response) plus the ad tag to be delivered if the bid is successful (3). Yieldlab supplies the ad tag of the winning bidder to the browser and replaces defined placeholders with details about the auction (4). The browser retrieves the advertising media from the Demand Partners ad server (5). Yieldlab supplies statistical information to all auction participants (6).

Bidding request sent by Yieldlab to Demand Partner

Parameter yl_id tid sid did wid adsize ext_id country user_agent lang refer ip Optional * X X X X X X Description Internal Yieldlab user cookie ID Unique transaction ID Supply Partners ID Demand Partner ID Website ID Ad space size External user ID ID of user country User agent Browser language URL of ad space Shortened IP address of request WIDTHxHEIGHT, e.g. 120x600 If user matching available Uppercase ISO 3166 2-letter code (e.g. DE for Germany) obtained from Accept-Language HTTP header URL-encoded user agent, obtained from User-Agent HTTP header (if available) (encoded using UTF-8 scheme) Lowercase ISO 639 language code (e.g. de for German) obtained from Accept-Language HTTP header URL-encoded referer URL, obtained from Referer HTTP header (if available) (encoded using UTF-8 scheme) The Internet Protocol (IP) address of the client or last proxy that sent the request, with the last octet set to 0 for privacy reasons (e.g. 46.20.32.0)

* Note: request parameters marked as optional may not be available for all supply partners, so it is preferable that demand partners do not depend on them when calculating bids. If an optional parameter is required for bidding, please communicate this fact to Yieldlab during the setup phase. User data submitted to Yieldlab via the ddata_XXX parameters (see User Matching) from previous user matching requests are included in the bidding request as HTTP cookie name-value pairs.
Page 4 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

Demand Partners need to provide Yieldlab with the URL to which bid requests should be sent. In cases where multiple agencies are supported by the demand partner, a configurable URL parameter must be provided that is unique for each agency. If present, only the specified agency may bid for the ad impression. In the case where this parameter is not set or is blank, all agencies are allowed to bid for the ad impression. The list of agency IDs supported by the demand partner should be communicated to Yieldlab during the setup phase. For example, the following Bid request URL
http://demandpartner.com/bid/yieldlab.bid?agency_id=145

results in only the agency with demand partner ID 145 being allowed to bid for the impression. Bidding response sent by Demand Partner to Yieldlab (JSON RFC4627 format)
Parameter Required cpm X adtag advertiser camurl tid error X X X X Type Float String String String String String Description Bid amount Ad tag Name of advertiser Landing page / campaign URL Unique request ID Error message Comments Return 0 if no bid is to be submitted Must conform to the spelling on the blacklist /whitelist The landing page of the campaign must be supplied as plain text (no click-through URLs!) e.g.: http://advertiser.com/index.html

In order to obtain information about the ad impression price, placeholder ${yl_winner_cpm} must be set in the ad tag. Yieldlab will replace this with the price payable for the ad impression. Example of a response to the Yieldlab system for a bid of EUR 1.25 with an ad server ad tag:
{ "cpm": 0.78, "tid": "730d97d0-dbca-42c4-a54f-6a7ef08d80e2", "adtag": "<script src=\"http://adserver.de/adcode.js?price=${yl_winner_cpm}&original_bid=${yl_bid_price}\"></scr ipt>", "camurl": "http://www.advertiser.de/landingpage/", "advertiser": "agency_advertiser" } } "bid": {

Up to 10 bids can be transferred in one response.

{ "bids": [ { "cpm": 0.93, "tid": "730d97d0-dbca-42c4-a54f-6a7ef08d80e2", "adtag": "<script src=\"http://adserver.de/adcode.js?price=${yl_winner_cpm}&original_bid=${yl_bid_price}\"></scr ipt>", "camurl": "http://www.advertiser.de/landingpage/", "advertiser": "agency_advertiser" }, { "cpm": 1.36, "tid": "730d97d0-dbca-42c4-a54f-6a7ef08d80e2", "adtag": "<script src=\"http://adserver.de/adcode2.js?price=${yl_winner_cpm}&original_bid=${yl_bid_price}\"></sc ript>", "camurl": "http://www.advertiser2.de/landingpage/", "advertiser": "agency_advertiser2" } ] } Page 5 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

Notification placeholders
Yieldlab offers a facility for obtaining information about won auctions with the aid of placeholders. For this purpose, defined placeholders are incorporated into the bidding response. Supported Placeholders in a Bidding Response
Placeholder ${yl_tid} ${yl_winner_cpm} ${yl_bid_price} ${yl_ext_id} Type String Float Float String Description Transaction ID der Auktion CPM for ad impression of the winning bid The CPM that was bid Price for the bid multiplied with the final endprice Comments Depending on the auction algorithm, the price may differ from the actual bid This way the final price will be handed over hidden

${yl_win_multiple} float

Example of a bid response with the notification placeholders:

{"bids": { "bid": { "cpm": 0.78, "tid": "730d97d0-dbca-42c4-a54f-6a7ef08d80e2", "adtag": "<script src=\"http://adserver.de/adcode.js?price=${yl_winner_cpm}&original_bid=${yl_bid_price}&tid=${y l_tid}\"></script>", "camurl": "http://www.advertiser.de/landingpage/", "advertiser": "agency_advertiser" } }}

If this bid has been successful, the following code is delivered to the browser:
<script src="http://adserver.de/adcode.js?price=0.73&original_bid=0.78&tid=730d97d0-dbca-42c4a54f-6a7ef08d80e2"></script>

If the bidder uses the placeholders to receive notification of the auction outcome, the notification is only sent if the bidder won the auction. If you also wish to be obtain information about auctions that you did not win, you need to use the statistics API.

Response times
Yieldlab requires a response time of maximum 120 ms. Any bids received after the response time has elapsed will be ignored. Should you not wish to submit a bid in response to a bid request, you should definitely respond with 0 instead of waiting for the timeout. Repeated non-adherence to the response deadline may cause the Demand Partner to be temporarily excluded. In order to minimize the latency between requests, Yieldlab uses persistent connections. This means, for example, that a certain number of persistent connections (connection pooling) to a specific Demand Partner are maintained and used repeatedly.

Programming interfaces Yieldlab Analytics API

What information can be queried? The Analytics API allows access to the following information from the Yieldlab system: White/black lists for all publishers that are being collaborated with List of advertisers maintained in Yieldlab system Historical reporting information for auction data
Page 6 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

The following types of media are supported

JSON - The REST API returns HTTP responses in JSON format XML - Support for XML can be implemented upon request Rate limiting may apply for API use and access will be granted based on IP addresses. Yieldlab requires the list of IP address(es) from which the Yieldlab API is to be accessed in advanced. Use of the API is restricted to IP addresses IP addresses requiring access to the Yieldlab API must be requested in advance A valid token must be obtained via the API for Authentication Block lists and reporting data can only be obtained for publishers with which activities are actually conducted (existing account)

Controlling data rate (rate limiting)

Restrictions and authorizations

API for Authentication

Via the API for Authentication, you receive a token that is intended for use of the entire Yieldlab APIs, i.e. that needs to be transmitted with each request. The relevant request transmitted to Yieldlab by the Demand Partner is as follows:
https://ad.yieldlab.net/api/auth

This must be executed as a POST request. The following parameters must be transmitted in the request body of the POST request:
username (the username provided by Yieldlab) password (the password for your Yieldlab account)

This request generates a token for the use of API requests. After receipt of a valid authentication token, this must be included in all subsequent requests. The validity of a token expires if it is not used within 5 minutes of having been issued. In that case, a new token simply needs to be requested from Yieldlab. You can request any number of authentication tokens.
Successful authentication

In the event of successful authentication, you will receive a token as a result as per the following example:
{ "output": { "token": " 4634c964-0c91-4157-a5fd-3b7d56aa6c21" } }

Here an example of a response where a problem occurred with the issuing of the authentication token:
{ "error": { "errorCode":1, "message":"Login failed" Page 7 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

} }

Authentication error

If you transmit an invalid token in connection with an API request, you will receive the following response:
{ "error": { "errorCode":2, "message":"invalid token" }

In this case, simply request a new token via the API for Authentication.

API for Advertiser Information

Using the following request to Yieldlab, a Demand Partner can query details about advertisers that are maintained in the Yieldlab system.
https://ad.yieldlab.net/api/advertisers/{advertiserId}/{authToken}

Parameters for the request

By specifying parameter advertiserId, details for a specific advertiser can be obtained. To obtain information on all available advertisers, please use value 0. The following example shows a request relating to all available advertisers:
Example of a request by the Demand Partner to Yieldlab
https://ad.yieldlab.net/api/advertisers/0/4634c964-0c91-4157-a5fd-3b7d56aa6c21

Example of a response by Yieldlab to the Demand Partner:

{ "output": { "advertisers": [ { "advertiserName": "advertiser "advertiserId": 1 }, { "advertiserName": "advertiser "advertiserId": 2 }, { "advertiserName": "advertiser "advertiserId": 3452 }, ... { "advertiserName": "advertiser "advertiserId": 8304 } ] }}

abc",

xyz",

dj",

g",

Parameters of the response to the Demand Partner

Parameter
advertiserID advertiserName

Description
ID of the advertiser from the Yieldlab system Unique name of the advertiser from the Yieldlab system

Page 8 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

API for Filters

Using the following request by the Demand Partner to Yieldlab, you can query information on the filters between advertisers and publishers maintained in the Yieldlab system.
https://ad.yieldlab.net/api/filter/{publisherId}/{authToken}

This request serves to determine all advertisers that are blocked for a publisher or for specific websites. By specifying the publisher ID, the request can be restricted to a specific publisher.
Parameters for the request

Specify the ID of the publisher for whom you wish to obtain the block list via parameter publisherId. Set the value to 0 if you wish to obtain information relating to all publishers with whom activities are conducted.
Example of a request by the Demand Partner to Yieldlab (to request a block list for Publisher 41)

https://ad.yieldlab.net/api/filter/41/4634c964-0c91-4157-a5fd-3b7d56aa6c21

Example of a response by Yieldlab to the Demand Partner

{"output": { "publisherFilters": [ { "publisherId": 41, "blackList": true, "list": [4, 5, 29], "websiteFilters: [ { "websiteId: 4711, "blackList": false, "list": [43, 52, 89] }, { "websiteId: 5291, "blackList": false, "list": [46, 213] } ] } ] }}

Interpretation

The publisher with ID=41 allows all advertisers except for 4, 5, and 29 Website 4711 of Publisher 41 allows only the following three advertisers: 43, 52, 89 Website 5291 of Publisher 41 allows only the following two advertisers: 46, 213 If there are further websites involved, no filters apply to them. I.e. every advertiser is allowed to bid for these websites (except for 4, 5, 29, since these are generally blocked for the specified publisher)

Page 9 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

Parameters of the response to the Demand Partner

Parameter
publisherID blackList blackList list websiteFilters

Output
true false

Description
ID of the publisher from the Yieldlab system If true is output, you are dealing with a blacklist! I.e. all advertisers are allowed apart from those listed. If false is output, you are dealing with a whitelist!. I.e. all advertisers are blocked, apart from those listed. A list including all blocked (blacklist = true) or all allowed (blacklist = false) advertisers for this publisher, independent of the website A list of all blocked (blacklist = true) and all allowed (blacklist = false) advertisers for specific websites. For websites that are not listed here all advertisers are allowed.

API for Reporting Data

This API provides access to the following details regarding publishers with which activities are conducted during a defined period: impressions eCPM spend / cost

Using the following request by the Demand Partner to Yieldlab, reporting data can be obtained from the Yieldlab system.
https://ad.yieldlab.net/api/report/demand/{publisherId}/{startDateTime}/{endDateTime}/{authTok en}

Parameters for the request

An individual publisher can be specified via parameter publisherId. To request transmission of data on all publishers, please use value 0. Parameters startDateTime and endDateTime can be used to define the period for which data is to be obtained. Please use format YYYY-MM-DD HH:MM:SS for this purpose. Example: 2011-04-19 00:00:00, URL encoded: 2011-04-19%2000%3A00%3A00
Example of a request by the Demand Partner to Yieldlab for Publisher 123
https://ad.yieldlab.net/api/report/demand/123/2011-04-19%2000%3A00%3A00/2011-0420%2000%3A00%3A00/4634c964-0c91-4157-a5fd-3b7d56aa6c21

Example of a response to the Demand Partner:

{"output": { "publisherReports": [ { "publisherId": 123, "startDateTime": "2011-04-19 00:00:00", "endDateTime": "2010-04-20 00:00:00", "impressions": 104892, "ecpm": 1.41, "spend": 147.9 } ] }}

Example of a request by the Demand Partner to Yieldlab for all publishers (with whom a collaboration exists)
https://ad.yieldlab.net/api/report/demand/0/2011-04-19%2000%3A00%3A00/2011-0419%2000%3A00%3A00/4634c964-0c91-4157-a5fd-3b7d56aa6c21 Page 10 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.

Yieldlab RTB Demand Specification Version 1.5.5 5/2012

Example of a response to the Demand Partner

{"output": { "publisherReports": [ { "publisherId": 123, "startDateTime": "2011-04-19 00:00:00", "endDateTime": "2010-04-20 00:00:00", "impressions": 104892, "ecpm": 1.41, "spend": 147.9 }, { "publisherId": 4711, "startDateTime": "2011-04-19 00:00:00", "endDateTime": "2010-04-20 00:00:00", "impressions": 492081, "ecpm": 0.84, "spend": 413.35 } ] }}

Parameters of the response to the Demand Partner

Parameter
publisherId startDateTime endDateTime impressions ecpm spend

Description
ID of the publisher from the Yieldlab system Start date End date Number of impressions in the specified period for the specified publisher Effective CPM (eCPM) Overall cost

Table listing possible error codes for automated processing of failed API requests:
Possible error codes

errorCode
1 2 3 4 5 9999

Description
Login failed Auth token invalid/expired Advertiser not found Publisher not found Time incorrectly formatted Unknown error

The Yieldlab RTB platform is currently still in the development phase; consequently, some of the API details may be updated over time. Please dont hesitate to contact the Yieldlab Team, should you have any questions!

Page 11 of 11 2010-2011 Yieldlab GmbH. All rights reserved. Confidential.