Bid Response Buyer Protocol

bid

array of objects

Array of Bid Objects, see Bid Object. The maximum number of bid objects per single bid request ad slot is two.

seat*

string

The seat ID of the bidder on whose behalf this bid is made. The value should match one of the values supplied in the wseat field of the bid request. For example, "34".

• This field is always required in responses, unless you have your account setup for single-seat responses, see the Seat ID and Agency Mapping section for more details about that.

• Some Suppliers expect their Buyers to respond with their Seat ID rather than Commerce Grid’s ID, see the Seat Self-Management for a list o those Suppliers.

group*

integer

The following values are supported:

• 0 (default): impressions can be won individually

• 1: impressions must be won or lost as a group

id

string

A bidder-generated ID for the bid object, used for tracking and debugging purposes, for example 3.

impid

string

The ID of the impression object (imp) from the bid request to which this bid response applies, for example "1"

price

float

The bid price as a float value, expressed as CPM. All prices assumed to be in USD if the cur parameter is omitted, for example 1.23

protocol*

integer

The Video response protocol of the markup if applicable, see the Video Response Protocols table for the valid values.

Note: This field is required in video responses.

adm*

string

Creative markup for banner ads.

• This field is required for banner ads, and is ignored for video or native bid responses.

• No more than one win price macro can be used in the adm field, otherwise The MediaGrid records multiple impression events.

• When using an <iframe> to include markup and/or pixel trackers, you should close the </iframe> properly as not doing so may result in discrepancies on some browsers.

<a href=\"http://adserver.com/click?adid=125&tracker=${CLICK_URL:URLENCODE}\"> <img src=\"http://image1.cdn.com/impid=102\"/></a>

burl

string

(Required) Specifies the billing notice URL called by Commerce Grid using a server-to-server call when Commerce Grid records a billable impression.

• This field should contain the win price macro, and there can only be one win price macro, see the Macros section.

• Commerce Grid expects that burl calls should return a HTTP status 200, 204, or 30x, see the Server-to-Server (s2s) Calls section for more information.

• You can respond with a non-secure burl for secure bid requests:

"burl":"http://dsp.com/winnotice?impid=102&winprice=${AUCTION_PRICE}"

nurl

string

(Optional) The win notice URL called if the bid wins.

• This field should not be used for submitting creative markup.

• The URL can contain the win price macro, see the Macros section

• This URL will be mostly called from the user’s browser and should thus be SSL-compliant for requests with imp.secure set to 1.

http://dsp.com/winnotice?impid=102&winprice=${AUCTION_PRICE}

iurl*

string

Sample image URL (without cache busting) for content checking, e.g. "http://adserver.com/preview?impid=102"

REQUIRED: for banner bid requests.

language*

string

The Alpha-2 ISO 639-1 code for the creative’s language, for example, ja. The nonstandard code "xx" may also be used if the creative has no linguistic content (e.g., a banner with just a company logo).

Use this field instead of the deprecated bid.ext.language field.

adid*

string

ID that references the ad to be served if the bid wins. Either the adid field or crid field should be present in the response, for example "3021"

Notes:

• Sometimes a Supplier’s CA Service bans creatives that seen in both secure (https) and non-secure (http) forms. Therefore it is recommended to have separate IDs for secure and non-secure versions of the same creative, e.g. cr_123 & cr_123_ssl

• When The MediaGrid passes the creative ID to the Supplier it prepends the Buyer ID, using the the following syntax: {DSP_ID}_{Creative_ID}, for example 70_650029457 or 79_0RsSUxZety0O1.

• When The MediaGrid receives both adid and crid fields, the adid ID field is used to pass the creative ID to Suppliers

adomain

array of strings

Advertiser’s primary or top-level domain for advertiser checking. This can be a list of domains if there is a rotating creative. :Note:

• Some Suppliers allow only one domain. To those Suppliers The MediaGrid only sends the first domain from the list, for example, ["advertiser.com"]

• The MediaGrid invalids non-ascii domains. If you need to pass a domain that uses unicode character such as in the Cyrillic or Japanese script, use punycode

  e.g. детивнепитики.рф or faß.de

bundle*

string

A platform-specific application identifier intended to be unique to the app and independent of the exchange. On Android, this should be a bundle or package name (e.g., com.foo.mygame)

cid*

string

Campaign ID or similar that is used by the Buyer to track and organize their campaigns, for example, 102

REQUIRED in responses for Rubicon, Nexage, Smaato and MoPub.

