How to Integrate Demand Partners (DSPs)

Contents

1. DSP Integration Process

2.1. Bid Request Parameters

2.2. Bid Request Example

3.1. Bid Response Parameters

3.1. Bid Response Example

1. DSP Integration Process

In order to integrate a DSP, please follow these steps:

  1. Create a campaign and ad group (strategy) with specific targeting parameters (traffic with such parameters will be sent to the external DSP) and set the ad group/ campaign inactive
  2. Send us an endpoint URL issued by the DSP. This URL will be implemented by our tech team
  3. Once we confirm the URL has been impelemented, activate the ad group/ campaign, run a short test and compare the stats with the DSP in a day or two (impressions, total ad cost)
  4. If the stats matches on both DSP and SSP side, you can scale the traffic volume to the DSP by increasing the strategy/ campaign daily budget

Please note that creatives assigned to different ad groups/ campaigns should have unique IDs (meaning that it is not allowed to use the same creative for different ad groups/ campaigns for a DSP). 

Requests to DSPs are sent via JSON using OpenRTB 2.5 protocol. We use nurl to notify a DSP about bid win.

2.1. Bid Request Parameters

2.1.1 Object: BidRequest

Attribute Type Description
id string; required Unique ID of the bid request, provided by the exchange.
imp object array;
required
Array of Imp objects representing the impressions offered. At least 1 Imp object is required.
site object;
recommended
Details via a Site object about the publisher’s website. Only applicable and recommended for websites.
app object; recommended  Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps.
device object;
recommended
Details via a Device object about the user’s device to which the impression will be delivered.
user object;
recommended
Details via a User object about the human user of the device; the advertising audience.
at integer;
default 2
Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values greater than 500. 
tmax integer  Maximum time in milliseconds the exchange allows for bids to be received including Internet latency to avoid timeout. This value supersedes any a priori guidance from the exchange.
cur string array Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies.


2.1.2 Object: Imp

Attribute Type Description
id string; required A unique identifier for this impression within the context of the bid request (typically, starts with 1 and increments).
banner object A Banner object; required if this impression is offered as a banner ad opportunity.
video object  A Video object; required if this impression is offered as a video ad opportunity.
native object  A Native object; required if this impression is offered as a native ad opportunity. 
instl integer;
default 0
1 = the ad is interstitial or full screen, 0 = not interstitial.
tagid string Identifier for specific ad placement or ad tag that was used to initiate the auction. This can be useful for debugging of any issues, or for optimization by the buyer.
bidfloor float; default 0  Minimum bid for this impression expressed in CPM.
secure integer Flag to indicate if the impression requires secure HTTPS URL creative assets and markup, where 0 = non-secure, 1 = secure. If omitted, the secure state is unknown, but non-secure HTTP
support can be assumed.


2.1.3 Object: Banner

Attribute Type Description
w integer  Exact width in device independent pixels (DIPS);
recommended if no format objects are specified.
h integer  Exact height in device independent pixels (DIPS);
recommended if no format objects are specified.
battr integer array Blocked creative attributes. 

2.1.4 Object: Video

Attribute Type Description
mimes
string array; required
Content MIME types supported (e.g., “video/x-ms-wmv”, “video/mp4”).
minduration integer; recommended Minimum video ad duration in seconds.
maxduration integer; recommended  Maximum video ad duration in seconds.
protocols
integer array; recommended  Array of supported video protocols. At least one supported protocol must be specified in either the protocol or protocols attribute. 
w integer; recommended Width of the video player in device independent pixels (DIPS).
h integer; recommended Height of the video player in device independent pixels (DIPS).


2.1.5 Object: Native

Attribute Type Description
request  string; required Request payload complying with the Native Ad Specification.
ver string; recommended Version of the Dynamic Native Ads API to which request complies; highly recommended for efficient parsing.
battr  integer array  Blocked creative attributes.


2.1.6 Object: Site

Attribute Type Description
id string;
recommended
Exchange-specific site ID.
name string Site name (may be aliased at the publisher’s request).
domain string Domain of the site (e.g., “mysite.foo.com”).
cat string array  Array of IAB content categories of the site. 
pagecat string array  Array of IAB content categories that describe the current page
or view of the site. 
page string URL of the page where the impression will be shown.
publisher object  Details about the Publisher of the site.


2.1.7 Object: App

Attribute Type Description
id string; recommended  Exchange-specific app ID. 
name string App name (may be aliased at the publisher’s request).
bundle string A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame). On iOS, it is typically a numeric ID.
storeurl string    App store URL for an installed app; for IQG 2.1 compliance.


2.1.8 Object: Publisher

Attribute Type Description
id string Exchange-specific publisher ID.


2.1.9 Object: Device

