How to Integrate Demand Partners (DSPs)
Contents
1. DSP Integration Process
In order to integrate a DSP, please follow these steps:
- Create a campaign and ad group (strategy) with specific targeting parameters (traffic with such parameters will be sent to the external DSP)
- Send us an endpoint URL issued by the DSP. This URL will be implemented by our tech team
- Once we confirm the URL has been impelemented, run a short test and compare the stats with the DSP in a day or two (impressions, total ad cost)
- 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
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"
}