DSP integration (experimental)#
Warning
This functionality is under development. Documentation can change at any time without notice.
AdServer (the supply part) can integrate with an external DSP (Demand Side Platform). The term “external DSP” should be understood as DSP outside the Adshares ecosystem.
This article describes interface which is required to assure communication between AdServer and external DSP. Later in article an external DSP will be referred as Bridge, because typical solution is to prepare a bridge between AdServer and existing DSP.
General assumptions#
Payments are credited by AdServer’s operator. Bridge can be trusted and credited payments will be paid by bridge. This can be changed to “Payments are credited by Bridge” when Bridge will support payments on ADS blockchain
Bridge is a microservice accessible by HTTP protocol on localhost. It does not expose any public endpoint
Bridge does not need to know all inventory (creatives’ content) like the demand part of AdServer, but should have minimal knowledge about it
AdServer configuration#
AdServer configuration requires:
Bridge’s URL address
Bridge’s Adshares account address
Bridge inventory#
Bridge should expose its inventory on /inventory endpoint.
The inventory format must comply with the standard format and match taxonomy.
Bridge does not have to store all DSP’s inventory. But it should at least know which creatives’ types, mimes, and scopes are supported by DSP.
Bridge events#
Bridge payments#
Instead of ADS transfers Bridge should provide payments data.
Bridge should expose payments’ details on /payments-details endpoint.
OpenRTB 2.6 integration#
This chapter covers integration between DSP bridge and DSP using OpenRTB 2.6 protocol. It contains excerpts from documentation supplemented with information about supported fields.
Object: BidRequest#
The auction type ‘at’ field is always set to 1 (first price auction).
The only supported currency ‘cur’ is USD.
The default value for ‘tmax’ is 1000 ms.
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
id |
string; required |
yes |
Unique ID of the bid request, provided by the exchange. |
imp |
object array; required |
yes |
Array of Imp objects representing the impressions offered. At least 1 Imp object is required. |
site |
object; recommended |
yes |
Details via a Site object about the publisher’s website. Only applicable and recommended for websites. |
app |
object; recommended |
no |
Details via an App object about the publisher’s app (i.e., non-browser applications). Only applicable and recommended for apps. |
dooh |
object |
no |
This object should be included if the ad supported content is a Digital Out-Of-Home screen. A bid request with a DOOH object must not contain a site or app object. |
device |
object; recommended |
yes |
Details via a Device object about the user’s device to which the impression will be delivered. |
user |
object; recommended |
yes |
Details via a User object about the human user of the device; the advertising audience. |
test |
integer; default 0 |
no |
Indicator of test mode in which auctions are not billable, where 0 = live mode, 1 = test mode. |
at |
integer; default 2 |
yes |
Auction type, where 1 = First Price, 2 = Second Price Plus. Exchange-specific auction types can be defined using values 500 and greater. |
tmax |
integer |
no |
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. |
wseat |
string array |
no |
Allowed list of buyer seats (e.g., advertisers, agencies) allowed to bid on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions. |
bseat |
string array |
no |
Block list of buyer seats (e.g., advertisers, agencies) restricted from bidding on this impression. IDs of seats and knowledge of the buyer’s customers to which they refer must be coordinated between bidders and the exchange a priori. At most, only one of wseat and bseat should be used in the same request. Omission of both implies no seat restrictions. |
allimps |
integer; default 0 |
no |
Flag to indicate if Exchange can verify that the impressions offered represent all of the impressions available in context (e.g., all on the web page, all video spots such as pre/mid/post roll) to support road-blocking. 0 = no or unknown, 1 = yes, the impressions offered represent all that are available. |
cur |
string array |
no |
Array of allowed currencies for bids on this bid request using ISO-4217 alpha codes. Recommended only if the exchange accepts multiple currencies. |
wlang |
string array |
no |
Allowed list of languages for creatives using ISO-639-1-alpha-2. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the Device and/or Content objects if available. Only one of wlang or wlangb should be present. |
wlangb |
string array |
no |
Allowed list of languages for creatives using IETF BCP 47I. Omission implies no specific restrictions, but buyers would be advised to consider language attribute in the Device and/or Content objects if available. Only one of wlang or wlangb should be present. |
bcat |
string array |
no |
Blocked advertiser categories using the specified category taxonomy. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied IAB Content Taxonomy 1.0 is assumed. |
cattax |
integer; default 1 |
no |
The taxonomy in use for bcat. Refer to the AdCOM 1.0 list List: Category Taxonomies for values. |
badv |
string array |
no |
Block list of advertisers by their domains (e.g., “ford.com”). |
bapp |
string array |
no |
Block list of applications by their app store IDs. See OTT/CTV Store Assigned App Identification Guidelines for more details about expected strings for CTV app stores. For mobile apps in Google Play Store, these should be bundle or package names (e.g. com.foo.mygame). For apps in Apple App Store, these should be a numeric ID. |
source |
object |
no |
A Source object that provides data about the inventory source and which entity makes the final decision. |
regs |
object |
no |
A Regs object that specifies any industry, legal, or governmental regulations in force for this request. |
ext |
object |
no |
Placeholder for exchange-specific extensions to OpenRTB. |
Object: Imp#
Only banner impressions are supported. Creative content can be image and/or video.
No interstitial ads are supported. The ‘instl’ attribute is not supported.
The only supported currency ‘bidfloorcur’ is USD.
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
id |
string; required |
yes |
A unique identifier for this impression within the content of the bid request (typically, starts with 1 and increments). |
metric |
object array |
no |
An array of Metric object. |
banner |
object |
yes |
A Banner object; required if this impression is offered as a banner ad opportunity. |
video |
object |
no |
A Video object; required if this impression is offered as a video ad opportunity. |
audio |
object |
no |
An Audio object; required if this impression is offered as an audio ad opportunity. |
native |
object |
no |
A Native object; required if this impression is offered as a native ad opportunity. |
pmp |
object |
no |
A Pmp object containing any private marketplace deals in effect for this impression. |
displaymanager |
string |
no |
Name of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps. |
displaymanagerver |
string |
no |
Version of ad mediation partner, SDK technology, or player responsible for rendering ad (typically video or mobile). Used by some ad servers to customize ad code by partner. Recommended for video and/or apps. |
instl |
integer; default 0 |
no |
1 = the ad is interstitial or full screen, 0 = not interstitial. |
tagid |
string |
no |
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 |
no |
Minimum bid for this impression expressed in CPM. |
bidfloorcur |
string; default “USD” |
no |
Currency specified using ISO-4217 alpha codes. This may be different from bid currency returned by bidder if this is allowed by the exchange. |
clickbrowser |
integer |
no |
Indicates the type of browser opened upon clicking the creative in an app, where 0 = embedded, 1 = native. Note that the Safari View Controller in iOS 9.x devices is considered a native browser for purposes of this attribute. |
secure |
integer |
no |
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. |
iframebuster |
string array |
no |
Array of exchange-specific names of supported iframe busters. |
rwdd |
integer; default 0 |
no |
Indicates whether the user receives a reward for viewing the ad, where 0 = no, 1 = yes. Typically video ad implementations allow users to read an additional news article for free, receive an extra life in a game, or get a sponsored ad-free music session. The reward is typically distributed after the video ad is completed. |
ssai |
integer; default 0 |
no |
Indicates if server-side ad insertion (e.g., stitching an ad into an audio or video stream) is in use and the impact of this on asset and tracker retrieval, where 0 = status unknown, 1 = all client-side (i.e., not server-side), 2 = assets stitched server-side but tracking pixels fired client-side, 3 = all server-side. |
exp |
integer |
no |
Advisory as to the number of seconds that may elapse between the auction and the actual impression. |
qty |
object |
no |
A means of passing a multiplier in the bid request, representing the total quantity of impressions for adverts that display to more than one person. |
dt |
float |
no |
Timestamp when the item is estimated to be fulfilled (e.g. when a DOOH impression will be displayed) in Unix format (i.e., milliseconds since the epoch). |
refresh |
object |
no |
Details about ad slots being refreshed automatically. (Section 3.2.33) |
refsettings |
object |
no |
Details about ad slots being refreshed automatically. (Section 3.2.33) |
ext |
object |
no |
Placeholder for exchange-specific extensions to OpenRTB. |
Object: Format#
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
w |
integer |
yes |
Width in device independent pixels (DIPS). |
h |
integer |
yes |
Height in device independent pixels (DIPS). |
wratio |
integer |
no |
Relative width when expressing size as a ratio. |
hratio |
integer |
no |
Relative height when expressing size as a ratio. |
wmin |
integer |
no |
The minimum width in device independent pixels (DIPS) at which the ad will be displayed the size is expressed as a ratio. |
ext |
object |
no |
Placeholder for exchange-specific extensions to OpenRTB. |
Object: Site#
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
id |
string; recommended |
no |
Exchange-specific site ID. |
name |
string |
no |
Site name (may be aliased at the publisher’s request). |
domain |
string |
yes |
Domain of the site (e.g., “mysite.foo.com”). |
cattax |
integer |
no |
The taxonomy in use. Refer to the AdCOM List: Category Taxonomies for values. If no cattax field is supplied IAB Cotent Category Taxonomy 1.0 is assumed. |
cat |
string array |
no |
Array of IAB Tech Lab content categories of the site. The taxonomy to be used is defined by the cattax field. |
sectioncat |
string array |
no |
Array of IAB Tech Lab content categories that describe the current section of the site. The taxonomy to be used is defined by the cattax field. |
pagecat |
string array |
no |
Array of IAB Tech Lab content categories that describe the current page or view of the site. The taxonomy to be used is definied by the cattax field. |
page |
string |
yes |
URL of the page where the impression will be shown. |
ref |
string |
no |
Referrer URL that caused navigation to the current page. |
search |
string |
no |
Search string that caused navigation to the current page. |
mobile |
integer |
no |
Indicates if the site has been programmed to optimize layout when viewed on mobile devices, where 0=no, 1=yes. |
privacypolicy |
integer |
no |
Indicates if the site has a privacy policy, where 0 = no, 1 = yes. |
publisher |
object |
no |
Details about the Publisher of the site. |
content |
object |
no |
Details about the Content within the site. |
keywords |
string |
no |
Comma separated list of keywords about the site. Only one of keywords or kwarray may be present. |
kwarray |
string array |
no |
Array of keywords about the site. Only one of keywords or kwarray may be present. |
ext |
object |
no |
Placeholder for exchange-specific extensions to OpenRTB. |
Object: Device#
Only one IP address of the device is present - IPv4 ‘ip’ or IPv6 ‘ipv6’.
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
geo |
object; recommended |
no |
Location of the device assumed to be the user’s current location defined by a Geo object. |
dnt |
integer; recommended |
no |
Standard “Do Not Track” flag as set in the header by the browser, where 0 = tracking is unrestricted, 1 = do not track. |
lmt |
integer; recommended |
no |
“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines. |
ua |
string |
yes |
Browser user agent string. This field represents a raw user agent string from the browser. For backwards compatibility, exchanges are recommended to always populate ua with the User-Agent string, when available from the end user’s device, even if an alternative representation, such as the User-Agent Client-Hints, is available and is used to populate sua. No inferred or approximated user agents are expected in this field. If a client supports User-Agent Client Hints, and sua field is present, bidders are recommended to rely on sua for detecting device type, browser type and version and other purposes that rely on the user agent information, and ignore ua field. This is because the ua may contain a frozen or reduced user agent string. |
sua |
object |
no |
Structured user agent information defined by a UserAgent object. If both ua and sua are present in the bid request, sua should be considered the more accurate representation of the device attributes. This is because the ua may contain a frozen or reduced user agent string. |
ip |
string |
yes |
IPv4 address closest to device. |
ipv6 |
string |
yes |
IP address closest to device as IPv6. |
devicetype |
integer |
no |
The general type of device. Refer to List: Device Types in AdCOM 1.0. |
make |
string |
no |
Device make (e.g., “Apple”). |
model |
string |
no |
Device model (e.g., “iPhone”). |
os |
string |
no |
Device operating system (e.g., “iOS”). |
osv |
string |
no |
Device operating system version (e.g., “3.1.2”). |
hwv |
string |
no |
Hardware version of the device (e.g., “5S” for iPhone 5S). |
h |
integer |
no |
Physical height of the screen in pixels. |
w |
integer |
no |
Physical width of the screen in pixels. |
ppi |
integer |
no |
Screen size as pixels per linear inch. |
pxratio |
float |
no |
The ratio of physical pixels to device independent pixels. |
js |
integer |
no |
Support for JavaScript, where 0 = no, 1 = yes. |
geofetch |
integer |
no |
Indicates if the geolocation API will be available to JavaScript code running in the banner, where 0 = no, 1 = yes. |
flashver |
string |
no |
Version of Flash supported by the browser. |
language |
string |
no |
Browser language using ISO-639-1-alpha-2. Only one of language or langb should be present. |
langb |
string |
no |
Browser language using IETF BCP 47. Only one of language or langb should be present. |
carrier |
string |
no |
Carrier or ISP (e.g., “VERIZON”) using exchange curated string names which should be published to bidders a priori. |
mccmnc |
string |
no |
Mobile carrier as the concatenated MCC-MNC code (e.g., “310-005” identifies Verizon Wireless CDMA in the USA). Refer to https://en.wikipedia.org/wiki/Mobile_country_code for further examples. Note that the dash between the MCC and MNC parts is required to remove parsing ambiguity. The MCC-MNC values represent the SIM installed on the device and do not change when a device is roaming. Roaming may be inferred by a combination of the MCC-MNC, geo, IP and other data signals. |
connectiontype |
integer |
no |
Network connection type. Refer to List: Connection Types in AdCOM 1.0. |
ifa |
string |
no |
ID sanctioned for advertiser use in the clear (i.e., not hashed). |
didsha1 |
string; DEPRECATED |
no |
Hardware device ID (e.g., IMEI); hashed via SHA1. |
didmd5 |
string; DEPRECATED |
no |
Hardware device ID (e.g., IMEI); hashed via MD5. |
dpidsha1 |
string; DEPRECATED |
no |
Platform device ID (e.g., Android ID); hashed via SHA1. |
dpidmd5 |
string; DEPRECATED |
no |
Platform device ID (e.g., Android ID); hashed via MD5. |
macsha1 |
string; DEPRECATED |
no |
MAC address of the device; hashed via SHA1. |
macmd5 |
string; DEPRECATED |
no |
MAC address of the device; hashed via MD5. |
ext |
object |
no |
Placeholder for exchange-specific extensions to OpenRTB. |
Object: User#
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
id |
string |
yes |
Exchange-specific ID for the user. |
buyeruid |
string |
no |
Buyer-specific ID for the user as mapped by the exchange for the buyer. |
yob |
integer; DEPRECATED |
no |
Year of birth as a 4-digit integer. |
gender |
string; DEPRECATED |
no |
Gender, where “M” = male, “F” = female, “O” = known to be other (i.e., omitted is unknown). |
keywords |
string |
no |
Comma separated list of keywords, interests, or intent. Only one of keywords or kwarray may be present. |
kwarray |
string array |
no |
Array of keywords about the user. Only one of keywords or kwarray may be present. |
customdata |
string |
no |
Optional feature to pass bidder data that was set in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. |
geo |
object |
no |
Location of the user’s home base defined by a Geo object (Section 3.2.19). This is not necessarily their current location. |
data |
object array |
no |
Additional user data. Each Data object (Section 3.2.21) represents a different data source. |
consent |
string |
no |
When GDPR regulations are in effect this attribute contains the Transparency and Consent Framework’s Consent String data structure. |
eids |
object array |
no |
Details for support of a standard protocol for multiple third party identity providers. |
ext |
object |
no |
Placeholder for exchange-specific extensions to OpenRTB. |
Object: BidResponse#
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
id |
string; required |
yes |
ID of the bid request to which this is a response. |
seatbid |
object array |
yes |
Array of seatbid objects; 1+ required if a bid is to be made. |
bidid |
string |
no |
Bidder generated response ID to assist with logging/tracking. |
cur |
string; default “USD” |
no |
Bid currency using ISO-4217 alpha codes. |
customdata |
string |
no |
Optional feature to allow a bidder to set data in the exchange’s cookie. The string must be in base85 cookie safe characters and be in any format. Proper JSON encoding must be used to include “escaped” quotation marks. |
nbr |
integer |
no |
Reason for not bidding. Refer to List: No-Bid Reason Codes in OpenRTB 3.0. |
ext |
object |
no |
Placeholder for bidder-specific extensions to OpenRTB. |
Object: SeatBid#
If ‘group’ property is set to 1, bids will be rejected.
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
bid |
object array; required |
yes |
Array of 1+ Bid objects each related to an impression. Multiple bids can relate to the same impression. |
seat |
string |
no |
ID of the buyer seat (e.g., advertiser, agency) on whose behalf this bid is made. |
group |
integer; default 0 |
no |
0 = impressions can be won individually; 1 = impressions must be won or lost as a group. |
ext |
object |
no |
Placeholder for bidder-specific extensions to OpenRTB. |
Object: Bid#
The ‘nurl’ URL is called on serve event. The ‘burl’ URL is called on view event.
Attribute |
Type |
Supported |
Description |
|---|---|---|---|
id |
string; required |
no |
Bidder generated bid ID to assist with logging/tracking. |
impid |
string; required |
yes |
ID of the Imp object in the related bid request. |
price |
float; required |
yes |
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). |
nurl |
string |
yes |
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. |
burl |
string |
yes |
Billing notice URL called by the exchange when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.). Substitution macros may be included. |
lurl |
string |
no |
Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros may be included. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed (i.e., replaced with a zero-length string). |
adm |
string |
no |
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. |
adid |
string |
no |
ID of a preloaded ad to be served if the bid wins. |
adomain |
string array |
no |
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. |
bundle |
string |
no |
The store ID of the app in an app store (e.g., Apple App Store, Google Play). See OTT/CTV Store Assigned App Identification Guidelines for more details about expected strings for CTV app stores. For mobile apps in Google Play Store, these should be bundle or package names (e.g. com.foo.mygame). For apps in Apple App Store, these should be a numeric ID. |
iurl |
string |
no |
URL without cache-busting to an image that is representative of the content of the campaign for ad quality/safety checking. |
cid |
string |
no |
Campaign ID to assist with ad quality checking; the collection of creatives for which iurl should be representative. |
crid |
string |
no |
Creative ID to assist with ad quality checking. |
tactic |
string |
no |
Tactic ID to enable buyers to label bids for reporting to the exchange the tactic through which their bid was submitted. The specific usage and meaning of the tactic ID should be communicated between buyer and exchanges a priori. |
cattax |
integer; default 1 |
no |
The taxonomy in use. Refer to List: Category Taxonomies for values. |
cat |
string array |
no |
IAB Tech Lab content categories of the creative. The taxonomy to be used is defined by the cattax field. If no cattax field is supplied Content Taxonomy 1.0 is assumed |
attr |
integer array |
no |
Set of attributes describing the creative. Refer to List: Creative Attributes in AdCOM 1.0. |
apis |
integer array |
no |
List of supported APIs for the markup. If an API is not explicitly listed, it is assumed to be unsupported. Refer to List: API Frameworks in AdCOM 1.0. |
api |
integer; DEPRECATED |
no |
NOTE: Deprecated in favor of the apisinteger array. API required by the markup if applicable. Refer to List: API Frameworks in AdCOM 1.0. |
protocol |
integer |
no |
Video response protocol of the markup if applicable. Refer to List: Creative Subtypes - Audio/Video in AdCOM 1.0. |
qagmediarating |
integer |
no |
Creative media rating per IQG guidelines. Refer to List: Media Ratings in AdCOM 1.0. |
language |
string |
no |
Language of the creative using ISO-639-1-alpha-2. The non- standard code “xx” may also be used if the creative has no linguistic content (e.g., a banner with just a company logo). Only one of language or langb should be present. |
langb |
string |
no |
Language of the creative using IETF BCP 47. Only one of language or langb should be present. |
dealid |
string |
no |
Reference to the deal.id from the bid request if this bid pertains to a private marketplace direct deal. |
w |
integer |
no |
Width of the creative in device independent pixels (DIPS). |
h |
integer |
no |
Height of the creative in device independent pixels (DIPS). |
wratio |
integer |
no |
Relative width of the creative when expressing size as a ratio. Required for Flex Ads. |
hration |
integer |
no |
Relative height of the creative when expressing size as a ratio. Required for Flex Ads. |
exp |
integer |
no |
Advisory as to the number of seconds the bidder is willing to wait between the auction and the actual impression. |
dur |
integer |
no |
Duration of the video or audio creative in seconds. |
mtype |
integer |
no |
Type of the creative markup so that it can properly be associated with the right sub-object of the BidRequest.Imp. Values: 1 = Banner, 2 = Video, 3 = Audio, 4 = Native |
slotinpod |
integer; default 0 |
no |
Indicates that the bid response is only eligible for a specific position within a video or audio ad pod (e.g. first position, last position, or any). Refer to List: Slot Position in Pod in AdCOM 1.0 for guidance on the use of this field. |
ext |
object |
no |
Placeholder for bidder-specific extensions to OpenRTB. |