crid*

string

Creative ID to assist with ad quality checking. Either the adid field or crid field should be present in the response, for example “3021”

Notes:

• Sometimes a Supplier’s CA Service bans creatives that are seen in both secure (https) and non-secure (http) forms. Therefore it is recommended to have separate IDs for secure and non-secure versions of the same creative, e.g. cr_123 & cr_123_ssl

• When The MediaGrid passes the creative ID to the Supplier it prepends the Buyer ID, using the the following syntax: {DSP_ID}_{Creative_ID}, for example 70_650029457 or 79_0RsSUxZety0O1.

• When The MediaGrid receives both adid and crid fields, the adid ID field is used to pass the creative ID to Suppliers

attr*

array of integers

Creative attributes as defined in the OpenRTB protocol, for example, [1,3].

dealid*

string

Reference to the deal.id from the bid request, if this bid pertains to a private marketplace direct deal, for example, "AA-1234"

h*

integer

The height of the creative in pixels when an alternative ad size is used, is relevant for banner ads only. 250. Required: For Pubmatic Banner ads.

w*

integer

The width of the creative in pixels when an alternative ad size is used, is relevant for banner ads only. 300. Required: For Pubmatic Banner ads.

cat*

array of strings

The IAB category of the creative.

slotinpod*

integer

Indicates that the bid response is only eligible for a specific position within a video or audio ad pod

mtype*

integer

Type of creative markup. The following values are supported:

• 1: Banner

• 2: Video

• 3: Audio

• 4: Native

dur*

integer

Duration of the video or audio creative in seconds.

ext*

object

This field may be required under certain circumstances, see Bid Ext Object.

data*

array of object

Returns arbitrary data to the Supplier, each object can take data.name and data.value to describe the data, see the Data Response Object for more details.

vast_url*

string

The URL pointing to the location of the VAST document for bid responses to video traffic, for example, "http://adserver.com/vast?impid=102"

• Required if the video.ext.vast_url_rq bid request field is set to 1.

• If the video.ext.vast_url_rq bid request field is set to 0 or missing, you can include the VAST URL in the nurl field.

For more information see the Video Ext Object section.

Note:

• The VAST URL should NOT contain a win price macro.

• The VAST document should NOT contain impression tracking URLs with win price macros.

daast_url*

string

The URL pointing to the location of the DAAST document for the bid response, for example, "http://adserver.com/daast?impid=102"

REQUIRED for bid responses to audio traffic.

Note:

• The DAAST URL should NOT contain a win price macro.

• The DAAST document should NOT contain impression tracking URLs with win price macros.

native*

object

Contains the details of the native response, for more information, see Native Response Object.

skadn*

object

Apple Ad Network Object, will be used to pass app data from iOS 14 and newer releases. See SkAdNetwork Extension

version*

str

Version of SKAdNetwork desired. Must be “2.0” or above. From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

network*

str

Ad network identifier used in signature. Should match one of the items in the imp.ext.skadnetids array in the request

campaign*

str

Campaign ID compatible with Apple’s spec. As of 2.0, this should be an integer between 1 and 100, expressed as a string, e.g. "45"

fidelities*

array of objects

Supports multiple fidelity types introduced in SKAdNetwork v2.2, see the SkAdNetwork Fidelities object for details.

From SKAdNetwork v2.2 onwards, this object wraps some of the other fields in this table into it. As a result, nonce, version, timestamp and signature should be used in the fidelities object and considered deprecated in this object.

itunesitem*

str

ID of advertiser’s app in Apple’s app store. Should match the seatbid.bid.bundle response field e.g “880047117”

nonce*

str

An ID unique to each ad response (GUID/UUID) e.g. "beeeb65e-b3de-02420004". From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

sourceapp*

str

ID of publisher’s app in Apple’s app store, this should match the imp.ext.skadn.sourceapp value

timestamp*

str

Unix time in millis string used at the time of signature. From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

signature*

str

SKAdNetwork signature as specified by Apple e.g. "MEQCIEQZRRyMyUXg==". From SKAdNetwork v2.2 onwards, this should be used in the fidelities object.

fidelity*

int

The fidelity-type of the attribution to track e.g 1

nonce*

str

An ID unique to each ad response (GUID/UUID) e.g. "beeeb65e-b3de-02420004"

timestamp*

str

Unix time in millis string used at the time of signature

signature*

str

SKAdNetwork signature as specified by Apple e.g. "MEQCIEQZRRyMyUXg=="