Ströer SSP OpenRTB

API History
General
Bid Request
Bid Response
Win, Loss and Error Notifications (Legacy)
Auction Price Encryption
- Requirements
- Notation
  - Examples
- Encryption
  - Input
  - Pseudocode
- Decryption
  - Input
  - Pseudocode
- Test Data
- Sample Code

API History

Version	Date	Description
1.00	22/08/2018	Support for Format object and Format Extension object (for special formats) - both in the context of open auction.
1.01	09/10/2018	Support for Bid`.lurl`.
1.02	20/12/2018	Remapped loss reason 1103 to 205
1.03	28/06/2019	Added support for Native Advertisement V1.2
1.04	21/08/2019	Added support for Supply Chain object.
1.05	08/04/2020	Removed support for postview
1.06	04/08/2020	Add `missingCompanionBid` loss reason definition
1.07	22/02/2021	Added support for HTTP/2
1.08	01/03/2021	Add `mediaFileUrlChangedBlocked` loss reason definition
1.09	26/07/2021	Documented supported fields that hadn’t been added to this API doc: * Video: pos, maxbitrate, sequence, playbackmethod, placement * App: storeurl, name, ver * User: added ext for external user IDs and TCF consent * SupplyChain: ver * Device: lmt, mccmnc, pxratio, w, h, connectionType * Site: added ext for `amp` indication
1.10	03/08/2021	* Documented `privacy` support in Native Markup Request Object and Native Markup Response Object. * Bid request and response compression support.
1.11	22/10/2021	Change connection type field in the device geo object from connectionType to connectiontype to match OpenRTB spec
1.12	08/11/2021	Added new fields we receive from GetPublica and forward to dsp partners
1.13	09/11/2021	Support app.content.url and device.ext.ifa_type
1.14	22/11/2021	Support for more external user IDs: `netid` and Stroeer Universal User ID as `uid.stroeer.com`
1.15	16/02/2022	Support device.ext.ssat and device.ext.ifv
1.16	19/04/2022	Renamed removed prefix content_ from Content Ext object nodes.
1.17	22/07/2022	Add Open Measurement fields, omidpv and omidpn, to Source Extension Object
1.18	09/02/2023	Add `floor` loss reason definition - where bid price was below bid floor
1.19	01/02/2024	Support for Digital Services Act (DSA) as per OpenRTB Spec. This introduces the Regulations object in the bid request. DSA for the bid request and DSA for the bid response.
1.20	02/02/2024	Support plcmt Video object specs and List of plcmt types

General

This document outlines outlines the objects and attributes supported by the Ströer SSP for the OpenRTB API v2.5.

The Ströer SSP supports two styles of bid requesting:

(a) a single impression in one bid request.
(b) multiple impressions in one bid request.

Please indicate on account setup which style of bid requesting you prefer.

Please note, with the introduction of the Format object the Bid object needs always to included the width and height.

Foreign Currencies Support

By default, all bids and prices in the API calls are in Euro (EUR).

If required by an RTB partner, this can be changed to US-Dollar (USD). It is an internal and a per-DSP partner setting in the Ströer SSP adserver, affecting all calls between the RTB partner and Ströer SSP.

The Ströer SSP auction runs in Euro (EUR). Therefore, all bids in USD are converted to EUR using a daily exchange rate before adding the bid to the auction. Prices in the legacy win/loss notification calls or in the auction price substitution macro will be converted back to US-Dollar.

Ströer SSP keeps a history of the daily exchange rates.

Ad Serving Option

For both, display and video, Ströer SSP supports ad serving in the bid, ie., the ad markup is returned directly in the bid itself using the bidresponse.seatbid.bid.adm attribute. Please see also the bid.nurl handling for video with respect to the VAST tag.

Native Advertisement Support

Native advertisement support is based on OpenRTB Dynamic Native Ads API Specification Version 1.1. Please specify with your account manager

which version of OpenRTB API you are supporting for native ad requests.
whether you are supporting JSON or JSON-encoded String in impression.native.request
whether you are passing the native ad markup in bid.adm as JSON or JSON-encoded String.

Currently supported assets are title, text, brand and image (see Native) object.

Bid Request

HTTP Versions

By default, requests are made using HTTP/1.1 with connection keep-alive enabled.

HTTP/2 support is available by request. Ideally HTTP/2 is enabled via ALPN as part of the TLS secure handshake. If HTTP/2 support enabled over an insecure link a h2c upgrade will be attempted.

HTTP Headers

The following headers are sent with the HTTP POST request:

Header	Description
`Content-Type`	The length of the request body.
`Content-Length`	The content type of the request. It’s value is `application/json`.
`Content-Encoding`	Bid request compression is available on request. Value is `gzip`. Bid response compression is handled automatically if indicated in the response headers.
`Host`	The domain of the bidding URL.
`x-openrtb-version`	Default value is `2.5`.

Bid Request Object

Either site or app must be set

Field	Scope	Type	Description
`id`	Always	string	Unique impression identifier.
`source`	Optional	object	A Source object that provides data about the inventory source and which entity makes the final decision.
`imp`	Always	object	Array of Impression Objects.
`site`	Optional	object	Set if App object not available. See Site Object.
`app`	Optional	object	See App Object.
`device`	Always	object	See Device Object.
`regs`	Optional	object	See Regulations Object.
`user`	Always	object	See User Object.
`tmax`	Always	integer	Maximum amount of time in milliseconds to submit a bid.
`at`	Always	integer	Auction type, where 1 = First Price, 2 = Second Price.

Source Object

Field	Scope	Type	Description
`ext`	Always	object	See Source Extension Object

Source Extension Object

Field	Scope	Type	Description
`schain`	Optional	object	Placeholder extension for Supply Chain object as recommended in IAB OpenRTB SupplyChain object doc.
`omidpn`	Optional	string	An identifier for the Open Measurement SDK integration. This is the same as the `name` parameter of the OMID Partner object.
`omidpv`	Optional	string	The version of the Open Measurement SDK integration. This is the same as the `versionString` parameter of the OMID Partner object.

Note: The omid fields are in addition to the API frameworks array on the impression. The array must include the value 7 to indicate OMID 1.0 support.

Supply Chain Object

The Supply Chain object is referenced as schain as in source.ext.schain

Field	Scope	Type	Description
`complete`	Always	integer	Flag indicating whether the chain contains all nodes involved in the transaction leading back to the owner of the site, app or other medium of the inventory, where 0 = no, 1 = yes. Defaults to `0`.
`nodes`	Always	object array	Array of Supply Chain Node objects in the order of the chain. In a complete supply chain, the first node represents the initial advertising system and seller ID involved in the transaction, i.e. the owner of the site, app, or other medium. In an incomplete supply chain, it represents the first known node. The last node represents the entity sending this bid request.
`ver`	Always	string	Version of the supply chain specification in use, in the format of “major.minor”.

Supply Chain Node Object

Field	Scope	Type	Description
`asi`	Always	string	The canonical domain name of the SSP, Exchange, Header Wrapper, etc system that bidders connect to. This may be the operational domain of the system, if that is different than the parent corporate domain, to facilitate WHOIS and reverse IP lookups to establish clear ownership of the delegate system. This should be the same value as used to identify sellers in an ads.txt file if one exists. Defaults to `stroeer.com`.
`sid`	Always	string	The identifier associated with the seller or reseller account within the advertising system. This is the same as in `publisher.id`.
`rid`	Always	string	The same as `request.id`.
`hp`	Always	integer	Indicates whether this node will be involved in the flow of payment for the inventory. Set to `1`.

Impression Object

Field	Scope	Type	Description
`id`	Always	string	Unique identifier of an impression within the request. Starts with `1`.
`tagid`	Always	string	Unique identifier of the slot.
`banner`	Optional	object	See Banner Object.
`video`	Optional	object	See Video Object.
`native`	Optional	object	See Native Object.
`pmp`	Optional	object	See PMP Object.
`instl`	Optional	integer	`1` if the ad is interstitial or full screen; else `0` (i.e., no)
`secure`	Optional	integer	Flag to indicate whether the impression requires secure HTTPS URL creative assets and markup. A value of `1` means that the impression requires secure assets. A value of `0` means non-secure assets.
`ext`	Always	object	See Impression Extension Object.

