Win Notification
- MediaMath delivers Win Notifications to the configured Custom Bid Router endpoints over HTTPS.
- The content type for the body of the request is set when the endpoint is configured. Therefore JSON (Content-Type: application/json) and Binary protobuf (Content-Type: application/protobuf) are supported.
- The Win Notification will be forwarded to the Custom Bid Router endpoints within seconds.
- Custom Bid Router does not implement a retry logic in case the Win Notification does not deliver successfully.
- Logging to S3 is currently not supported.
- Sample Rate is set to 100% (the full stream), but can be adjusted.
Win Notification Protobuf definition
The Win Notification Protobuf definition can be found here: https://github.com/MediaMath/bid-valuator-endpoint-java/blob/master/src/main/proto/mediamath/winnotice/winnotice.proto
Setup Win Notification Endpoint
To setup a Win Notification Endpoint, follow the Win Notification Endpoint documentation
For every Win Notification Endpoint added, the endpoint_type field needs to be set to "win".
Win Notification Sample Rate
The sample rate of an endpoint can be adjusted to selectively forward only a percentage of the Win Notifications. The sample rate can be adjusted collectively for all endpoints of an executor.
curl -X PATCH \
https://api.byoa.mediamath.com/custombidrouter/{org_id}/executors/4 \
-d '{"sample_rate": 75,
"endpoint_type": "win"}' \
-H 'authorization: Bearer <oauth_access_token>'Win Notification Example Request and Response
Request
Request Header
The X-Timeout header is set to 400ms. Which means that Custom Bid Router sets a deadline of 400ms for the win notification response to arrive. If it takes longer than 400ms, an error will be logged on the Grafana Dashboard.
Content-Type: application/protobuf
X-Timeout: 400Request Body Example (protobuf decoded)
| Field | Description | Example |
|---|---|---|
| ExchangeAuctionID | Exchange Auction ID we receive | 8118261190986958665 |
| AuctionID | MM Auction ID unique to MM | 3023274093253060000 |
| BidPriceCpm | Bid price at CPM level in USD | 0.46974 |
| ClearPriceCpm | Amount SSP tells us the CPM cost once we have won auction | 0.469363 |
| TotalSpend | Total Spend CPM including all tracked fees | 0.899475 |
| MmUuid | Identifier for the user who received the ad | 93e75a86-036a-4000-9679-000000000000 |
| AdvertiserID | ID of the Advertiser in MediaMath for the campaign that won the impression | 123456 |
| CampaignID | Campaign ID for the impression win event | 123456 |
| StrategyID | ID for the impression win event at the granular strategy level | 123456 |
| CreativeID | Unique identifier that identifies the creative used in displaying the impression | 123456 |
| BidTimestamp | Converted to unix timestamp (note: will be at seconds and not milliseconds). In UTC time. | 2020-05-26 13:27:23 |
Response
The Win Notification Response is expected to return the following Response back to Custom Bid Router.
Response Header
HTTP/1.1 200 OKGrafana Stats
- Win Notifications by Datacenter: shows the attempt Win Notification Requests
- Win Notification Responses by Datacenter: shows successful Win Notification Responses
- Win Notification Response Code Distribution: shows the Win Notification Response Code Distribution (expected 200)
- Win Notification Response Latency Distribution: shows the Win Notification Response Latency (max allowed 40ms)