Marketplace Auction Notifications

• Overview
• Benefits
• Pre­requisites
• Auction Notification Response Structure
• Reason Codes
• Example Responses
• FAQ
• Questions?

Overview

Many DSP partners, in particular those who started as desktop focused, receive auction notifications or lost-bid notifications from the exchanges they are integrated with. These notifications are helpful for the following reasons:

1. Rapidly identifying and resolving technical issues
2. Identifying trends in bidding behavior
3. Understand the outcome of an auction on Pre-Cached ad formats.

Benefits

This service provides DSPs with a powerful tool to help close a key information gap with how our current RTB auctions operate. Key benefits include:

1. Full visibility into auction outcome at time of serving ­ including notification of whether the DSP wins or loses vs. network proxy
2. Complete transparency on auction fails (e.g., technical, blocks, etc)
3. Option to receive only loss transparency and not wins

Pre­requisites

In order to use the service, DSPs must:

1. Have either an RTB 2.3 or an RTB 2.5 enabled bidder
2. Provide an http OR https endpoint to receive auction notify responses

Note: Your account team can enable you to receive auction notifications permanently or periodically for debugging purposes.

Auction Notification Response Structure

The auction notification response is structured like a typical bid response. For more information on individual fields from the bid response structure, please refer to the 2.3 spec or 2.5 spec respectively.

The fields in bold denote those specific to auction notifications.

Reason Codes

Reason codes will be sent with the auction notify response and be present at different levels of the bid response hierarchy based on the specific reason. See below table for details.

Reason code mapping table

Example Responses

Server error ­- 503 response code

{
  "latency": 0.137,
  "reason": {
    "description": "non_http_ok",
    "id": 9
  },
  "bidfloor": 0.1,
  "http_status": 503,
  "id": "d42cca99­e058­4c21­a333­80d0f3efa3ce"
}

Marketplace Loss with multiple bids/reasons

{
  "latency": 0.139,
  "seatbid": [{
      "bid": [{
        "reason": {
          "description": "outbid",
          "value": "bidder",
          "id": 1
        },
        "impid": "1",
        "price": 0.25,
        "adid": "3141592",
        "id": "bid1_2"
      }],
      "seat": "seat1"
    },
    {
      "bid": [{
        "reason": {
          "description": "below_floor",
          "id": 2
        },
        "impid": "1",
        "price": 0.04,
        "adid": "3141592",
        "id": "bid2_1"
      }],
      "seat": "seat2"
    }
  ],
  "bidfloor": 0.1,
  "http_status": 200,
  "bidid": "bidid2",
  "id": "2fa74f29­641e­44db­8893­1ea86c87ced6"
}

Network Loss (out bid by ad network)

{
  "latency": 0.139,
  "seatbid": [{
    "bid": [{
      "reason": {
        "description": "outbid",
        "value": "network",
        "id": 1
      },
      "impid": "1",
      "price": 0.51,
      "adid": "3141592",
      "id": "bid1_1"
    }],
    "seat": "seat1"
  }],
  "bidfloor": 0.1,
  "http_status": 200,
  "bidid": "bidid2",
  "id": "2fa74f29­641e­44db­8893­1ea86c87ced6"
}

FAQ

1. Why do we have an option for wins with this service?

Our imptracker notification occurs at the time of charging a DSP for impressions served. This new win notification will notify if the bid is the highest paying demand source for this impression at the time of the auction completing ­ i.e. if the DSP has the highest bid price from all DSPs, and also if they beat out the network proxies.

2. Does a “win” account for networks?

Yes, “wins” with this service mean the DSP’s bid represents the highest priced demand source for this impression and it will be sent to the user”s device.

3. I noticed some auction_ids are appearing for both losses and wins. Why is that?

You may see some loss notifications that end up becoming win notifications at a later point. The reason for this is due to Publishers having their Marketplace line item compete with a network. For example, you may lose to a network and if (for a variety of reasons) that network cannot fulfill the impression request, you may then win and be able to serve your impression.

Please keep in mind that you may see multiple loss notifications with the same ID. The would be due to Publisher waterfall setups. Taking the previous example into consideration, there are possibilities where you lose to a network, that network cannot fulfill, you lose to a second network, so on and so forth.

4. Should I still use the impression tracker (imptrackers) if I integrate this service?

Yes, the impression tracker is the MoPub billing notification for an impression event. A “win” here represents a server­side win ­meaning that your bid represented the highest paying demand source for this impression, but it doesn”t guarantee that it is shown to the user for a revenue event.

Note: MoPub uses client side impression tracking (imptrackers) per IAB and MRC best practice for mobile impression counting.

5. How does this work if the bidder returns multiple seatbid or bid objects in their bid response?

• All lost bids are grouped into a single auction notification response, each bid will have its own reason
• If one bid is the winner from the auction, that individual bid will be sent in a separate auction notification and this bidder will receive a max 2 notifications.
• Why can the “reason” object be located at different levels of the response hierarchy?
  • Its dependent on where the error occurs ­ see the reason code table for details
• What is the maximum QPS you will send through with auction notifies?
  • It is dependent on the rate of bids submitted. It will max out at 2x the rate of bids you submit (if you always submit multiple bids in a bid response), otherwise, the max QPS is equal to the rate of bids your bidder submits.
• When will you send an auction notification? Will it be for every auction request I receive?
  • We only send auction notifications if there is a bid. I.e., all “NoBid” situations will be left out. Examples of NoBid situations are 204 response, or a 200 empty response.
  • Sending back a 200 response with a $0 bid will trigger a notification
• How do you send auction notifies to our endpoint?
  • HTTP method: POST
  • HTTP content-type: application/json

Questions?

For more information, or questions, please email your Account Management team or mopubDSPsuccess@twitter.com.

Please contact your account team if you would like info/graphs on the rate of bids for your bidder to help guide this decision.