Note: In the case of an secure bid request the creative asset/markup is validated for secure content. Should the validation fail a loss notification with the reason insecureCreative is send (if loss notification is enabled in the partner setup)

Impression Extension Object

For native ad bidding, the iframe and position give additional information about the native ad placement.

Field	Scope	Type	Description
`iframe`	Optional	boolean	Indicates if a native ad is in an iframe or not.
`position`	Optional	integer	The native ad position on the screen. Values follow the OpenRTB definition of the `impression.banner.pos` field: `0` (unknown), `1` (above the fold), `3` (below the fold).

Field	Scope	Type	Description
`format`	Always	object array	Array of Format objects representing the banner sizes permitted.
`wmax`	Optional	integer	The maximum width of the impression in pixels. If included the `w` field is omitted.
`hmax`	Optional	integer	The maximum height of the impression in pixels. If included the `h` field is omitted.
`wmin`	Optional	integer	The minimum width of the impression in pixels. If included the `w` field is omitted.
`hmin`	Optional	integer	The minimum height of the impression in pixels. If included the `h` field is omitted.
`pos`	Optional	integer	Ad position. `0` (unknown), `1` (above the fold), `3` (below the fold).
`topframe`	Optional	integer	Specify if the banner is delivered in the top frame or in an iframe. `1` for top frame, `0` for iframe.
`expdir`	Optional	integer array	An array of expansion directions 1=left, 2=right, 3=up, 4=down, 5=fullscreen
`api`	Optional	integer array	List of supported API frameworks for this impression. See list of api frameworks
`ext`	Optional	object	See Banner Extension Object.

Field	Scope	Type	Description
`popunder`	Optional	integer	`1` for popunder, `0` not a popunder advert.
`lightbox`	Optional	integer	`1` for interstitial. Indicates that a half transparent, full size layer is placed above the site content surrounding the ad.

Format Object

This object was introduced in OpenRTB API v2.4.

Field	Scope	Type	Description
`w`	Always	integer	Width in device independent pixels (DIPS).
`h`	Always	integer	Height in device independent pixels (DIPS).
`ext`	Optional	object	The Format Extension Object to define special formats.

Format Extension Object

Field	Scope	Type	Description
`sticky`	Optional	integer	`1` for floor adverts. Indicates that the advert is fixed vertically and does not move as the site content is scrolled.
`scaling`	Optional	integer	`1` for dynamic sitebar.

Note, the two fields are not provided in the Banner Extension Object if Format Object is used.

Video Object

Field	Scope	Type	Description
`mimes`	Always	string array	Supported Content MIME types: video/avi, video/mp4, video/quicktime, video/x-flv, video/x-ms-wmv and application/x-shockwave-flash
`minduration`	Always	integer	Minimum video ad duration in seconds.
`maxduration`	Always	integer	Maximum video ad duration in seconds.
`protocols`	Always	integer array	Video bid response protocols. Supported are `2`, `3`, `5` and `6`)
`w`	Always	integer	Width of the player in pixels.
`h`	Always	integer	Height of the player in pixels.
`api`	Optional	integer array	List of supported API frameworks for this impression. See list of api frameworks
`linearity`	Optional	integer	Indicates whether the ad impression must be linear, non-linear, or both (in which case the field is not set).
`startdelay`	Optional	integer	Indicates the start delay in seconds for pre-roll, mid-roll, or post-roll ad placements. 0 = Pre-Roll, -1 = Mid-Roll, -2 = Post-Roll.
`pos`	Optional	integer	The ad position the screen. Values: `0` (unknown), `1` (above the fold), `3` (below the fold).
`minbitrate`	Optional	integer	Minimum bit rate in Kbps.
`maxbitrate`	Optional	integer	Maximum bit rate in Kbps.
`sequence`	Optional	integer	If multiple ad impressions are offered in the same bid request, the sequence number will allow for the coordinated delivery of multiple creatives.
`placement`	Optional	integer	Placement type for the impression. See list of placement types
`plcmt`	Optional	integer	Plcmt type for the impression. See list of plcmt types
`playbackmethod`	Optional	integer array	Allowed playback methods. If none specified, assume all are allowed. See list of playback methods
`delivery`	Optional	integer array	Supported delivery methods. See list of delivery methods

Native Object

Field	Scope	Type	Description
`ver`	Always	string	Version of the NativeAd Specification used. Currently supported is v1.1 or v1.2.
`request`	Always	string or object	Request payload complying with the Native Ad Specification v1.1 or v1.2. It is passed either as JSON-encoded String or JSON depending on your account configuration. See Native Markup Request Object
`ext`	Always	object	Extensions object to pass additional information about the placement.

Native Markup Request Object

Please note that this is send either as JSON or JSON-encoded String dependent on your account configuration. Also, as per OpenRTB Native Ads Specification v1.1 the native ad markup is enclosed in a "native"object such as

{
  "imp": [
    {
      "native": {
        "request": {
          "native": {
            "ver":"1.1",
            "assets":[]
          }
        },
        "ver": "1.1"
      }
    }
  ]
}

Field	Scope	Type	Description
`ver`	Always	string	Version of the Native Ad Spec used. Defaults to `1.1`
`context`	always	integer	The context in which the ad appears. See “Table of Context IDs” of the OpenRTB Native Ads Specification v1.1 for a list of supported context types.
`contextsubtype`	Optional	integer	A more detailed context in which the ad appears. See “Table of Context SubTypes IDs” of the OpenRTB Native Ads Specification v1.1 for a list of supported context subtypes.
`plcmttype`	Always	integer	The design/format/layout of the ad unit being offered. See “Table of Placement Type IDs” of the OpenRTB Native Ads Specification v1.1 for a list of supported placement types.
`assets`	Always	object array	The array of Assets objects as defined in OpenRTB Native Ads Specification v1.1.
`privacy`	Always	integer	Version 1.2 only. Always set to 1: the native ad supports buyer-specific privacy notice.
`eventtrackers`	Optional	object array	Version 1.2 only. The array of Event Trackers Request Objects as defined in OpenRTB Native Ads Specification v1.2.

Asset Object

The asset object will have one of title, img or data.

Field	Scope	Type	Description
`id`	Always	integer	Unique asset ID.
`required`	Always	integer	Flag to indicate whether asset is required. `1` means it is required and the SSP does not accept a bid without it.
`title`	Optional	object	The Title object.
`img`	Optional	object	The Image object.
`data`	Optional	object	The Data object for brand name and description.

Title Object

Field	Scope	Type	Description
`len`	Always	integer	Maximum length of the text in the title element.

Image Object

Field	Scope	Type	Description
`type`	Optional	integer	Type ID of the image element supported by the publisher.
`wmin`	Always	integer	The minimum requested width of the image in pixels.
`hmin`	Always	integer	The minimum requested height of the image in pixels.

Data Object

Field	Scope	Type	Description
`type`	Always	integer	Type ID of the element supported by the publisher. Supported are type `1` (brand) and `2` (text).
`len`	Optional	integer	Maximum length of the text in the element’s response.

Field	Scope	Type	Description
`id`	Always	string	Unique identifier of the website.
`publisher`	Always	object	See Publisher Object.
`domain`	Always	object	Domain of the site, for example, `foo.com`
`page`	Optional	string	URL of the page where the impression will be shown.
`ref`	Optional	string	Referrer URL that caused navigation to the current page.
`ext`	Optional	object	Site Ext object.

Field	Scope	Type	Description
`wuuid`	Always	string	Stroeer internal website ID
`amp`	Always	boolean	Indicates if the site is AMP (Accelerated Mobile Pages) optimised, where `1` = Yes and `0` = No.

Field	Scope	Type	Description
`id`	Always	string	Unique identifier of the website.
`publisher`	Always	object	See Publisher Object.
`domain`	Always	string	Domain of the site, for example, `foo.com`
`bundle`	Optional	string	Application bundle or package name.
`storeurl`	Optional	string	App store URL for an installed app; for IQG 2.1 compliance.
`name`	Optional	string	App name (may be aliased at the publisher’s request).
`ver`	Optional	string	Application version.
`content`	Optional	object	See Content Object.

Content Object

Field	Scope	Type	Description
`url`	Optional	string	URL of the content, for buy-side contextualization or review.
`series`	Optional	string	Content series. Examples: “Star Wars” or “Tatort”
`context`	Optional	integer	Type of content. See context type list
`ext`	Optional	object	Content Ext object.

