Skip to end of metadata
Go to start of metadata

Bid Response from Bidders

This describes the integration of the OpenRTB 2.4 protocol.

A bidder will send a bid response after it receives a Bid Request from the impression bus. The bid response will include the bidder's bid (price) and chosen creative (creative_id or creative_code). This creative will be served if the bid is ultimately accepted by the ad server. Multiple bids within the bid response are encouraged.

On This Page

Implementation

Xandr expects all calls to return HTTP code 200 except for an empty bid response (no bid), which will return HTTP code 204. We currently support the following fields in the bid response object:

Bid Response Object

Field

Type

Description

id

string

(Required) The ID of the bid request to which this is a response.

seatbid

array of objects

(Required if a bid is made) Used for identifying  seatbid objects. See Seat Bid Object below.

bidid

string

The bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross-reference.

This is used only to populate the macro ${AUCTION_BID_ID}. We do not store this information.

cur

string

The bid currency using ISO-4217 alphabetic codes. If omitted, default is USD. Also used for the macro ${AUCTION_CURRENCY} in the win notify URL and creative or pixel payload.

Seat Bid Object

 Xandr supports the following fields in the seatbid object, each of which represents a different bidder seat and contains one or more individual bids:

Field

Type

Description

bid

array of objects

(Required) An array of bid objects; each bid object relates to an Impression Object in the Bid Request. Note that, if supported by an exchange, one Impression Object can have many bid objects. See Bid Object for more information.

seat

string

(Required) The ID of the member whose creative is chosen by the bidder. Corresponds to the Xandr member_id. Also used to populate the ${AUCTION_SEAT_ID} macro in the win notify URL and creative or pixel payload. 

Bid Object

Field

Type

Description

id

string

(Required) The ID for the bid object; this is chosen by the bidder for tracking and debugging purposes. Useful when multiple bids are submitted for a single impression for a given seat.

impid

string

(Required) The ID of the impression object to which this bid applies. Should match the id field from the bid request's impression object. Can be used to populate the ${AUCTION_AD_ID} macro.    

price

float

(Required) The bid price expressed in CPM. Also used to populate the ${AUCTION_PRICE} macro.

If the bid_payment_type is not set to "Impression", then price will be the eCPM price for the bid, and the payment_type_price will be used to populate the ${AUCTION_PRICE} macro.

Note: bid_payment_type is is not enabled for all clients. Please reach out to your account representative for this feature. 

Although this value is a float, OpenRTB strongly suggests using integer math for accounting to avoid rounding errors.

adid

string

The Xandr creative ID, viewable via the API using the Creative Service. This ID references the actual ad to be served if the bid wins. Can be used to populate the ${AUCTION_AD_ID} macro. If both adid and crid are passed, adid takes precedence.

nurl

string

The win notify URL, which is dropped as a pixel into the web browser or SDK. Our server pings this URL when it receives a client side notification from the device, which indicates that we won the auction. Responses will be sent server side. This occurs at the same time that we record the impression. The max length is 2000 characters with macros expanded.

Win notify URLs using HTTPS are not supported. These notifications will not be sent. Please ensure you are only sending HTTP urls.

The following macros are supported in the notify URL:

  • ${AUCTION_ID} - Xandr auction_id_64
  • ${AUCTION_BID_ID} - ID of the bid specified in the bidid field in the bid response
  • ${AUCTION_IMP_ID} - ID of the impression, from the impid field in the bid object of the seatbid object
  • ${AUCTION_SEAT_ID} - ID of the winning seat, from the seat field in the seatbid object
  • ${AUCTION_AD_ID} - ID of the buyer's creative, from the adid field in the bid object of the seatbid object
  • ${AUCTION_PRICE} - Clearing price of the impression in the currency specified in the cur field in the bid response
  • ${AUCTION_CURRENCY} - Currency of the clearing price, as specified in the cur field in the bid response
  • ${CREATIVE_CODE} - The code field set on the creative object via the API when registering a creative
  • ${AN_PAYMENT_TYPE} - ID of the payment type of bid specified in the bid_payment_type field of the bid response (Note: This macro is not enabled for all clients. Please reach out to your account representative for this feature.)

