Skip to main content
Table of contents

Bid Response Ext Object

Bid Response Ext Object Properties

Value

Type

Description

protocol

string

(Optional) The latest The MediaGrid protocol version this bid response is compliant with, for example "1.0". For version 1.0 of the protocol this is optional.

Seat Bid Object

Formally there can be multiple bids within the Seat Bid object for two reasons.

  • There can be several slots in each bid request.

  • There can be more than one bid for a single slot.

Commerce Grid allows no more than two bids for a single ad slot. Bids belonging to the same seat must be in the same seatbid.bid array, i.e. all seatbid.seat values must be unique per response.

Note

Fields marked with an asterisk (*) are optional.

Seat Bid Object Properties

Value

Type

Description

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

Bid Object

Note

(*) Fields marked with an asterisk are usually optional, but may be required for some Suppliers; check for usage notes

Bid Object Properties

Value

Type

Description

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.

Bid Ext Object

Bid Ext Object Properties

Value

Type

Description

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

SkAdNetwork Extension

skadn Ext Object Properties

Value

Type

Description

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.

Note

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.

SkAdNetwork Fidelities

Fidelities Object Properties

Value

Type

Description

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=="

Native Response Object

Note

Fields marked with an asterisk (*) are optional.

Native Object Properties

Value

Type

Description

assets

array of objects

List of native ad assets.

link

object

The Native Link Object. This is the default link object for the ad. Individual assets can also have a link object which applies if the asset is activated (clicked). If the asset has no link object, the parent link object applies.

ext*

object

Native Ext Object

ver*

string

Version of the Native Markup version in use, for example, "1".

privacy*

string

If support was indicated in the request, return the URL of a page informing the user about the buyer’s targeting activity.

eventtrackers*

array of objects

Specifies what type of event tracking is supported, see Event Tracker Response Object

imptrackers **

array of strings

Deprecated since version 5.3: replaced by the eventtrackers field

An array of impression tracking URLs, expected to return a 1x1 image or 204 response, for example, ["http://adserver.com/native?impid=102"]. This URL can contain the win_price macro.

jstracker*

string

Deprecated since version 5.3: replaced by the eventtrackers field

Optional JavaScript impression tracker. This should be valid HTML with JavaScript already wrapped in <script> tags. It will be executed at impression time where it can be supported.

Note: Currently the only Supplier that supports this field is TripleLift.

Note

(**) imptrackers array should be used with following constraints:

For Rubicon, only one element is guaranteed to be triggered. Place the trackers in the order of importance, otherwise, this array is optional and may not be present in each response.

Native Assets Object

Note

  • (*) There may be exactly one of the fields marked with an asterisk in one asset object.

  • (**) The link object is optional and may not be present in each response.

Native Asset Object Properties

Value

Type

Description

id

integer

A unique asset ID, must match one of the asset IDs in the bid request, for example, 1.

required*

integer

Set to 1 if the asset is required (bidder requires it to be displayed), default is 0, for example, 1.

title*

object

Title object for a title asset, see, Native Assets Title Object.

img*

object

Image object for an image asset, see, Native Assets Image Object.

video*

object

Video object for a video asset, see, Native Asset Video Object.

data*

object

Data object for a data asset, see, Native Asset Data Object.

link **

object

Link object for a call to action.

  • The link object applies if the asset item is activated (clicked).

  • If there is no link object on the asset, the parent link object on the bid response applies. See Native Link Object.

Native Assets Title Object

Native Asset Title Object Properties

Value

Type

Description

text*

string

The text associated with the title element. "Our product is the best!"

Native Assets Image Object

Native Asset Image Object Properties

Value

Type

Description

url

string

(Required) URL of the image asset, for example, "http://adserver.com/image?impid=102".

h

integer

(Recommended) Height of the image in pixels, for example, 250.

w

integer

(Recommended) Width of the image in pixels, for example, 300.

Important

If the Supplier specifies the exact w/h or the wmin/hmin in the bid request, the bid response must contain the w/h values and these fields become required, see the relevant request field for details Native Asset Image Object.

