Multi-Winner Placements

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.

{
  "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.

{
  "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": "<a href=\"http://e-1234.adzerk.net/r?e=eyJhdiI6ODU2NzEsImF0Ij..." rel=\"nofollow\" target=\"_blank\" title=\"\"><img src=\"https://s.zkcdn.net/Advertisers/985a089f8e384f338fc4d41100037f22.jpg\" title=\"\" alt=\"\" border=\"0\" width=\"300\" height=\"250\"></a>",
            "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

🚧
Note that ads in passback priorities are not eligible for multi-winner placements and will never be selected in a multi-winner decision.

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.
Ads in flights in passback priorities 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.

See the example impression object to the right.

{
  "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.