AdSpirit currently implemented the OpenRTB 2.5 specification as described under http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-API-Specification-Version-2-5-FINAL.pdf. AdSpirit supports OpenRTB for both ways, buyside and sellside / requests and responses. Also AdSpirit supports OpenRTB Dynamic Native Ads API V1.1 (http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) in both directions.
1. Used extensions
OpenRTB allows adding new properties via the "ext" object. AdSpirit uses this object to add some information needed by AdSpirit and/or the bidder/seller. These extensions are:
- AdSpirit will add bidresponse -> seatbid -> bid -> ext -> defaultpixel to the bid-response. The defaultpixel property can be used to transmit additional pixels (HTML markup) from the advertiser to the adserver to be served with the creative – even if the advertiser does not win the auction the pixels shall be shown. It is recommended that exchanges/publishers allow advertisers who use AdSpirit as their bidding adserver to transmit additional codes via this property.
- AdSpirit will add bidrequest -> ext -> pageviewid and pagevieworder to the bid-request. The property pageviewid can be used in order to match multiple requests on the same pageview. The property pagevieworder can be used in order to determine the context of the current ad in regards of the pageview.
2. Limitations
AdSpirit supports all required OpenRTB objects and properties. Nevertheless AdSpirit will handle some things different as described in the OpenRTB specs:
-
website-endpoint (uses &wsid=X as parameter instead of &pid=X) AdSpirit requires the properties bidrequest -> imp -> banner/video -> w and bidrequest -> imp -> banner/video -> h to be present.
• AdSpirit recommends an advertiser to send the creative markup via bidresponse -> seatbid -> bid -> adm instead of "nurl". If "adm" and "nurl" are present, AdSpirit will use the markup from "adm" and add the url supplied in "nurl" as a 1x1 pixel to the "adm"-markup.
• If you want AdSpirit to send markup via "nurl" property instead of "adm", you must add the parameter &usenurl=1 to the entpoint-URL (see Endpoint URL configuration). Otherwise AdSpirit will send all markup via "adm" property and pass a blank url (1x1 Pixel without any functionality) as value of "nurl".
• By default, AdSpirit will urlencode the markup supplied in "adm". If you want to receive the markup in un-encoded form, please add parameter &admnoenc=1
• AdSpirit does not support the macros ${AUCTION_CURRENCY} and ${AUCTION_PRICE:X} where X is the used encryption algorithm. If you like to get pricing information please only use ${AUCTION_PRICE} and set the encryption algorithm in the AdSpirit frontend.
.
3. Price encryption
AdSpirit prefers to use a SHA1 encrypted price transmission with a 32 byte encryption key and a 32 byte integrity key. If other encryption methods should be used, this can be set in the AdSpirit frontend.
4. Response times
AdSpirit requires an answer bid within 100ms.
5. Pre-filtering & QPS
AdSpirit can pre-filter bid-requests before send to the advertiser’s bidder. These filters include ad-sizes, geo, operating system, language and others as well as frequency-capping(s). Pre-filtering can be set via the AdSpirit frontend.
AdSpirit can also control the maximum queries per second (QPS) send from AdSpirit to the advertiser’s bidder. The QPS are set on campaign and creative level. AdSpirit can also set minimum answer-rates and minimum win-rates as well as maximum error-rates. If the advertisers results are below/above these rates, the current QPS will be decreased.
6. Endpoint-URL configuration
AdSpirit will provide an endpoint URL in order to connect to the AdServer. This URL usually look like
http://clientname.adspirit.de/rtb/getbid.php?...
The url can use the following parameters. Most parameters are optional:
|
Parameter |
Description |
|
&wsid= (sometimes &pid= or &pnm= are used) |
Integer. AdSpirits internal ID for this connection |
|
&rtbprovider= or &rtb= |
String. Description of the protocol used. For OpenRTB use "openrtb" as value |
|
&useprenca= or &upa= |
String. Description of which price encoding macro AdSpirit shall output with the code. (Value "&upa=-x-" can be used as a synonym for &useprenca=${AUCTION_PRICE} |
|
&useprencmode= or &upm= |
Char. Description of which price encryption mode is used by AdSpirit. |
|
&dataid= |
Integer. AdSpirits internal ID for the user-syncing database. |
|
&asm= |
Integer. AdSpirits internal ID for this client. This parameter is mandatory if you bidder is not able to send HTTP Host-Header. |
|
&outputfilter= or &opf= |
String. Description if the output generated by AdSpirit should be transformed in a certain way. |
|
&oneline=1 |
Integer. If present, indicates that the output code shall be in one single code-line. |
|
&ignoremime=1 or &igm=1 |
Integer. If present, indicates that AdSpirit shall ignore the mime-header send via OpenRTB blocklist. |
|
&ignorebytpe=1 or &igb=1 |
Integer. If present, indicates that AdSpirit shall ignore the btype-header send via OpenRTB blocklist. |
|
&ignorebattr=1 or &iga=1 |
Integer. If present, indicates that AdSpirit shall ignore the battr-header send via OpenRTB blocklist. |
|
&admnoenc=1 |
Integer. If present, indicates that the "adm" output will NOT be urlencoded. |
|
&usenurl=1 |
Integer. If present, AdSpirit will send bid responses with a fully valid and functional "nurl" property. The URL provided with this property must then be used in order to receive the html-markup. If present, AdSpirit will not send the "adm" property. |
|
&setseatid |
String. If present, AdSpirit will set this value as "seat" object in bid response. |
|
&noext=1 |
Integer. If present, AdSpirit will not send "ext" objects in bid response. |
|
&nonurl=1 or &nnu=1 |
Integer. If present, AdSpirit will not send "nurl" property in bid response. |
|
&nocid=1 |
Integer. If present, AdSpirit will not send "cid" properties in bid response. |
|
&nocrid=1 |
Integer. If present, AdSpirit will not send crid |
|
&nopixel=1 |
Integer. If present, AdSpirit will not send ext -> defaultpixel. |
|
&allowzerobid=1 |
Integer. If present, AdSpirit will respond with HTML-codes ("adm") even in case the bid is 0.00 (Zero). |
|
&add_advname=1 |
Integer. If present, AdSpirit will add a property ext -> advname with the Advertisername in it. |
|
&add_agencyname=1 |
Integer. If present, AdSpirit will add a property ext -> agencyname with the Agencyname in it. |
|
&add_avn=1 |
Integer. If present, AdSpirit will add a property ext -> avn with the Advertisername in it. |
|
&add_agn=1 |
Integer. If present, AdSpirit will add a property ext -> agn with the Agencyname in it. |
7. Native Ads via OpenRTB
AdSpirit fully supports OpenRTB extension Native Ads V1.1 (as described in http://www.iab.com/wp-content/uploads/2016/03/OpenRTB-Native-Ads-Specification-1-1_2016.pdf) in both directions (buyer/seller). As the design of the native ads assetts are fully up to the seller, please make sure that both match their settings before using Native Ads.