Content Extension Object

Field	Scope	Type	Description
`network`	Always	string	Content network
`channel`	Always	boolean	Content channel

Device Object

Field	Scope	Type	Description
`ua`	Optional	string	Browser user agent string as per ‘User-Agent’ HTTP header.
`geo`	Optional	object	Location of the device assumed to be the user’s current location defined by a Geo object.
`ip`	Optional	string	IP address of the user.
`language`	Optional	string	Browser language using ISO 639-1 codes (two characters long).
`ifa`	Optional	string	ID sanctioned for advertiser use in the clear
`devicetype`	Optional	integer	The general type of device. Supported: `2` for desktop, `4` for phone, `5` for tablet
`os`	Optional	string	Device operating system (e.g., “iOS”).
`osv`	Optional	string	Device operating system version (e.g., “3.1.2”).
`make`	Optional	string	Device make (e.g., “Apple”).
`model`	Optional	string	Device model (e.g., “iPhone”).
`lmt`	Optional	string	“Limit Ad Tracking” signal commercially endorsed (e.g., iOS, Android), where 0 = tracking is unrestricted, 1 = tracking must be limited per commercial guidelines.
`mccmnc`	Optional	string	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.
`pxratio`	Optional	float	The ratio of physical pixels to device independent pixels.
`h`	Optional	integer	Physical height of the screen in pixels.
`w`	Optional	integer	Physical width of the screen in pixels.
`connectiontype`	Optional	integer	Network connection type. See connection type list.
`didsha1`	Optional	string	Hardware device ID (e.g., IMEI); hashed via SHA1.
`didmd5`	Optional	string	Hardware device ID (e.g., IMEI); hashed via MD5.
`ext`	Optional	object	Device Ext object.

Device Extension Object

Field	Scope	Type	Description
`ifa_type`	Optional	string	IFA type of the device
`atts`	Optional	integer	(iOS only) App Tracking Transparency Status. Represents the app’s tracking authorization status, where 0 = not determined, 1 = restricted, 2 = denied, 3 = authorized.
`ifv`	Optional	string	Limited-scope device identifier. It is the same for apps from the same vendor but different across vendors. For Apple devices, this is the IDFV (Identifier For Vendors).

Geo Object

Field	Scope	Type	Description
`type`	Optional	string	Source of location data (either IP address or GPS).
`country`	Optional	string	Country code using ISO-3166-1-alpha-3.
`lat`	Optional	float	Latitude from -90.0 to +90.0, where negative is south.
`lon`	Optional	gloat	Longitude from -180.0 to +180.0, where negative is west.
`region`	Optional	string	Region code using ISO-3166-2.
`utcoffset`	Optional	integer	Local time as the number +/- of minutes from UTC.
`city`	Optional	string	City using United Nations Code for Trade & Transport Locations.
`lastfix`	Optional	integer	Number of seconds since this geolocation fix was established.
`accuracy`	Optional	integer	Estimated location accuracy in meters.
`metro`	Optional	string	Google metro code; similar to but not exactly Nielsen DMAs.
`zip`	Optional	string	Zip or postal code.

Publisher Object

Field	Scope	Type	Description
`id`	Always	string	Unique identifier of the publisher.

Regulations Object

Field	Scope	Type	Description
`ext`	Optional	object	Regulations Ext object to provide the Digital Services Act (DSA) transparency information

Regulations Ext Object

Field	Scope	Type	Description
`dsa`	Optional	object	Digital Services Act DSA transparency information.

DSA Transparency Object

Full support for the all fields defined by the OpenRTB DSA Transparency ext specification.

User Object

Field	Scope	Type	Description
`id`	Always	string	Ströer SSP’s unique user ID.
`buyeruid`	Optional	string	Buyer’s user ID (as established via User Matching API).
`customdata`	Optional	string	Optional user related data from publisher
`ext`	Optional	object	User Ext object for TCF consent and external user ID information.

User Ext Object

Field	Scope	Type	Description
`id`	Always	string	Ströer SSP’s unique user ID.
`consent`	Optional	string	Passes the Transparency & Consent Framework string. The current valid version of this string is v2.0.
`eids`	Optional	object array	Contains the Extended Identifiers object, see the Extended Identifiers section for details
`us_privacy`	Optional	string	US privacy data

Extended Identifiers

For passing multiple third party user identifiers. See official eids.md for details.

Field	Scope	Type	Description
`source`	Always	string	Source or technology provider responsible for the set of included IDs. Expressed as a top-level domain.
`uids`	Always	object array	Passes the Extended Identifier UIDs matched from the given provider (`source`).

Extended Identifier UIDs

Field	Scope	Type	Description
`id`	Always	string	The User ID with this provider.

Stroeer supports the following external user ID provider:

Criteo as criteo.com
ID5 as id5-sync.com
PubCommon as pubcid.org
SharedID as sharedid.org
netId as netid.de
UniversalUserId as uid.stroeer.com

Please check with your account manager to enable passing external user IDs in the bid request.

Example for ID5:

"user": {
  "id": "ef824e53893631ac2d413682587bd2853cfa93775185d9abfdb8df3f6c5adc58",
  "buyeruid": "8911957921327140313",
  "ext": {
     "consent": "CPJTW5sP....",
     "eids": [
        {
           "source": "id5-sync.com",
           "uids": [
              {
                 "id": "ID5-ZHMOYgRz87P6h5Vb_vFZKpy-uHNcMOchpZOGLAGtTg"
              }
           ]
        }
     ]
  }
}

PMP Object

Field	Scope	Type	Description
`private_auction`	Always	integer	An integer flag indicating that the impression is a private auction eligible only to deals in the Direct Deal object. `1` = bids for this impression are restricted to the deals specified and the terms thereof; `0` = all bids are accepted.
`deals`	Always	object array	A collection of Deal objects encapsulating a list of direct deals eligible for this impression. See Direct Deals object.

Direct Deals Object

Field	Scope	Type	Description
`id`	Always	string	A unique identifier for the direct deal.
`bidfloor`	Always	float	Bid floor for this impression (in CPM of `bidfloorcur`).
`bidfloorcur`	Always	string	Supported currencies are `EUR` and `USD`.
`at`	Always	integer	Auction type: `2` = second price auction, `3` = apriori agreed upon deal price.
`wseat`	Always	string array	Array of buyer seats allowed to bid on this Direct Deal.

Note: Deal bids are send in the currency of your partner configuration at Ströer SSP.

Event Tracker Request Object

Field	Scope	Type	Description
`event`	Always	integer	Type of event for tracking. Only supports Type ID `1` (impression)
`methods`	Always	integer	Array of types of tracking available for given event. Only supports types `1` (img) and `2` (js)

Enumerated Lists

API Frameworks

Value	Description
1	VPAID 1.0
2	VPAID 2.0
3	MRAID-1
4	ORMMA
5	MRAID-2
6	MRAID-3
7	OMID-1

Connection types

Value	Description
0	Unknown
1	Ethernet
2	WIFI
3	Cellular Network – Unknown Generation
4	Cellular Network – 2G
5	Cellular Network – 3G
6	Cellular Network – 4G

Context types

Value	Description
1	Video
2	Game
3	Music
4	Application
5	Text
6	Other
7	Unknown

Delivery methods

Value	Description
1	Streaming
2	Progressive
3	Download

Video placement types

Value	Description
1	In-Stream Played before, during or after the streaming video content that the consumer has requested (e.g., Pre-roll, Mid-roll, Post-roll).
2	In-Banner Exists within a web banner that leverages the banner space to deliver a video experience as opposed to another static or rich media format. The format relies on the existence of display ad inventory on the page for its delivery.
3	In-Article Loads and plays dynamically between paragraphs of editorial content; existing as a standalone branded message.
4	In-Feed - Found in content, social, or product feeds.
5	Interstitial/Slider/Floating Covers the entire or a portion of screen area, but is always on screen while displayed (i.e. cannot be scrolled out of view). Note that a full-screen interstitial (e.g., in mobile) can be distinguished from a floating/slider unit by the imp.instl field.

Video plcmt types

