Marketplace Auction Notifications

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 an RTB 2.3 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.

The fields in bold denote those specific to auction notifications.

bidid       Bid response ID to assist tracking for bidders. This value is chosen by the bidder for cross­-reference. Optional for bidder and only shown if bidder passes in response.
id       Top­-level ID of the bid request that this is a response for.
http_status       http status code from the bid response
bidfloor       Not typically passed by a bidder in the bid response added here for trouble shooting
latency       latency of the bid response ­in seconds (e.g., .139 = 139ms)
seatbid []       An array of all seats for this bidder endpoint. There must be at least one seat present
  seat     A unique identifier for this seat. This should be logged and will primarily be used for billing purposes. Optional for bidder to support? required if using multiple seats
  bid []     Enables consideration for all elements in the array, rather than just the first. The highest bid that is not excluded by blocklist violations and other validity checks will be submitted as the winning bid from this seat.
    id   Used only to identify which among many bids in a seatbid was chosen? ID chosen by the bidder? should be logged.
    adid   ID that references the ad to be served if the bid wins. Logged if passed.
    impid   Matches the impression object that was sent in the bid request that this bid corresponds to. This must match the value in imp.id from the bid request.
    price   The bid price, in CPM units. If the bid price is above $1000, the bid will not be considered for the auction. This is to protect bids from clearing at higher than market price CPMs.
    reason   Note that reason object can be located at different levels of heirarchy
      description string describing the reason for the notification
      value optional field if theres additional detail on the reason to supply
      id reason id from reason code mapping table

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

ID Description Value Reason Location
0 win   Bid is highest demand source for this impression bid object
1 outbid bidder,network,line item   bid object
2 below price floor     bid object
3 invalid file extension   filtered due to containing of swf or flv in markup bid object
4 missing values include missing value if applicable   can be a root,bid,or seatbid
5 blocked adomain return adomain violates adomain blocks bid object
6 blocked creative   creative ID is blocked due to violation or low TDR, or blocked by publisher bid object
7 unparseable   e.g., not valid JSON root
8 timeout     root
9 non http ok   503 on bid request (or some other error like 400,500) We expect responses to either be HTTP 200 or 204. Any other response will not be processed. root
10 wrong format   Bid response is not video on a video only request or bid response is not recognized as native on a native request bid object
12 invalid pmp deal ID   Bid response does not contain the correct PMP deal ID bid object
13 invalid pmp domain   Bid response does not contain a publisher whitelisted adomain bid object
14 invalid asset   Only sent for the Native Ad format. Assets used in Bid Response do not conform to OpenRTB specs bid object
15 blocked category   violates category blocks bid object
16 auction id mismatch   Bid response contains auction id that does not match auction id found in Bid Request bid object
17 unexpected whitespace   Bid response contains unexpected whitespace (extra whitespace where it should not be) bid object
18 invalid adomain format   Bid response contains adomain that is not a proper string bid object
20 blocked creative attribute   violates creative blocks bid object
21 invalid audience segment deal id   Bid response contains an audience segment deal id that is not valid bid object
22 insecure creative url   Bid response contains a creative url that is not secure bid object

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 2.3 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 (2.3 imptracker) 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 (2.3 imptracker) 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 dspsupport@mopub.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.

Last updated November 15, 2018

TWITTER, MOPUB, and the Bird logo are trademarks of Twitter, Inc. or its affiliates. All third party logos and trademarks included are the property of their respective owners.

© 2018 MoPub Inc.