Attribute Type Description
ua string;
recommended
Browser user agent string.
geo object;
recommended
Location of the device assumed to be the user’s current
location defined by a Geo object.
dnt integer;
recommended
Standard “Do Not Track” flag as set in the header by the
browser, where 0 = tracking is unrestricted, 1 = do not track.
ip string;
recommended
IPv4 address closest to device.
devicetype integer The general type of device. 
make string Device make (e.g., “Apple”).
model string Device model (e.g., “iPhone”).
os string Device operating system (e.g., “iOS”).
osv string Device operating system version (e.g., “3.1.2”).
js integer  Support for JavaScript, where 0 = no, 1 = yes.
language string Browser language using ISO-639-1-alpha-2.
carrier string Carrier or ISP (e.g., “VERIZON”) using exchange curated string
names which should be published to bidders a priori.
connectiontype integer Network connection type. 


2.1.10 Object: GEO

Attribute Type Description
type integer
Source of location data; recommended when passing
lat/lon. Refer to List 5.20.
country string Country code using ISO-3166-1-alpha-3.
region string Region code using ISO-3166-2; 2-letter state code if USA.
metro string
Google metro code; similar to but not exactly Nielsen DMAs.
See Appendix A for a link to the codes.
city string City using United Nations Code for Trade & Transport
Locations. See Appendix A for a link to the codes.
zip string Zip or postal code.


2.1.11 Object: User

Attribute Type Description
id string;
recommended
Exchange-specific ID for the user. At least one of id or
buyeruid is recommended.

2.2. Bid Request Example

{   "id": "1-e3241aed85d6ed4-482",

"imp": [       {

           "id": "3972",

           "banner": {

               "w": 320,

               "h": 50,

               "battr": [

                   1,

                   6,

                   8,

                   10,

                   14

               ]

           },

           "instl": 0,

           "tagid": "1087575",

           "bidfloor": 0.6883333333333334,

           "secure": 0

       }

   ],

   "site": {

       "id": "7662efc4ea7c",

       "name": "todays-headlines.mobileposse.com",

       "domain": "todays-headlines.mobileposse.com",

       "cat": [

           "IAB12"

       ],

       "pagecat": [

           "IAB12"

       ],

       "page": "http://todays-headlines.mobileposse.com/section/us?sch=pm&alias=nightnews&utm_medium=notification&mpnav=start",

       "publisher": {

           "id": "156078"

       }

   },

   "device": {

       "ua": "Mozilla/5.0 (Linux; Android 5.1.1; LGMS345 Build/LMY47V; wv) AppleWebKit/537.36 (KHTML, like Gecko) Version/4.0 Chrome/46.0.2490.76 Mobile Safari/537.36",

       "geo": {

           "type": 2,

           "country": "USA",

           "region": "pa",

           "metro": "504",

           "city": "philadelphia",

           "zip": "19130"

       },

       "dnt": 0,

       "ip": "208.54.90.178",

       "devicetype": 1,

       "make": "LG",

       "model": "MS345",

       "os": "android",

       "osv": "5.1.1",

       "js": 1,

       "language": "en",

       "carrier": "T-Mobile USA",

       "connectiontype": 3

   },

   "user": {

       "id": "100:user.id:b2da0a89b08e038451d7aeec93e19d263cfae274"

   },

   "at": 2,

   "tmax": 80,

   "cur": [

       "USD"

   ]

}


3.1. Bid Response Parameters


3.1.1 Object: BidResponse

Attribute Type Description
id string; required ID of the bid request to which this is a response.
bidid string Bidder generated response ID to assist with logging/tracking.
seatbid object array Array of seatbid objects; 1+ required if a bid is to be made.
cur string;
default “USD”
Bid currency using ISO-4217 alpha codes.


3.1.2 Object: SeatBid

Attribute Type Description
bid object array;
required
Array of 1+ Bid objects each related to an
impression. Multiple bids can relate to the same impression.
seat string ID of the buyer seat (e.g., advertiser, agency) on whose behalf
this bid is made.


3.1.3 Object: Bid

Attribute Type Description
id string; required Bidder generated bid ID to assist with logging/tracking.
adid string ID of a preloaded ad to be served if the bid wins.
nurl string Win notice URL called by the exchange if the bid wins (not
necessarily indicative of a delivered, viewed, or billable ad);
optional means of serving ad markup. Substitution macros
may be included in both the URL and optionally
returned markup.
price float; required Bid price expressed as CPM although the actual transaction is
for a unit impression only. Note that while the type indicates
float, integer math is highly recommended when handling
currencies (e.g., BigDecimal in Java).
impid string; required  ID of the Imp object in the related bid request.
crid string; required Creative ID to assist with ad quality checking.
cid string Campaign ID to assist with ad quality checking; the collection
of creatives for which iurl should be representative.
adomain string array Advertiser domain for block list checking (e.g., “ford.com”).
This can be an array of for the case of rotating creatives.
Exchanges can mandate that only one domain is allowed.
adm string Optional means of conveying ad markup in case the bid wins;
supersedes the win notice if markup is included in both.
Substitution macros may be included.
iurl string URL without cache-busting to an image that is representative
of the content of the campaign for ad quality/safety checking.
cat string array IAB content categories of the creative.
ext object Placeholder for bidder-specific extensions to OpenRTB.