Value	Description
1	Instream: Pre-roll, mid-roll, and post-roll ads that are played before, during or after the streaming video content that the consumer has requested. Instream video must be set to “sound on” by default at player start, or have explicitly clear user intent to watch the video content. While there may be other content surrounding the player, the video content must be the focus of the user’s visit. It should remain the primary content on the page and the only video player in-view capable of audio when playing. If the player converts to floating/sticky subsequent ad calls should accurately convey the updated player size.
2	Accompanying Content: Pre-roll, mid-roll, and post-roll ads that are played before, during, or after streaming video content. The video player loads and plays before, between, or after paragraphs of text or graphical content, and starts playing only when it enters the viewport. Accompanying content should only start playback upon entering the viewport. It may convert to a floating/sticky player as it scrolls off the page.
3	Interstitial: Video ads that are played without video content. During playback, it must be the primary focus of the page and take up the majority of the viewport and cannot be scrolled out of view. This can be in placements like in-app video or slideshows.
4	No Content/Standalone: Video ads that are played without streaming video content. This can be in placements like slideshows, native feeds, in-content or sticky/floating.

Video playback methods

Value	Description
1	Initiates on Page Load with Sound On
2	Initiates on Page Load with Sound Off by Default
3	Initiates on Click with Sound On
4	Initiates on Mouse-Over with Sound On
5	Initiates on Entering Viewport with Sound On
6	Initiates on Entering Viewport with Sound Off by Default

Bid Request Examples

Display, Private Market Place

{
    "id": "997d03370c424c2aa958c7c28e845c5a",
    "source": {
        "ext": {
            "schain": {
                "complete": 0,
                "nodes": [
                    {
                        "asi": "stroeer.com",
                        "sid": "17445",
                        "rid": "997d03370c424c2aa958c7c28e845c5a",
                        "hp": 1
                    }
                ]
            }
        }
    },
    "imp": [
        {
            "id": "1",
            "banner": {
                "format": {
                  "w": 468,
                  "h": 60
                },
                "pos": 1,
                "topframe": 1
            },
            "instl": 1,
            "pmp": {
                "private_auction": 1,
                "deals": [
                    {
                        "id": "ABLAgency1L0001",
                        "bidfloor": 3.50,
                        "bidfloorcur": "EUR",
                        "at": 2,
                        "wseat": [
                            "seat_id_1"
                        ]
                    },
                    {
                        "id": "ABLAgency1L0002",
                        "bidfloor": 4.50,
                        "bidfloorcur": "EUR",
                        "at": 3,
                        "wseat": [
                            "seat_id_2"
                        ]
                    }
                ]
            },
            "tagid": "39005"
        }
    ],
    "site": {
        "id": "51005",
        "ref": "http://www.example.com/foo?",
        "page": "http://referrer.com/search?",
        "publisher": {
            "id": "17445"
        }
    },
    "device": {
        "ip": "123.123.123.123",
        "ua": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/0.2.153.1 Safari/525.19",
        "language": "en"
    },
    "user": {
        "id": "400101417655403416",
        "buyeruid": "639612c0-6e0c-11e4-a149-0002a5d5c51b"
    },
    "tmax": 98
}

Video, Mid-Roll, Private Market Place

{
    "id":"30668144364741648101T099",
    "imp":[
        {
            "id": "1",
            "video": {
                "mimes": [
                    "video/x-flv",
                    "video/quicktime",
                    "video/mp4",
                    "video/x-ms-wmv",
                    "application/x-shockwave-flash"
                ],
                "startdelay": -1,
                "linearity": 1,
                "minduration": 0,
                "maxduration": 2147483647,
                "protocols": [
                    2,
                    5,
                    3,
                    6
                ],
                "api": [
                    1,
                    2
                ],
                "w": 1280,
                "h": 720
            },
            "pmp": {
                "private_auction": 1,
                "deals": [
                    {
                        "id": "ABLAgency1L0001",
                        "bidfloor": 3.50,
                        "bidfloorcur": "EUR",
                        "at": 2,
                        "wseat": [
                            "seat_id_3"
                        ]
                    },
                    {
                        "id": "ABLAgency1L0002",
                        "bidfloor": 4.50,
                        "bidfloorcur": "EUR",
                        "at": 3,
                        "wseat": [
                            "seat_id_4"
                        ]
                    }
                ]
            },
            "tagid": "75729",
            "secure": 0
        }
    ],
    "site":{
        "id": "21255",
        "domain": "filmotopia.com",
        "page": "http://filmotopia.com/online-filmovi-sa-prevodom/ghost-rider-spirit-vengeance/",
        "publisher": {
            "id": "11598"
        }
    },
    "device": {
        "ip": "88.153.6.27",
        "language": "sr",
        "ua": "Mozilla/5.0 (Windows NT 6.3; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/45.0.2454.101 Safari/537.36"
    },
    "user": {
        "id": "421931431157813513"
    },
    "tmax": 198
}

{
    "id": "12345678912345678911T32",
    "imp": [
        {
            "id": "1",
            "banner": {
                "format": {
                  "w": 468,
                  "h": 60
                },
                "pos": 1,
                "topframe": 1
            },
            "instl": 1,
            "tagid": "39005"
        }
    ],
    "app": {
        "id": "51005",
        "domain": "example.stroeer.de",
        "bundle": "de.stroeer.example",
        "publisher": {
            "id": "3011"
        },
        "content": {
            "url": "https://example.stroeer.de/app-name/info.html"
        }
    },
    "device": {
        "ip": "123.123.123.123",
        "ua": "Mozilla/5.0 (Windows; U; Windows NT 5.1; en-US) AppleWebKit/525.19 (KHTML, like Gecko) Chrome/0.2.153.1 Safari/525.19",
        "language": "en",
        "ifa": "e4fe9bde-caa0-47b6-908d-ffba3fa184f2"
    },
    "user": {
        "id": "400101417655403416"
    },
    "tmax": 98
}

Native Bid Example

{
  "id": "unique-request-id",
  "imp": [
    {
      "id": "1",
      "tagid": "1234",
      "secure": 1,
      "native": {
        "ver": "1.1",
        "request": {
            "native": {
              "context": 2,
              "contextsubtype": 20,
              "plcmttype": 11,
              "privacy": 1,
              "assets": [
                {
                  "id": 123,
                  "required": 1,
                  "title": {
                    "len": 50
                  }
                },
                {
                  "id": 128,
                  "required": 0,
                  "img": {
                    "wmin": 836,
                    "hmin": 627,
                    "type": 3
                  }
                },
                {
                  "id": 126,
                  "required": 1,
                  "data": {
                    "type": 1,
                    "len": 130
                  }
                },
                {
                  "id": 127,
                  "required": 1,
                  "data": {
                    "type": 2,
                    "len": 250
                  }
                }
              ]
            }
         }
      },
      "ext": {
        "iframe": true,
        "position": 1
      }
    }
  ],
  "device": {
    "ua": "Apache-HttpClient/4.4.1 (Java/1.8.0_131)",
    "ip": "127.0.0.1",
    "language": "English"
  },
  "site": {
    "page": "http://publisher.com/news",
    "ref": "http://google.com/search?params=included"
  },
  "user": {
    "id": "my-user-id",
    "buyeruid": "my-user-id"
  },
  "tmax": 100
}

Popunder Adverts

Bid requests for popunder adverts have the following characteristics in the bid request:

BidRequest.Impression.Banner.format array is replaced with
- BidRequest.Impression.Banner.wmax
- BidRequest.Impression.Banner.hmax
- BidRequest.Impression.Banner.wmin
- BidRequest.Impression.Banner.hmin
- whereby the maximum values are 1024 x 800 and the minimum values are 250 x 250.
BidRequest.Impression.Banner.ext.popunder is added with a value of 1.
BidRequest.Impression.Banner.topframe is set to 1 as popunder adverts are on the page in the popunder window.

Example of a popunder advert BidRequest.Impression.Banner object:

"banner": {
    "wmax": 1024,
    "hmax": 800,
    "wmin": 250,
    "hmin": 250,
    "topframe": 1,
    "ext": {
        "popunder": 1
    }
}

Bid requests for mobile interstitial adverts have the following characteristics in the bid request:

BidRequest.Impression.instl is added with a value of 1.
BidRequest.Impression.Banner.foramt array is replaced with
- BidRequest.Impression.Banner.wmax
- BidRequest.Impression.Banner.hmax
- BidRequest.Impression.Banner.wmin
- BidRequest.Impression.Banner.hmin
- whereby the maximum values are 320 x 480 and the minimum values are 160 x 240.
BidRequest.Impression.Banner.topframe is set to 1 as mobile interstitial adverts are on the page.