Native Asset Data Object

Native Asset Data Object Properties

Value

Type

Description

value

string

The formatted string of data to be displayed. Can contain a formatted value such as “5 stars” or “$10” or “3.4 stars out of 5”.

Native Link Object

Native Link Object Properties

Value

Type

Description

url

string

Landing URL of the clickable link, for example, "http://advertiser.com/"

clicktrackers*

array of strings

Click tracker URLs to be activated when the URL is clicked, for example, ["http://adserver.com/click?impid=102"]

Native Video Response Object

Note

Fields marked with an asterisk (*) are optional.

Native Asset Video Object

Native Asset Video Object Properties

Value

Type

Description

vasttag

string

Vast XML, use the following example to format your VAST XML response. See the VAST Tag example below, Video Asset vasttag Example.

ext*

object

Native Asset Video Object Extension

Native Asset Video Object Extension

Native Asset Video Object Extension Properties

Value

Type

Description

playbackmethod*

integer

Desired video playback method

Native Link Object Properties

Value

Type

Description

url

string

Landing URL of the clickable link, for example, "http://advertiser.com/"

clicktrackers*

array of strings

Click tracker URLs to be activated when the URL is clicked, for example, ["http://adserver.com/click?impid=102"]

Event Tracker Response Object

The event trackers response is an array of objects and specifies the types of events the bidder wishes to track and the URLs/information to track them. Buyers must only respond with methods indicated as available in the request.

Note

Most javascript trackers expect to be loaded at impression time, so it’s not generally recommended for the Buyer to respond with javascript trackers on other events. Still, the appropriateness of this is up to each Buyer.

Event Tracker Response Object

Value

Type

Description

event

integer

Type of event to track, see the Event Tracking Types table

method

integer

Type of method to track, see the Event Tracking Methods table

url*

string

The URL of the impage or js. Required for image or js, optional for custom. This value can contain the win_price macro.

customdata*

object

containing key:value pairs - To be agreed individually with the exchange, an array of key:value objects for custom tracking, for example the account number of the DSP with a tracking company. IE {“accountnumber”:”123”}.

ext*

object

This object is a placeholder that may contain custom JSON agreed to by the parties to support flexibility beyond the standard defined in this specification.

Data Response Object

Can be used to return arbitrary data to your Suppliers, if they support this field.

Bid Response Data Extension Object

Value

Type

Description

name

string

Used to specify the name of the entity to which the value refers, e.g. "Scan Code"

value

string

The value for the named data type being returned to the Supplier, e.g. "1iuyyw-

Display Banner Bid Response

The following example shows an ad being served from the adm field, with the bid price for the impression being $9.43 CPM.

Secure Banner Bid Response

The following example shows an ad being served from the adm field, with the bid price for the impression being $9.43 CPM, and suitable for serving in HTTPS environment.

iOS 14 Banner Bid Response

See the highlighted lines that denote the iOS 14 fields, see the Protocol Release Notes for more details.

Video Bid Response

Secure Video Bid Response

Secure Audio Bid Response

Native Bid Response

Secure Native Bid Response

The following example shows a native bid response with the title and image asset specified for serving in an HTTPS environment.

Multi-bid Response

Please pay attention to the following conditions:

  • The total size of your response should not exceed 50 kb

  • There can be 2 seatbid.bid objects within 1 seatbid object

  • A response containing two bids for the same impression should contain both bid objects within the same seatbid.bid array of objects

The following bid response example contains two bids, one for $9.43 CPM and one for $5.50 CPM. Both bids target the same ad slot, both would take part in the auction and if the first one is discarded due to publisher-side blocklist then the second one would be able to win the auction.

Private Deal Bid Response

Buyer No Bid Response

The following example shows a No Bid Response coming from a Buyer, which is an empty bid response.

Note

The preferred No Bid Response format is an empty HTTP 204 response.

No Bid Reason

The following example shows a No Bid Reason response, which includes the reason code in the nbr field. See the Buyer No-bid Response / Reason section for more information.

TV/DOOH Bid Response