Win and loss notifications

Page Summary

Win and loss notifications provide details about bid outcomes in Real-time Bidding, specifically for mobile app inventory.
Mobile app publishers use a mediation chain, meaning a bid winning Google's exchange doesn't guarantee winning the overall impression.
You can configure win and loss notifications by including URLs in your bid response using the nurl (win) and lurl (loss) fields.
Recommended notification URLs include request-level data and utilize macros for detailed information about the auction and mediation waterfall.

Overview

You can use win and loss notifications to receive pings with details about wins and losses for your bids. You can configure these notifications to include server-side auction feedback similar to Real-time feedback, as well as mediation chain feedback.

You can configure notifications 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:

Win notification URL: BidResponse.seatbid.bid.nurl
Loss notification URL: BidResponse.seatbid.bid.lurl

Mobile app mediation chains

Mobile app publishers often 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.

Win and loss notifications can help you understand your bid's status in the overall mediation chain. If the mediation chain result is known to Google, then the notification that is sent reflects whether your bid won or lost in the mediation chain. Moreover, if your bid loses in the mediation chain, Google communicates the winning mediation chain element's estimated CPM in the loss notification. Together with the server-side minimum bid to win, you can determine the overall bid you had to submit in order to win the impression by taking the maximum of the two values.

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.

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.	Yes	Yes
`${CREATIVE_STATUS_CODE}`	Google-specific status code for the ad. Possible values can be found in creative-status-codes.txt.	Yes	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

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}"
          }
      ]
  ]
}