An example of a mobile interstitial advert BidRequest object:

{
    ...
    "imp": [
        {
            ...
            "id": "1",
            "banner": {
                "wmax": 320,
                "hmax": 480,
                "wmin": 160,
                "hmin": 240,
                "topframe": 1,
            },
            "instl": 1,
            ...
        }
    ],
    ...
}

Floor Adverts

Bid requests for floor adverts have the following characteristics in the bid request:

BidRequest.Impression.instl is added with a value of 1.
BidRequest.Impression.Banner.topframe is set to 0 as floor adverts are rendered in an iframe.
BidRequest.Impression.Banner.expdir is set to [3] as floor adverts expand upwards.
BidRequest.Impression.Banner.format[].w is set to the slots width.
BidRequest.Impression.Banner.format[].h is set to the slots height.
BidRequest.Impression.Banner.format[].ext.sticky is set to 1.

Floor adverts come in 3 sizes. 728x200, 800x200 and 1200x200.

An example of a floor advert BidRequest object:

{
    ...
    "imp": [
        {
            ...
            "id": "1",
            "banner": {
            "format": {
                  "w": 800,
                  "h": 200,
                  "ext": { "sticky": 1 }
                },
                "topframe": 0,
                "expdir": [3]
            },
            "instl": 1,
            ...
        }
    ],
    ...
}

Interstitial Adverts

Bid requests for interstitial adverts have the following characteristics in the bid request:

BidRequest.Impression.instl is added with a value of 1.
BidRequest.Impression.Banner.topframe is set to 0 as interstitial adverts are rendered in an iframe.
BidRequest.Impression.Banner.format[].w is set to the slots width.
BidRequest.Impression.Banner.format[].h is set to the slots height.
BidRequest.Impression.Banner.ext.lightbox is set to 1.

Interstitial adverts come in 4 sizes. 400x400, 800x600, 1024x768 and 1280x1024.

An example of an interstitial advert BidRequest object:

{
    ...
    "imp": [
        {
            ...
            "id": "1",
            "banner": {
                "format": {
                    "w": 800,
                    "h": 600
                },
                "topframe": 0,
                "ext": { "lightbox": 1 }
            },
            "instl": 1,
            ...
        }
    ],
    ...
}

Layer Adverts

Bid requests for Layer adverts have the following characteristics in the bid request:

BidRequest.Impression.instl is added with a value of 1.
BidRequest.Impression.Banner.topframe is set to 0 as layer adverts are rendered in an iframe.
BidRequest.Impression.Banner.format[].w is set to the slots width.
BidRequest.Impression.Banner.format[].h is set to the slots height.

Layer adverts come in 4 sizes. 400x400, 800x600, 1024x768 and 1280x1024.

An example of an layer advert BidRequest object:

{
    ...
    "imp": [
        {
            ...
            "id": "1",
            "banner": {
                "format": {
                    "w": 800,
                    "h": 600
                },
                "topframe": 0
            },
            "instl": 1,
            ...
        }
    ],
    ...
}

Bid requests for sticky adverts have the following characteristics in the bid request:

BidRequest.Impression.Banner.topframe is set to 0 as floor adverts are rendered in an iframe.
BidRequest.Impression.Banner.format[].w is set to the slots width.
BidRequest.Impression.Banner.format[].h is set to the slots height.
BidRequest.Impression.Banner.format[].ext.sticky is set to 1.

Sticky adverts come in 4 sizes. 120x600, 160x600, 200x600, 300x600.

An example of a sticky advert BidRequest object:

{
    ...
    "imp": [
        {
            ...
            "id": "1",
            "banner": {
                "format": {
                  "w": 300,
                  "h": 600,
                  "ext": { "sticky": 1 }
                },
                "topframe": 0
            },
            ...
        }
    ],
    ...
}

Dynamic Sitebar Adverts

Bid requests for dynamic sitebar adverts have the following characteristics in the bid request:

BidRequest.Impression.Banner.topframe is set to 0 as floor adverts are rendered in an iframe.
BidRequest.Impression.Banner.format[].w is set to the slots width (301).
BidRequest.Impression.Banner.format[].h is set to the slots height (301).
BidRequest.Impression.Banner.format[].ext.sticky is set to 1.
BidRequest.Impression.Banner.format[].ext.scaling is set to 1.

Dynamic Sitebar adverts have dimension set to 301x601 (although their true dimension will be scaled to fill the available content).

An example of a dynamic sitebar advert BidRequest object:

{
    ...
    "imp": [
        {
            ...
            "id": "1",
            "banner": {
                "format": {
                  "w": 301,
                  "h": 601,
                  "ext": {
                    "sticky": 1,
                    "scaling": 1
              }
                },
                "topframe": 0
            },
            ...
        }
    ],
    ...
}

Video Ad Formats

The “nature” of a video placement is indicated by a combination of fields (startdelay, linearity) and their values:

Video Ad Format	`startdelay`	`linearity`
Pre-Roll	0	1
Mid-Roll	-1	1
Post-Roll	-2	1
Outstream	not send	1

Bid Response

Listing of objects and fields related to the bid response supported by Ströer SSP.

Bid Response Object

Field	Scope	Type	Description
`id`	Always	string	ID of the bid request.
`seatbid`	Always	object array	Array of Seat Bid Objects.

Seat Bid Object

Field	Scope	Type	Description
`bid`	Always	object array	Array of Bid Objects.
`seat`	Optional	string	ID of the bidder seat on whose behalf this bid is made. Required when bidding in the private market place.

Bid Object

Field	Scope	Type	Description
`id`	Always	string	Buyer’s unique identifier for the bid request. If present will be used in the win/loss notification.
`impid`	Always	string	ID of the impression object to which this bid applies.
`price`	Always	float	Bid price in CPM.
`nurl`	Optional	string	Win notice URL called by the exchange if the bid wins (not indicative of a delivered, viewed, or billable ad). Supported macros are: `${AUCTION_PRICE}`, `${AUCTION_PRICE:ENC}`. See Note below the table.¹⁾
`lurl`	Optional	string	Loss notice URL called by the exchange when a bid is known to have been lost. Supported macros are: `${AUCTION_PRICE}`, `${AUCTION_PRICE:ENC}` and `${AUCTION_LOSS}`. See ²⁾ for loss reason codes for the `${AUCTION_LOSS}` macro replacement.
`adm`	Always	string	Actual ad markup. For responses to video objects it needs to be VAST XML.
`adomain`	Always	string array	Array of landing page URLs.
`crid`	Always	string	Buyer’s creative ID. If present will be used in the win/loss notification.
`dealid`	Optional	string	A unique identifier for the direct deal associated with the bid. If the bid is associated and in response to a `dealid` in the request object it si required in the response object.
`w`	Always	integer	The height of the creative in pixels.
`h`	Always	integer	The height of the creative in pixels.
`ext`	Always	object	See Bid Extension Object.

¹⁾ The handling of the nurl in the bid response is implemented for video bids only. The nurl is used in preference to the adm:

`nurl`	`adm`	Behaviour
present	absent	Auction price macros are replaced and a VAST wrapper is created using the given win notification URL as the `VASTAdTagURI`. The DSP has to make sure that the final VAST for the player is return upon unwrapping.
present	present	Auction price macros are replaced and a VAST wrapper is created using the given win notification URL as the `VASTAdTagURI`. The DSP has to make sure that the final VAST for the player is return upon unwrapping. The VAST in the `adm` is basically ignored.
absent	present	Auction price macros are replaced in the VAST and delivered to the video player.

²⁾ Loss reason codes:

