A multi-winner placement returns multiple selections inside a single placement object in the Decision API. This is useful in several situations: - If an auction takes place downstream of Kevel, multiple winning bids are available for the auction to select from. - If response time is critical, multi-winners in a single placement are faster than requesting multiple placements. - If the exact number of placements is not known at response time, multiple winners gives the calling application a range of ads to choose from. Multiple winning placements are available for ads in both auction and lottery priorities. > 🚧 > Multi-winner placements can be requested only via the Decision API. Ados.js and other delivery methods are currently not supported. ## Request To request multiple winners, add an integer `count` property to the placement object. This requests the _maximum_ number of winners (selections) that can be included in the placement. > 👍 > Note that setting a `count` sets the upper limit for the ads in the placement. It does NOT guarantee that this number of ads will be returned. The `count` must be an integer between 1 and 20. The **maximum number of ads returned per placement is 20.** See the example request to the right. ### Multi-winner placement object ```json { "placements": [ { "divName": "multi-winner", "networkId": 1234, "siteId": 12345, "adTypes": [ 5 ], "count": 2 } ] } ``` ## Response The winning ads will be returned as an array. See the example response to the right. ### Multi-winner response when count=2 ```json { "user": { "key": "abc" }, "decisions": { "multi-winner": [ { "adId": 12345, "creativeId": 12345, "flightId": 12345, "campaignId": 12345, "clickUrl": "https://e-1234.adzerk.net/r?e=eyJhdiI6MTQ4NTY4LCJhdCI...", "impressionUrl": "https://e-1234.adzerk.net/i.gif?e=eyJhdiI6MTQ4NTY4L...", "contents": [ { "type": "raw", "body": "I'm an ad!", "data": { "height": 250, "width": 300 }, "customTemplate": "I'm an ad!" } ], "height": 250, "width": 300, "events": [] }, { "adId": 12346, "creativeId": 12356, "flightId": 12345, "campaignId": 12345, "clickUrl": "https://e-1234.adzerk.net/r?e=eyJhdiI6ODU2NzEsIm...", "impressionUrl": "https://e-1234.adzerk.net/i.gif?e=eyJhdiI6ODU2NzEs...", "contents": [ { "type": "html", "body": "\"\"", "data": { "height": 250, "width": 300, "imageUrl": "https://s.zkcdn.net/Advertisers/985a089f8e384f338fc4d41100037f22.jpg", "title": "", "fileName": "985a089f8e384f338fc4d41100037f22.jpg" }, "template": "image" } ], "height": 250, "width": 300, "events": [] } ] } } ``` ## Ad Serving Behavior In general, a multi-winner placement will return the same ads that are returned from multiple single-winner placements. However there are a few important differences: - Companion ads will **never** be selected. - No ad will be selected multiple times in the same multi-winner placement. This means that if there are 3 eligible ads for a request but a request includes a `count` of 5, only 3 ads will be returned. However, as with single-winner placements, multiple winner placements _can_ return ads from multiple priorities in the response. For instance, if there are 5 requested ads and only 2 in the highest priority are available, the remaining 3 ads will be chosen from the next highest priority. ## Reporting and Data Shipping Impressions in data shipping will contain some information especially useful for understanding multi-winner placements: - `Id`: a unique ID for each impression in the placement - `DecisionId`: a unique ID for the decision, which is the same for every impression in a placement - `DecisionIdx`: the index of the ad in the array of ads returned for the placement -- the first ad returned will have a `DecisionIdx` of 0, the next ad returned will have a `DecisionIdx` of 1, and so on. All impressions from a single multiple-winner request can be tied back to that request via the `DecisionId`, and individual impressions can be identified by their `Id` and/or `DecisionIdx`. ### Multi-winner impression object ```json { "Id": "b83e379c9ea84417ad6b0b3c8a861629", "DecisionId": "fd2339937b1741629da6ad32f8b0e173", "DecisionIdx": 0, "CreatedOn": "/Date(1508880397811)/", "EventCreatedOn": 1508880439150, "ImpressionCreatedOn": 1508880397811, "AdTypeId": 5, "AuctionBids": 1, "BrandId": 12345, "CampaignId": 12345, "Categories": [], "ChannelId": 12345, "CreativeId": 12345, "CreativePassId": 12345, "DeliveryMode": 3, "FirstChannelId": 12345, "ImpressionCount": 1, "IsNoTrack": false, "IsTrackingCookieEvents": false, "IsPublisherPayoutExempt": false, "IsValidUA": true, "Keywords": "", "Location": { "CountryCode": "US", "CountryName": "United States", "Region": "VA", "City": "Ashburn", "PostalCode": "20149", "Latitude": 39.0481, "Longitude": -77.4728, "MetroCode": 511, "DmaCode": 511 }, "MatchingKeywords": [], "NetworkId": 1234, "PassId": 123456, "PhantomCreativePassId": 0, "PlacementName": "multi-winner-placement", "PhantomPassId": 0, "PriorityId": 12345, "Price": "0", "RateType": 1, "RelevancyScore": 500, "Revenue": 0, "RemoteIP": "1.2.3.4", "ServedBy": "i-064b598fa470a8780", "ServedByPid": 1234, "ServedByAsg": "bifrost-mock-data", "SiteId": 12345, "User": { "Key": "abc", "IsNew": false }, "UserAgent": "RonBot/7.43.0", "UserKey": "abc", "ZoneId": 0 } ``` > 📘 > Each multi-winner ad request counts as only a single Ad Decision Request for reporting & billing purposes. > 👍 > If ads from a second-price auction are returned in a multi-winner placement, second-pricing will apply to the winners.