3.2. Bid Response Example

{

   "id": "1-e3241aed85d6ed4-482",

   "bidid": "9966aeb821cd91479eddb0e31bfdc064",

   "seatbid": [

       {

           "bid": [

               {

                   "id": "5a02f0d1108921510142161",

                   "adid": "sf023eea64-96c7-473e-8cbd-0df53",

                   "nurl": "https://track.example.com/win?aid=${AUCTION_ID}&ap=${AUCTION_PRICE}&bid_id=${AUCTION_BID_ID}&imp_id=${AUCTION_IMP_ID}&ad_id=${AUCTION_AD_ID}&cur=${AUCTION_CURRENCY}&s1=v1AAEFAAir9.PCyHlVcwACBAAEAAAAVAATBAAEAAAAVAADBAAEAAAANAAEBgAIP_XCj1wo9cMABQYACD_1wo9cKPXDABEGAAg_8n752yLQ5gAGBwAfZGMwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAHBwAfeXUwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAIBwAfc2YwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAJBwABMQALBwAAAAwEAAQAAAAAAA0GAAg_wzMzMzMzMwAONgAAAA82AAAAEDgAAAASBwADVVNE&s2=aHR0cDovL3RyYWZmaWMuMTgwNS50ZWNoL3VzZXJzbnljLnBocD9wcmljZT0ke0FVQ1RJT05fUFJJQ0V9JmJpZF9pZD0ke0FVQ1RJT05fQklEX0lEfSZyZXFpZD0ke0FVQ1RJT05fSUR9JnJuPWZiZTg3ODc5ZTFiN2Y3MWNlY2NjMTE2Y2NjOWI2NGEwJmlwPTIwOC41NC45MC4xNzgwZTNjNzAxYy1lNDY3LTQ4YzItYTZmMy00YzA0YWMyNDhiZjkmZnJlcT0xMiZ0b2tlbj03NjYyZWZjNGVhN2MlN0MlN0MlN0N0b2RheXMtaGVhZGxpbmVzLm1vYmlsZXBvc3NlLmNvbSU0MDBlM2M3MDFjLWU0NjctNDhjMi1hNmYzLTRjMDRhYzI0OGJmOSZzaXRlX2lkPTc2NjJlZmM0ZWE3YyZjcD15dTAyM2VlYTY0LTk2YzctNDczZS04Y2JkLTBkZjUz",

                   "price": 1.156,

                   "impid": "1",

                   "crid": "yu023eea64-96c7-473e-8cbd-0df53",

                   "cid": "dc023eea64-96c7-473e-8cbd-0df53",

                   "adomain": [

                       "viber.com"

                   ],

                   "adm": "<img src=\"http://track.us.example.com/imp?aid=${AUCTION_ID}&ap=${AUCTION_PRICE}&s1=v1AAEFAAir9.PCyHlVcwACBAAEAAAAVAATBAAEAAAAVAADBAAEAAAANAAEBgAIP_XCj1wo9cMABQYACD_1wo9cKPXDABEGAAg_8n752yLQ5gAGBwAfZGMwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAHBwAfeXUwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAIBwAfc2YwMjNlZWE2NC05NmM3LTQ3M2UtOGNiZC0wZGY1MwAJBwABMQALBwAAAAwEAAQAAAAAAA0GAAg_wzMzMzMzMwAONgAAAA82AAAAEDgAAAASBwADVVNE\" width=\"0\" height=\"0\" style=\"display:none\"><script>var s_ad_pub = '156078' ,s_psid = '7662efc4ea7c' , s_bidvisi = 'ABF7E3C2C8795573' ,s_cli_ip = '208.54.90.178',s_cli_geo = 'USA' ,s_cli_spe = 'USA' ,s_cli_dev = '3' ,s_cli_os = 'android' ,s_cli_uuid = '0e3c701c-e467-48c2-a6f3-4c04ac248bf9' , s_pub_fingerprint = 'LiMTU2MTExNDIwMQ==', s_cli_dev_id = '12';</script><a href='https://play.google.com/store/apps/details?id=com.viber.voip'><img  src='https://s3.amazonaws.com/830d-4cd2-b585-2166481d/85-216.jpg' /></a>\r\n<script src=\"https://s3.amazonaws.com/830d-4cd2-b585-2166481d/35cae7.js\"></script>",

                   "iurl": "https://s3.amazonaws.com/smabfuihei/64a3ff2d7b4f3496beb0.png",

                   "cat": [

                       "IAB9"

                   ],

                   "ext": {

                       "imptrackers": []

                   }

               }

           ],

           "seat": "pio"

       }

   ],

   "cur": "USD"

}

Still need help? Contact Us Contact Us