`value`	`description`
`1`	Other
`2`	Impression Opportunity Expired
`3`	Invalid Bid Response
`4`	Invalid Deal ID
`100`	Bid was Below Auction Floor
`101`	Bid was Below Deal Floor
`102`	Lost to Higher Bid
`103`	Lost to a Bid for a PMP Deal
`201`	Creative Filtered - Pending processing by Exchange (e.g., approval, transcoding, etc.)
`202`	Creative Filtered - Disapproved by Exchange
`203`	Creative Filtered - Size Not Allowed
`205`	Creative Filtered - Advertiser Exclusions
`207`	Creative Filtered - Not Secure
`1001`	The creative is waiting for publisher approval
`1002`	The creative was declined by publisher approval
`1003`	The bid did not win
`1101`	The agency in the bid response is blacklisted by the publisher
`1102`	For native bids an asset did not match the required asset definition of the bid request
`1104`	The bid response did not match the brands associated with the direct deal
`1105`	The bid response did not match the ad formats associated with the direct deal
`1106`	The bid response did not contain all mandatory fields (`agn`, `avn`, `crid`, `adomain`)
`1107`	The bid response did not match the seat id associated with the direct deal
`1108`	The playrate (rendered creative events divided by delivery attempts) of the creative was zero ³⁾.

³⁾ Play rate is defined as the ration between delivery attempts and rendered creative events and is taken into consideration in the bidding process.

Bid Extension Object*

Field	Scope	Type	Description
`avn`	Always	string	The name of the advertiser.
`agn`	Always	string	The name of the agency.
`dsa`	Optional	object	Digital Services Act transparency information

*If seatand adomain parameters are provided in each bid response, the bid extension object can be omitted. In this case a seat IDs table should be made available to Ströer SSP and regularly updated.

DSA Transparency Object

Full support for the all fields defined by the OpenRTB DSA Transparency ext specification.

Substitution Macros

Ströer SSP supports the following substitution macros in the Bid Object.adm field: ${AUCTION_PRICE} and ${AUCTION_PRICE:ENC}.

The price macros are subsituted with the value ADSCALE_AUDIT when the adtag is reviewed by our Team or Ad Verification Service and can be ignored.

For a detailed description of the encrypted auction price substitution macro see section Auction Price Encryption below.

Note:

Decimal places are separated with a period, “.”
The price is given as CPM and not as absolute costs.
The price may be the value ADSCALE_AUDIT during adtag reviews and is not a bid

Native Markup Response Object

The Native Ad Markup is returned in the adm field as either a JSON or JSON-encoded String.

Note, the Native ad markup has a native element as per Native Ad Specification.

The SSP validates the returned assets against the required assets of the bid request. If validation fails an error notification is send (if opted in for notifications) with the error reason of “assetInconsistency” (see Win, Loss and Error Notifications).

{
  "id": "123",
  "seatbid": [
    {
      "bid": [
        {
          "impid": "1",
          "adm": {
            "native": {
              "ver":"1.0",
              "link":{...},
              "assets":[ ... ]
            }
          }
        }
      ]
    }
  ]
}

Field	Scope	Type	Description
`ver`	Optional	string	Version of the Native Markup version in use. Defaults to “1.1”
`link`	Always	object	Destination link. See Link object.
`assets`	Always	object array	List of native ad’s assets. See Asset object.
`imptrackers`	Optional	string array	Array of impression tracking URLs, expected to return a 1x1 image or 204 response.
`jstracker`	Optional	string	Optional JavaScript impression tracker.
`eventtracker`	Optional	object array	Version 1.2 Optional event trackers. See Event Trackers object
`privacy`	Optional	integer	Version 1.2 only. If support was indicated in the request, URL of a page informing the user about the buyer’s targeting activity.

Link Object

Field	Scope	Type	Description
`url`	Always	string	Landing URL of the clickable link.
`clicktrackers`	Optional	string array	List of third-party tracker URLs to be fired on click of the URL.

Asset Object

The asset object must contain one of title, img or data.

Field	Scope	Type	Description
`id`	Always	integer	Unique asset ID, assigned by exchange, must match one of the asset IDs in request.
`required`	Optional	integer	Set to 1 if asset is required.
`title`	Optional	object	The Title object for title assets.
`img`	Optional	object	The Image object for image assets.
`data`	Optional	object	The Data object for brand and text assets.

Title Object

Field	Scope	Type	Description
`text`	Always	string	The text associated with the text element.

Image Object

Field	Scope	Type	Description
`url`	Always	string	URL of the image asset.
`w`	Optional	integer	Width of the image in pixels.
`h`	Optional	integer	Height of the image in pixels.

Data Object

Field	Scope	Type	Description
`value`	Always	string	The formatted string of data to be displayed.
`label`	Optional	string	The optional formatted string name of the data type todisplayed.

Bid Response Examples

Open Auction Response

{
    "id": "12345678912345678911W32",
    "seatbid": [
      {
        "bid": [
          {
            "id": "345324-23432",
            "impid": "1",
            "price": 0.2,
            "adm": "<script>tag</script>",
            "crid": "342523a454",
            "adomain": [
              "http://landing.page.com"
            ],
            "ext": {
              "avn": "advertiser name",
              "agn": "agency name"
            }
          }
        ]
      }
    ]
  }

Deal Response

Example bid response for a bid on a deal (note, that both seat and dealid have to be included in the bid and match the deal setup to be considered in the auction):

{
    "id": "12345678912345678911W32",
    "seatbid": [
      {
        "seat": "512",
        "bid": [
          {
            "id": "345324-23432",
            "impid": "1",
            "price": 0.2,
            "adm": "<script>tag</script>",
            "crid": "342523a454",
            "dealid": "ABLAgency1L0001",
            "adomain": [
              "http://landing.page.com"
            ],
            "ext": {
              "avn": "advertiser name",
              "agn": "agency name"
            }
          }
        ]
      }
    ]
  }

Native Ad Response

