Response Bid Object

Note

  • (*) Fields marked with an asterisk are optional.

  • While individually neither of the following fields is required, one of them must be in the response: adm, adm_native.

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

Used to pass creative markup for display (banner), video, or audio ads. One of either adm or adm_native should be present in the response.

  • This field can contain the win price macro.

  • This field is not used for native bid responses.

<a href=\"http://adserver.com/click?adid=125\"> <img src=\"http://image1.cdn.com/impid=102\"/></a>

adm_native*

object

Used for native bid responses, see the Native Response Object for the data it contains. One of either adm or adm_native should be present in the response.

burl

string

The Billing notice URL called by the exchange using a server-to-server call when a winning bid becomes billable based on exchange-specific business policy (e.g., typically delivered, viewed, etc.).”

This field should contain the win price macro, see the Macros section.

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

iurl*

string

Sample image URL (without cache busting) for content checking. REQUIRED when bidding on on banner bid requests.

"http://adserver.com/preview?impid=102"

lurl*

string

Loss notice URL called by the exchange when a bid is known to have been lost. Substitution macros may be included. Exchange-specific policy may preclude support for loss notices or the disclosure of winning clearing prices resulting in ${AUCTION_PRICE} macros being removed (i.e., replaced with a zero-length string).

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).

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 that some Suppliers allow only one domain. To those Suppliers BidSwitch only sends the first domain from the list, for example, ["advertiser.com"]

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)

cat*

array of strings

Array of IAB content categories, for example, ["IAB1", "IAB2-3"]. Based on the IAB taxonomy, and extended with additional sensitive categories listed in the Sensitive Categories and Rich Media section.

cid*

string

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

crid

string

Creative ID to assist with ad quality checking, for example “3021”

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, relevant for banner ads only. 250

w*

integer

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

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 can be used to supply information about the creative agency for whom the Buyer is working, see the Bid Ext Object section below for details.

Bid Ext Object

Bid Ext Object Properties

Value

Type

Description

advertiser_name*

string

The name of the advertiser serving the creative, for example, "Coca-Cola"

agency_name*

string

The name of the agency representing the advertiser, for example, "CCA"

agency_id*

string

ID of the agency representing the advertiser, for example, “123”

third_party_buyer_token

string

This is a Google specific response field, the token is used to identify end third-party buyer information if the exchange as an Open Bidder is an intermediary. This is obtained from the third-party buyer and must be passed to Google unaltered in the bid response. You can read more about it here https://developers.google.com/authorized-buyers/rtb/response-guide

data*

array of object

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

skadn*

object

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

dsa*

object

Digital Services Act (DSA) Ad Transparency information

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.

productpageid*

str

Passes the custom product page UUID 45812c9b-c296-43d3-c6a0-c5a02f74bf6e

sourceidentifier*

str

A four-digit integer that ad networks define to represent the ad campaign. Used in SKAdNetwork 4.0+, replaces Campaign ID campaign. Buyers must generate signatures in 4.0+ using the Source Identifier. Please refer to the SKAdNetwork 4 release notes for more details

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

DSA Extension

DSA Object Properties

Value

Type

Description

behalf*

string

Advertiser Transparency: Free UNICODE text string with a name of whose behalf the ad is displayed. Maximum 100 characters.

paid*

string

Advertiser Transparency: Free UNICODE text string of who paid for the ad. Must always be included even if it’s the same as what is listed in the behalf attribute. Maximum 100 characters

transparency*

array of objects

Array of objects of the entities that applied user parameters and the parameters they applied.

adrender*

integer

Flag to indicate that buyer/advertiser will render their own DSA transparency information inside the creative.

  • 0: buyer/advertiser will not render

  • 1: buyer/advertiser will render

Transparency Object

DSA Transparency Object Properties

Value

Type

Description

domain*

string

Domain of the entity that applied user parameters

dsaparams*

array of integers

Array of buy-side applied User Parameters targeting (using the list provided by DSA Transparency Taskforce). Include support for multiple vendors who may add their own user-targeting parameters.

{
    "ext":{
        "advertiser_name":"Coca-Cola",
        "agency_name":"CC-advertising",
        "data":[
            {
                "name":"TUV",
                "value":"ABC123"
            }
        ],
        "skadn":{
            "network":"cDkw7geQsH.skadnetwork",
            "campaign":"45",
            "itunesitem":"880047117",
            "sourceapp":"123456789",
            "fidelities":[
                {
                    "timestamp":"1594406341",
                    "signature":"2RmFS7daRzSVZRVZ8RyMyUXg==",
                    "nonce":"473b1a16-b4ef-43ad-9591-fcf3aefa82a7",
                    "fidelity": 1
                }
            ]
        },
        "dsa": {
            "behalf": "Advertiser",
            "paid": "Advertiser",
            "transparency": [{
                "domain": "dsp1domain.com",
                "dsaparams": [1,2]
            }],
            "adrender": 1
        }
    }
}

Video Response Protocols

Video Response Protocols

Value

Type

1

VAST 1.0

2

VAST 2.0

3

VAST 3.0

4

VAST 1.0 Wrapper

5

VAST 2.0 Wrapper

6

VAST 3.0 Wrapper

7

VAST 4.0

8

VAST 4.0 Wrapper

9

DAAST 1.0

10

DAAST 1.0 Wrapper

11

VAST 4.1

12

VAST 4.1 Wrapper

13

VAST 4.2

14

VAST 4.2 Wrapper