Only the macros in the preceding list can be used in the notify URL, no other macros are supported in the bid response.

cridstringThe creative ID from the bidder's system. Used to reference a Xander creative based on the creative code as set via the Creative Service . If both adid and crid are passed, adid takes precedence.
dealidstringThe deal ID from the deal object in the Bid Request, if this bid relates to a deal.

ext

object

Used for identifying platform-specific extensions to the OpenRTB bid response. See Bid Response Extension Object below.

Bid Reponse Extension Object

Xandr supports a single object in the ext object to support platform-specific extensions:

Field

Type

Description

appnexus

object

Specifies the platform-specific extensions to the OpenRTB bid response. See AppNexus Object below.

AppNexus Object

Xandr supports the following fields in the appnexus extension object:

Field

Type

Description

custom_macrosarray of objectsUsed for identifying custom_macro objects. See Custom Macro Object below.
min_pricefloat

The minimum price to which the bid should be reduced in the second price auction.

spend_protection_pixel_idsarray of integers

Deprecated.

custom_notify_data
string

Note: This feature is not enabled by default. You must request to have this field enabled. 

Use this field to pass information to the Notify Request. The string is entered as freeform text and will be automatically URL- and/or cookie-encoded by ImpBus.

click_url
stringThe click URL to be associated with the creative. This field should contain a redirect link. For example, "http://mydomain.com/abcd?redir="
enable_bid_shading
integer

Note: This field is in the process of being deprecated. It is set as false irrespective of the value sent in the bid response.

bid_payment_type
array of objects

Note: This feature is not enabled by default. You must request to have this field enabled. 

Specifies the payment type for which the Bidder is bidding and will be billed. If omitted, then we will consider the payment type to be 'impression'.

Custom Macro Object

Xandr supports the following fields in the custom_macro object of the appnexus extension object:

Field

Type

Description

namestringThe name of the macro to be replaced in any of the creative's URLs (media, pixel, click, and so on). The name must be formatted as ${MACRO_NAME} within the creative's URL or content. Note that the custom macros are replaced AFTER system macros have been replaced. See the example below, and refer to the Creative Service for more information.
valuestring

The value used to replace the macro. Do not escape forward slashes. Even if the value is an integer, it must be placed within quotation marks (for example, "42"). The max length of the value is 550 characters.

Bid Payment Type Object

Xandr supports the following fields in the bid_payment_type object of the appnexus extension object:

Note: This feature is not enabled by default. You must request to have this field enabled. 

Field

Type

Description

payment_type
integer

Specifies the payment type for which the Bidder is bidding and will be billed. If the payment type is not 'impression', then a billing notify url must be set on the bid object. The currently supported values are -

  • 1: Impression
  • 2: Viewable Impression

Currently, for "Viewable Impression" bids, only USD bids are supported.

price
double

Specifies the bid price for the payment type. For the 'Viewable Impression' payment type, the bid price will be vCPM.



Why we don't support the adm field

AppNexus works with members who care deeply about brand and reputation. For this reason, we are careful to ensure that the advertisements (creatives) that pass through our system are acceptable to all parties. For quality assurance, all creatives that serve on third-party inventory must be pre-registered using the Creative Service.

For these reasons, AppNexus does not support the adm field (which allows bidders to pass in the actual ad markup). Instead, we construct the ad markup using the provided adid and nurl for win notification.

Example Bid Response

Example Multi-Bid Response

 

Win Notification

For more information, see the definition of the nurl field above.

In certain auction types, a lost or pending notification may be generated prior to the win notification. Win notifications are always authoritative and override any other notifications previously received for that auction.

Loss Notification

If you opt for a loss notification, it will look something like this. The loss notification information appears at the end of the response.

  • No labels