{
  "id": "123",
  "seatbid": [
    {
      "bid": [
        {
          "id": "12345",
          "impid": "1",
          "price": 3.50,
          "nurl": "http://example.com/winnoticeurl",
          "adm": {
            "native": {
              "link": {
                "url": "http: //i.am.a/URL"
              },
              "imptrackers": [
                "http://buyer.com/track?p=${AUCTION_PRICE:ENC}"
              ],
              "assets": [
                {
                  "id": 123,
                  "title": {
                    "text": "Watch this awesome thing"
                  }
                },
                {
                  "id": 128,
                  "img": {
                    "url": "http://www.myads.com/largethumb1.png"
                  }
                },
                {
                  "id": 126,
                  "data": {
                    "value": "My Brand"
                  }
                },
                {
                  "id": 127,
                  "data": {
                    "value": "Some awesome description here"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Native Ad Response Version 1.2

{
  "id": "123",
  "seatbid": [
    {
      "bid": [
        {
          "id": "12345",
          "impid": "1",
          "price": 3.50,
          "nurl": "http://example.com/winnoticeurl",
          "adm": {
            "native": {
              "link": {
                "url": "http: //i.am.a/URL"
              },
              "eventtrackers": [{
                "event": 1,
                "method": 1,
                "url": "http://buyer.com/track?p=${AUCTION_PRICE:ENC}"
              }],
              "assets": [
                {
                  "id": 123,
                  "title": {
                    "text": "Watch this awesome thing"
                  }
                },
                {
                  "id": 128,
                  "img": {
                    "url": "http://www.myads.com/largethumb1.png"
                  }
                },
                {
                  "id": 126,
                  "data": {
                    "value": "My Brand"
                  }
                },
                {
                  "id": 127,
                  "data": {
                    "value": "Some awesome description here"
                  }
                }
              ]
            }
          }
        }
      ]
    }
  ]
}

Popunder Adverts

The bid response for a popunder advert should additionally include the following fields:

BidResponse.Seat.Bid.h and
BidResponse.Seat.Bid.w

A bid response having the values of the width and height not within the specified maximum and minimum values of the bid request will not be considered in the bidding process and an error notification with an error reason of invalidResponse is returned.

The bid response for a mobile interstitial advert should additionally include the following fields:

BidResponse.Seat.Bid.w
BidResponse.Seat.Bid.h

Floor Adverts

The bid response for a floor advert should additionally include the following fields:

BidResponse.Seat.Bid.w
BidResponse.Seat.Bid.h

A bid response having the values of the width and height not equal to the width and height of the bid request will not be considered in the bidding process and an error notification with an error reason of invalidResponse is returned.

The bid response for a sticky advert should additionally include the following fields:

BidResponse.Seat.Bid.w
BidResponse.Seat.Bid.h

Dynamic Sitebar Adverts

The bid response for a dynamic sitebar advert should additionally include the following fields:

BidResponse.Seat.Bid.w
BidResponse.Seat.Bid.h

Interstital Adverts

The bid response for an interstitial advert should additionally include the following fields:

BidResponse.Seat.Bid.w
BidResponse.Seat.Bid.h

Layer Adverts

The bid response for an layer advert should additionally include the following fields:

BidResponse.Seat.Bid.w
BidResponse.Seat.Bid.h

Win, Loss and Error Notifications (Legacy)

Please note that the following describes the legacy and proprietary notification implementation before the introduction of Bid.lurl in OpenRTB v2.5. Partners migrating to v2.5 should use bid.lurl and bid.nurl as this takes precedence over the proprietary notification API which is still available for backwards compatibility.

The JSON-based Notification API provides the buyer with feedback on the bid outcome. Notifications are send in batches of up to 100 notifications per request (HTTP POST). The batch size is part of the partner configuration.

Notifications are intended as a real-time reporting system for debugging purposes. For real time win notification the auction price substitution macros, ${AUCTION_PRICE} or ${AUCTION_PRICE:ENC}, should be used (see section Substitution Macros under Bid Response).

A no-bid response should have an empty body with the status code 204 (or 200).

A notification request is not resend on timeout, no response and a status code other then 200 or 204.

Note:

A minimum bid of 0.001 is required to participate in the auction for an impression.
No notification will be sent out for zero/no bids.
In case of a malformed bid response or timeouts an error notification will be sent.

There are three types of notification calls: win, loss and error. Each notification type can be enabled individually for each DSP partner.

Field	Scope	Type	Description
`id`	Always	string	Unique ID of the bid request provided by the exchange.
`impid`	Always	string	A unique identifier for this impression within the context of the bid request (typically, value starts with 1, and increments up to n for n impressions.
`userid`	Always	string	Unique consumer ID of this user on the exchange.
`buyeruid`	Always	string	Buyer’s user ID for this user as mapped by exchange for the buyer.
`bidid`	Always	string	ID for the bid object chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.
`dealid`	If provided	string	A unique identifier for the direct deal if the bid was on a deal.
`seat`	If provided	string	ID of the bidder seat on whose behalf this bid is made.
`crid`	If provided	string	Creative ID for reporting content issues or defects.
`win`	Always	boolean	`true/false`
`p`	If win/loss	number	The price as a CPM the bidder paid for the impression. Not available for error notifications.
`r`	If loss	string	Reason for the loss or error notification. See table above.
`t`	Always	number	The response time of the bid response.

Note: Additional parameters can be added at any time and without prior notification.

The parameter r contains one of the following reasons for the loss or error notification:

Reason	Description
`agencyBlocked`	The agency in the bid response is blacklisted by the publisher
`assetInconsistency`	For native bids an asset did not match the required asset definition of the bid request.
`brandBlocked`	The brand in the bid response is blacklisted by the publisher
`brandInconsistency`	The bid response did not match the brands associated with the direct deal
`cpm`	The bid did not win.
`dealidInconsistency`	The bid response did not match the deal id associated with the direct deal
`declined`	The creative has been declined by approval.
`floorInconsistency`	The bid response price was null or below the floor of the direct deal
`formatBlocked`	The ad format in the bid response is blacklisted by the publisher
`formatInconsistency`	The bid response did not match the ad formats associated with the direct deal
`incompleteResponse`	The bid response did not contain all mandatory fields. (`agn`, `avn`, `crid`, `adomain`)
`insecureCreative`	If insecure content in the creative asset/markup is detected for a secure bid request, ie., `impression.secure: 1`.
`invalidResponse`	Bid response HTTP status code other than 200 or invalid JSON.
`other`	Any other error during bid response handling than above.
`pending`	The creative has not gone through approval yet.
`privateSale`	The impression was sold in a private sale.
`publisherPending`	The creative is waiting for publisher approval.
`publisherRejected`	The creative was declined by publisher approval.
`seatInconsistency`	The bid response did not match the seat id associated with the direct deal
`zeroPlayRate`	The playrate (rendered creative events divided by delivery attempts) of the creative was zero ¹⁾.
`timeout`	The bid response did not arrive within the provided timeout period.
`missingCompanionBid`	A multi-impression bid response was missing required bids for at least one impression
`mediaFileUrlChangedBlocked`	The provided media file in the vast response has been changed since the first submission
`floor`	The bid response price was below the bid floor

¹⁾ Play rate is defined as the ration between delivery attempts and rendered creative events and is taken into consideration in the bidding process.

Example of a JSON notifications message:

{
    "notifications": [
        {
            "id": "12345678912345678911T32",
            "impid": "1",
            "userid": "400101417655403416",
            "buyeruid": "639612c0-6e0c-11e4-a149-0002a5d5c51b",
            "bidid": "345324-23432",
            "dealid": "ABLAgency1L0001",
            "seat": "512",
            "crid": "342523a454",
            "win": false,
            "p": 1.23,
            "r": "cpm",
            "t": 26
        },
        {
            "id": "12345678912345678911T32",
            "impid": "2",
            "userid": "400101417655403412",
            "buyeruid": "639612c0-6e0c-11e4-a149-0002a5dXXXX",
            "bidid": "345324-234XX",
            "dealid": "ABLAgency1L0002",
            "seat": "513",
            "crid": "342523a4XX",
            "win": true,
            "p": 1.50,
            "t": 43
        }]
}

Auction Price Encryption

This section describes the encryption used for the ${AUCTION_PRICE:ENC} substitution macro.

Both encryption and decryption use two secret keys, the pad key and the signature key. Please ask your account manager for these keys.

Requirements

Crypto library supporting SHA-1 HMAC
Decoder for base64-encoded, web-safe, unpadded strings (see RFC 3548, page 6)

Notation

The pseudocode in this document uses the following notation:

Pseudocode	Description
`s{n}`	The first `n` bytes of string `s`.
`s{n:c}`	String `s` padded to the length of `n` bytes by adding `c`s to its end.
`a` \| \| `b`	String `a` concatenated with string `b`.
`hmac(d, k)`	The SHA-1 HMAC of data `d` using key `k` as raw byte stream.

Examples

s = "abcdef"
s{3} // equals "abc"

s = "1.321"
s{8:0} // equals "1.321000"

a = "foo"
b = "bar"
a || b // equals "foobar"

d = "foo"
k = "bar"
hmac(d, k) // equals "85d155c55ed286a300bd1cf124de08d87e914f3a" (hex notation*)

Hex notation here is just used for visibility, hmac(d, k) returns a raw byte stream.

Encryption

The price is encrypted using a key-hashed version of the impression ID.

The complete message you receive consists of the impression ID, the encrypted price and a signature for validating the decryption. The message is passed as a base64-encoded, web-safe, unpadded string (see RFC 3548, page 6).

The message is always 28 bytes long and has the following format:

<impressionId (16 bytes)><encryptedPrice (8 bytes)><signature (4 bytes)>

Therefore the base64-encoded, web-safe, unpadded string is always 38 bytes long.

Input

Parameter	Description	Example
`padKey`	Secret key used for the pad (ask your account manager).	`we-will-use-this-key-for-the-pad`
`signatureKey`	Secret key used for the signature (ask your account manager).	`for-the-signature-we-use-another`
`impressionId`	Impression ID.	`1234567890123456`
`price`	Price.	`1.321`

Pseudocode

impressionId = impressionId{16} // only the first 16 bytes
price = price{8:0} // pad price to 8 bytes

pad = hmac(impressionId, padKey)
pad = pad{8} // only the first 8 bytes

encryptedPrice = pad xor price

signature = hmac(price || impressionId, signatureKey)
signature = signature{4} // only the first 4 bytes

message = impressionId || encryptedPrice || signature

encodedMessage = encodeBase64WebsafeUnpadded(message)

Decryption

The decryption uses the same two secret keys, the pad key and the signature key. Please ask your account manager for these keys.

Since the impression ID used for encryption is also part of the message, you should calculate a check-signature and compare it against the signature of the message to validate the correct decryption.

Input

Parameter	Description	Example
`padKey`	Secret key used for the pad (ask your account manager).	`we-will-use-this-key-for-the-pad`
`signatureKey`	Secret key used for the signature (ask your account manager).	`for-the-signature-we-use-another`
`encodedMessage`	The message as a base64-encoded, web-safe, unpadded string.	`MTIzNDU2Nzg5MDEyMzQ1NvKEVxJuVzSmV-T3Fg`

Pseudocode

message = decodeBase64WebsafeUnpadded(encodedMessage)
(impressionId, encryptedPrice, signature) = message // split (16, 8, 4) bytes

pad = hmac(impressionId, padKey)
pad = pad{8} // only the first 8 bytes

price = encryptedPrice xor pad

checkSignature = hmac(price || impressionId, signatureKey)
checkSignature = checkSignature{4} // only the first 4 bytes

valid = (checkSignature == signature)

Test Data

This table contains data for testing purposes. All examples use the following secret keys and impression ID:

Parameter	Value
`padKey`	`we-will-use-this-key-for-the-pad`
`signatureKey`	`for-the-signature-we-use-another`
`impressionId`	`1234567890123456`

Each encryption of price results in the following encodedMessage:

price	encodedMessage
1.321	MTIzNDU2Nzg5MDEyMzQ1NvKEVxJuVzSmV-T3Fg
1.34	MTIzNDU2Nzg5MDEyMzQ1NvKEVxRvVzSmqBMpDw
1.345678	MTIzNDU2Nzg5MDEyMzQ1NvKEVxRqUTOun5Q4og
2.5	MTIzNDU2Nzg5MDEyMzQ1NvGEURBvVzSmiimHTA

Sample Code

Here is an example implementation in PHP.

index.php:

<?php
require_once('WinningBidEncryption.php');

$padKey = 'we-will-use-this-key-for-the-pad'; // 32 bytes ;-)
$signatureKey = 'for-the-signature-we-use-another'; // too

$impressionId = '1234567890123456';
$price = '1.321';

$winningBidEncryption = new WinningBidEncryption($padKey, $signatureKey);

echo 'price = ' . $price . '<br />';

$encodedMessage = $winningBidEncryption->encrypt($impressionId, $price);
echo 'encoded message = ' . $encodedMessage . '<br />';

$priceAgain = $winningBidEncryption->decrypt($encodedMessage);
echo 'price again = ' . $priceAgain;

The output is:

price = 1.321
encoded message = MTIzNDU2Nzg5MDEyMzQ1NvKEVxJuVzSmV-T3Fg
price again = 1.321000

WinningBidEncryption.php

<?php
class WinningBidEncryption
{
    private $padKey = NULL;
    private $signatureKey = NULL;

    public function __construct($padKey, $signatureKey)
    {
        assert(strlen($padKey) == 32); // must be 32 bytes
        assert(strlen($signatureKey) == 32); // too

        $this->padKey = $padKey;
        $this->signatureKey = $signatureKey;
    }

    private function base64Encode($input)
    {
        // see http://tools.ietf.org/html/rfc3548#page-6

        $output = base64_encode($input);
        $output = strtr($output, '+/', '-_'); // make web-safe
        $output = rtrim($output, '='); // remove padding

        return $output;
    }

    private function base64Decode($input)
    {
        // add padding
        if (strlen($input) % 4 == 2)
        {
            $input .= '==';
        }
        elseif (strlen($input) % 4 == 1)
        {
            $input .= '=';
        }
        $input = strtr($input, '-_', '+/'); // make web-unsafe
        $output = base64_decode($input);

        return $output;
    }

    public function encrypt($impressionId, $price)
    {
        $impressionId = substr($impressionId, 0, 16); // only the first 16 bytes
        $price = str_pad($price, 8, '0'); // pad price to 8 bytes

        $pad = hash_hmac('sha1', $impressionId, $this->padKey, true); // raw
        $pad = substr($pad, 0, 8); // only the first 8 bytes

        $encryptedPrice = $pad ^ $price; // xor

        $signature = hash_hmac('sha1', $price . $impressionId,
            $this->signatureKey, true); // true
        $signature = substr($signature, 0, 4); // only the first 4 bytes

        // put it together
        $message = $impressionId . $encryptedPrice . $signature;

        return $this->base64Encode($message);
    }

    public function decrypt($encodedMessage)
    {
        $message = $this->base64Decode($encodedMessage);

        // take it apart
        $impressionId = substr($message, 0, 16); // 16  bytes
        $encryptedPrice = substr($message, 16, 8); // 8 bytes
        $signature = substr($message, 24, 4); // 4 bytes

        $pad = hash_hmac('sha1', $impressionId, $this->padKey, true); // raw
        $pad = substr($pad, 0, 8); // only the first 8 bytes

        $price = $encryptedPrice ^ $pad; // xor

        $checkSignature = hash_hmac('sha1', $price . $impressionId,
            $this->signatureKey, true); // raw
        $checkSignature = substr($checkSignature, 0, 4); // only the first 4 bytes

        // check signature
        if ($checkSignature != $signature)
        {
            return -1;
        }

        // $price = rtrim($price, '0'); // remove trailing zeros

        return $price;
    }
}

Table of Contents ¶

API History ¶

General ¶

Foreign Currencies Support ¶

Ad Serving Option ¶

Native Advertisement Support ¶

Bid Request ¶

HTTP Versions ¶

HTTP Headers ¶

Bid Request Object ¶

Source Object ¶

Source Extension Object ¶

Supply Chain Object ¶

Supply Chain Node Object ¶

Impression Object ¶

Impression Extension Object ¶

Banner Object ¶

Banner Extension Object ¶

Format Object ¶

Format Extension Object ¶

Video Object ¶

Native Object ¶

Native Markup Request Object ¶

Asset Object ¶

Title Object ¶

Image Object ¶

Data Object ¶

Site Object ¶

Site Extension Object ¶

App Object ¶

Content Object ¶

Content Extension Object ¶

Device Object ¶

Device Extension Object ¶

Geo Object ¶

Publisher Object ¶

Regulations Object ¶

Regulations Ext Object ¶

DSA Transparency Object ¶

User Object ¶

User Ext Object ¶

Extended Identifiers ¶

Extended Identifier UIDs ¶

PMP Object ¶

Direct Deals Object ¶

Event Tracker Request Object ¶

Enumerated Lists ¶

API Frameworks ¶

Connection types ¶

Context types ¶

Delivery methods ¶

Video placement types ¶

Video plcmt types ¶

Video playback methods ¶

Bid Request Examples ¶

Display, Private Market Place ¶

Video, Mid-Roll, Private Market Place ¶

App ¶

Native Bid Example ¶

Special Advert Types ¶

Popunder Adverts ¶

Mobile Interstitial Adverts ¶

Floor Adverts ¶

Interstitial Adverts ¶

Layer Adverts ¶

Sticky Adverts ¶

Dynamic Sitebar Adverts ¶

Video Ad Formats ¶

Bid Response ¶

Bid Response Object ¶

Seat Bid Object ¶

Bid Object ¶

Bid Extension Object* ¶

DSA Transparency Object ¶

Substitution Macros ¶

Native Markup Response Object ¶

Link Object ¶

Asset Object ¶

Title Object ¶

Image Object ¶

Table of Contents

API History

General

Foreign Currencies Support

Ad Serving Option

Native Advertisement Support

Bid Request

HTTP Versions

HTTP Headers

Bid Request Object

Source Object

Source Extension Object

Supply Chain Object

Supply Chain Node Object

Impression Object

Impression Extension Object

Banner Object

Banner Extension Object

Format Object

Format Extension Object

Video Object

Native Object

Native Markup Request Object

Asset Object

Title Object

Image Object

Data Object

Site Object

Site Extension Object

App Object

Content Object

Content Extension Object

Device Object

Device Extension Object

Geo Object

Publisher Object

Regulations Object

Regulations Ext Object

DSA Transparency Object

User Object

User Ext Object

Extended Identifiers

Extended Identifier UIDs

PMP Object

Direct Deals Object

Event Tracker Request Object

Enumerated Lists

API Frameworks

Connection types

Context types

Delivery methods

Video placement types

Video plcmt types

Video playback methods

Bid Request Examples

Display, Private Market Place

Video, Mid-Roll, Private Market Place

App

Native Bid Example

Special Advert Types

Popunder Adverts

Mobile Interstitial Adverts

Floor Adverts

Interstitial Adverts

Layer Adverts

Sticky Adverts

Dynamic Sitebar Adverts

Video Ad Formats

Bid Response

Bid Response Object

Seat Bid Object

Bid Object

Bid Extension Object*

DSA Transparency Object

Substitution Macros

Native Markup Response Object

Link Object

Asset Object

Title Object

Image Object