Marketplace Auction Notifications

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

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 purposes:

1. Rapidly identifying and resolving technical issues.
2. Identifying trends in bidding behavior.
3. Understanding 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 against the 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, 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 will be present at different levels of the bid response hierarchy, based on the specific reason. See the following 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 (Outbid 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

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 win notification will notify if the bid is the highest paying demand source for this impression at the time of the auction completion; that is, if the DSP has the highest bid price of all DSPs, and also if they beat the network proxies.

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.

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

Should I still use the impression tracker (1imptrackers1) 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.

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 maximum of two notifications.

Why can the “reason” object be located at different levels of the response hierarchy?

It is 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

Additional Questions

For more information or questions, please email your Account Management team or visit our Support Center.

Please contact your account team for information or graphs on the rate of bids for your bidder to help guide this decision.