Win and loss notifications

Overview

You can use win and loss notifications to receive pings with details about wins and losses for your bids in Real-time Bidding. These are only supported when bidding on mobile app inventory. You can configure these notifications to include server-side auction feedback similar to Real-time feedback, as well as mediation chain feedback.

Mobile app publishers use a mediation chain in products such as Ad Manager and AdMob to have their ad request reach multiple ad networks, increasing the likelihood of their inventory being filled. Mediation uses a waterfall model where ad networks are ordered by their expected bid in descending value, and the first network in the waterfall to return a winning bid will place their ad. As a result, it is possible for you to place a winning bid for mobile inventory in Google's exchange, and still not win the impression in the overall mediation chain.

Google recommends that you implement win and loss notifications for mobile app inventory in order to be better informed of your win or loss in the mediation chain. These are configured by populating corresponding fields with a URL in the bid response. Google will ping the win notification URL if the bid wins, or the loss URL if the bid is filtered or lost. We recommend that you construct win and loss notification URLs to include request-level data; for example, the bid request ID, and use macros to get your preferred data. These URLs are specified in the following response fields:

OpenRTB
- Win URL: BidResponse.seatbid.bid.nurl
- Loss URL: BidResponse.seatbid.bid.lurl
Google RTB
- Win URL: BidResponse.ad.win_notice_url
- Loss URL: BidResponse.ad.loss_notice_url

Supported macros

Macros can help provide insight into both the server-side auction and the on-device mediation waterfall. Macros supported in win and loss notification URLs include the following.

OpenRTB

Macro string	Description	Supported in `nurl`	Supported in `lurl`
`${AUCTION_ID}`	The ID of the bid request.	Yes	Yes
`${AUCTION_BID_ID}`	The ID of the bid in the bid response.	Yes	Yes
`${AUCTION_IMP_ID}`	The ID of the impression in the bid response.	Yes	Yes
`${AUCTION_SEAT_ID}`	The ID of the bidder seat in the bid response.	Yes	Yes
`${AUCTION_AD_ID}`	The ID of the ad in the bid response.	Yes	Yes
`${AUCTION_PRICE}`	The impression cost in CPM in units of the bid currency if the bid won the auction. This is different from the use of the macro in impression tracking URLs, where the same macro is replaced with an encoded impression cost in CPI micros and units of the bid currency.	Yes	No
`${AUCTION_LOSS}`	Google supports most OpenRTB loss reason codes. Additionally, Google will send loss reason value `501` to indicate that a bid lost in the mediation waterfall.	No	Yes
`${CREATIVE_STATUS_CODE}`	Google-specific status code for the ad. Possible values can be found in creative-status-codes.txt.	No	Yes
`${AUCTION_MIN_TO_WIN}`	The minimum bid to win of the server side auction in CPM and units of the bid currency. If this macro is replaced by a non-empty string, the bid had to have been higher than the replaced macro value in order to win the server side auction. The units are different from the existing `BidRequest.ext.bid_feedback.minimum_bid_to_win` field, which is expressed in CPM and units of the buyer account currency.	Yes	Yes
`${WINNING_MEDIATION_ECPM}`	The estimated CPM of the winning item in the mediation chain in units of the bid currency. This macro is replaced with an empty string if there is no estimated CPM associated with the line item or if the estimated CPM is unavailable. If this macro is replaced by a non-empty string, the bid had to have been higher than the replaced macro value in order to win the mediation waterfall.	No	Yes

Google RTB

Macro string	Description	Supported in `win_notice_url`	Supported in `loss_notice_url`
`%%WINNING_PRICE%%`	The impression cost in CPM and units of the bid currency if the bid won the auction. This is different from the use of the macro in impression tracking URLs, where the same macro is replaced with an encoded impression cost in CPI micros and units of the bid currency.	Yes	No
`%%AUCTION_MIN_TO_WIN%%`	The minimum bid to win of the server side auction in CPM and units of the bid currency. If this macro is replaced by a non-empty string, the bid had to have been higher than the replaced macro value in order to win the server side auction. The units are different from the existing `BidRequest.bid_response_feedback.minimum_bid_to_win` field, which is expressed in CPM micros and units of the buyer account currency.	Yes	Yes
`%%AUCTION_LOSS%%`	Google supports most OpenRTB loss reason codes. Additionally, Google will send loss reason value `501` to indicate that a bid lost in the mediation waterfall.	No	Yes
`%%CREATIVE_STATUS_CODE%%`	Google-specific status code for the ad. Possible values can be found in creative-status-codes.txt.	No	Yes
`%%WINNING_MEDIATION_ECPM%%`	The estimated CPM of the winning item in the mediation chain in units of the bid currency. This macro is replaced with an empty string if there is no estimated CPM associated with the line item or if the estimated CPM is unavailable. If this macro is replaced by a non-empty string, the bid had to have been higher than the replaced macro value in order to win the mediation waterfall.	No	Yes

Example Bid Responses

OpenRTB Protobuf

...
seatbid {
    ...
    bid {
        ...
        nurl: "http://example.com/win?win_price=${AUCTION_PRICE}&mbtw=${AUCTION_MIN_TO_WIN}"
        lurl: "http://example.com/loss?mbtw=${AUCTION_MIN_TO_WIN}&loss_reason=${AUCTION_LOSS}&creative_status_code=${CREATIVE_STATUS_CODE}&mediation_ecpm=${WINNING_MEDIATION_ECPM}"
    }
}

OpenRTB JSON

{
  ...
  "seatbid": [
      ...
      "bid": [
          {
              ...
              "nurl": "http://example.com/win?win_price=${AUCTION_PRICE}&mbtw=${AUCTION_MIN_TO_WIN}",
              "lurl": "http://example.com/loss?mbtw=${AUCTION_MIN_TO_WIN}&loss_reason=${AUCTION_LOSS}&creative_status_code=${CREATIVE_STATUS_CODE}&mediation_ecpm=${WINNING_MEDIATION_ECPM}"
          }
      ]
  ]
}

Google RTB

...
ad {
    ...
    win_notice_url: "http://example.com/win?win_price=%%WINNING_PRICE%%&mbtw=%%AUCTION_MIN_TO_WIN%%"
    loss_notice_url: "http://example.com/loss?mbtw=%%AUCTION_MIN_TO_WIN%%&loss_reason=%%AUCTION_LOSS%%&creative_status_code=%%CREATIVE_STATUS_CODE%%&mediation_ecpm=%%WINNING_MEDIATION_ECPM%%"
}