Add multiformat ad unit information

dev-docs/bidder-adaptor.md

@@ -208,9 +208,9 @@ Sample array entry for `validBidRequests[]`:
 {% endhighlight %}
 
 {: .alert.alert-success :}
-There are several IDs present in the bidRequest object:  
-- **Bid ID** is unique across ad units and bidders.  
-- **Auction ID** is unique per call to `requestBids()`, but is the same across ad units.  
+There are several IDs present in the bidRequest object:
+- **Bid ID** is unique across ad units and bidders.
+- **Auction ID** is unique per call to `requestBids()`, but is the same across ad units.
 - **Transaction ID** is unique for each ad unit with a call to `requestBids`, but same across bidders. This is the ID that DSPs need to recognize the same impression coming in from different supply sources.
 
 The ServerRequest objects returned from your adapter have this structure:
@@ -336,6 +336,9 @@ export const spec = {
 
 {% endhighlight %}
 
+{: .alert.alert-info :}
+If your adapter supports banner and video media types, make sure to include `'banner'` in the `supportedMediaTypes` array as well
+
 ### Step 2: Accept video parameters and pass them to your server
 
 Video parameters are often passed in from the ad unit in a `video` object.

dev-docs/publisher-api-reference.md

@@ -14,7 +14,7 @@ pid: 10
 This page has documentation for the public API methods of Prebid.js.
 
 {: .alert.alert-danger :}
-Methods marked as deprecated will be removed in version 1.0 (scheduled for release Q4 2017).  
+Methods marked as deprecated will be removed in version 1.0 (scheduled for release Q4 2017).
 After a transition period, documentation for these methods will be removed from Prebid.org (likely early 2018).
 
 <a name="module_pbjs"></a>
@@ -566,7 +566,7 @@ See the table below for the list of properties on the ad unit.  For example ad u
 | `code`       | Required | String                                | Unique identifier that you create and assign to this ad unit.  Used to set query string targeting on the ad. If using GPT, we recommend setting this to slot element ID.          |
 | `sizes`      | Required | Array[Number] or Array[Array[Number]] | All the sizes that this ad unit can accept.  Examples: `[400, 600]`, `[[300, 250], [300, 600]]`.  For 1.0 and later, prefer [`mediaTypes.banner.sizes`](#adUnit-banner).          |
 | `bids`       | Required | Array[Object]                         | Each bid represents a request to a bidder.  For a list of properties, see [Bids](#addAdUnits-Bids) below.                                                                         |
-| `mediaTypes` | Optional | Object                                | Defines the media type of the ad.  For a list of properties, see [Media Types](#addAdUnits-MediaTypes) below.                                                                     |
+| `mediaTypes` | Optional | Object                                | Defines one or multiple media types the ad unit supports.  For a list of properties, see [Media Types](#addAdUnits-MediaTypes) below.                                                                     |
 | `labelAny` | optional  | array<string> | An array of string labels, used for showing responsive ads.  With the `labelAny` operator, just one label has to match for the condition to be true. Works with the `sizeConfig` object passed in to [pbjs.setConfig]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setConfig).  |
 | `labelAll` | optional  | array<string> | An array of string labels, used for showing responsive and conditional ads. With the `labelAll` conditional, every element of the target array must match an element of the label array in order for the condition to be true. Works with the `sizeConfig` object passed in to [pbjs.setConfig]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setConfig).  |
 
@@ -594,9 +594,9 @@ See the table below for the list of properties in the `mediaTypes` object of the
 {: .table .table-bordered .table-striped }
 | Name     | Scope                                                        | Type   | Description                                                                                                        |
 |----------+--------------------------------------------------------------+--------+--------------------------------------------------------------------------------------------------------------------|
-| `native` | Required, unless either of the other properties are present. | Object | Defines properties of a native ad.  For an example native ad unit, see [the native example below](#adUnit-native). |
-| `video`  | Required, unless either of the other properties are present. | Object | Defines properties of a video ad.  For examples, see [the video examples below](#adUnit-video).                    |
-| `banner` | Required, unless either of the other properties are present. | Object | Defines properties of a banner ad.  For examples, see [the banner example below](#adUnit-banner).                  |
+| `banner` | optional. If no other properties are specified, this is the default | Object | Defines properties of a banner ad.  For examples, see [the banner example below](#adUnit-banner).                  |
+| `native` | optional | Object | Defines properties of a native ad.  For an example native ad unit, see [the native example below](#adUnit-native). |
+| `video`  | optional | Object | Defines properties of a video ad.  For examples, see [the video examples below](#adUnit-video).                    |
 
 <a name="addAdUnits-Examples">
 
@@ -605,6 +605,7 @@ See the table below for the list of properties in the `mediaTypes` object of the
 + [Native](#adUnit-native)
 + [Video](#adUnit-video)
 + [Banner](#adUnit-banner)
++ [Multi-format](#adUnit-multiformat)
 
 <a name="adUnit-native">
 
@@ -724,6 +725,72 @@ pbjs.addAdUnits({
 })
 ```
 
+<a name="adUnit-multiformat">
+
+##### Multi-format
+
+Multiple media formats may be declared on a single ad unit, allowing any bidder that supports at least one of those media formats to participate in the auction. Any bidder that isn't compatible with the specified `mediaTypes` will be dropped from the ad unit. If `mediaTypes` is not specified on an ad unit, `banner` is the assumed format and any banner bidder is eligible for inclusion.
+
+For examples of a multi-format ad units and behavior, see below.
+
+```javascript
+// each bidder supports at least one of the formats, so all will participate
+pbjs.addAdUnits({
+  code: 'div-banner-outstream-native',
+  mediaTypes: {
+    banner: { sizes: [[300, 250], [300, 600]] },
+    native: {
+        title: {required: true},
+        image: {required: true},
+        body: {required: false},
+    },
+    video: {
+        context: 'outstream',
+        playerSize: [400, 600],
+    },
+  },
+  bids: [
+    {
+      bidder: 'bannerBidder',
+      params: {placementId: '481'}
+    },
+    {
+      bidder: 'nativeBidder',
+      params: {titleAsset: '516'}
+    },
+    {
+      bidder: 'videoBidder',
+      params: {vidId: '234'}
+    },
+  ]
+});
+```
+
+```javascript
+// only nativeBidder and videoBidder will participate
+pbjs.addAdUnits({
+  code: 'div-native-outstream',
+  mediaTypes: {
+    native: { type: 'image' },
+    video: { context: 'outstream', playerSize: [400, 600] },
+  },
+  bids: [
+    {
+      bidder: 'bannerBidder',
+      params: {placementId: '481'}
+    },
+    {
+      bidder: 'nativeBidder',
+      params: {titleAsset: '516'}
+    },
+    {
+      bidder: 'videoBidder',
+      params: {vidId: '234'}
+    },
+  ]
+});
+```
+
 <hr class="full-rule">
 
 <a name="module_pbjs.addBidResponse"></a>
@@ -803,7 +870,7 @@ per adapter as needed. Both scenarios are described below.
 
 **Keyword targeting for all bidders**
 
-The below code snippet is the *default* setting for ad server targeting. For each bidder's bid, Prebid.js will set 5 keys (`hb_bidder`, `hb_adid`, `hb_pb`, `hb_size`, `hb_source`) with their corresponding values. The key value pair targeting is applied to the bid's corresponding ad unit. Your ad ops team will have the ad server's line items target these keys.
+The below code snippet is the *default* setting for ad server targeting. For each bidder's bid, Prebid.js will set 6 keys (`hb_bidder`, `hb_adid`, `hb_pb`, `hb_size`, `hb_source`, `hb_format`) with their corresponding values. The key value pair targeting is applied to the bid's corresponding ad unit. Your ad ops team will have the ad server's line items target these keys.
 
 If you'd like to customize the key value pairs, you can overwrite the settings as the below example shows. *Note* that once you updated the settings, let your ad ops team know about the change, so they can update the line item targeting accordingly. See the [Ad Ops](../adops.html) documentation for more information.
 
@@ -842,6 +909,11 @@ pbjs.bidderSettings = {
             val: function (bidResponse) {
                 return bidResponse.source;
             }
+        }, {
+            key: 'hb_format',
+            val: function (bidResponse) {
+                return bidResponse.mediaType;
+            }
         }]
     }
 }
@@ -1045,7 +1117,7 @@ For an example showing how to use this method, see [Show Video Ads with a DFP Vi
 This method is deprecated as of version 0.27.0 and will be removed in version 1.0 (scheduled for release Q4 2017).  Please use [`setConfig`](#module_pbjs.setConfig) instead.
 
 {: .alert.alert-danger :}
-**BREAKING CHANGE**  
+**BREAKING CHANGE**
 As of version 0.27.0, To encourage fairer auctions, Prebid will randomize the order bidders are called by default. To replicate legacy behavior, call `pbjs.setBidderSequence('fixed')`.
 
 This method shuffles the order in which bidders are called.
@@ -1233,9 +1305,9 @@ pbjs.setConfig({ bidderTimeout: 3000 });
 {% endhighlight %}
 
 {: .alert.alert-warning :}
-**Bid Timeouts and JavaScript Timers**  
-Note that it's possible for the timeout to be triggered later than expected, leading to a bid participating in the auction later than expected.  This is due to how [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) works in JS: it queues the callback in the event loop in an approximate location that *should* execute after this time but *it is not guaranteed*.  
-With a busy page load, bids can be included in the auction even if the time to respond is greater than the timeout set by Prebid.js.  However, we do close the auction immediately if the threshold is greater than 200ms, so you should see a drop off after that period.  
+**Bid Timeouts and JavaScript Timers**
+Note that it's possible for the timeout to be triggered later than expected, leading to a bid participating in the auction later than expected.  This is due to how [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) works in JS: it queues the callback in the event loop in an approximate location that *should* execute after this time but *it is not guaranteed*.
+With a busy page load, bids can be included in the auction even if the time to respond is greater than the timeout set by Prebid.js.  However, we do close the auction immediately if the threshold is greater than 200ms, so you should see a drop off after that period.
 For more information about the asynchronous event loop and `setTimeout`, see [How JavaScript Timers Work](https://johnresig.com/blog/how-javascript-timers-work/).
 
 <a name="setConfig-Send-All-Bids" />
@@ -1361,7 +1433,7 @@ However, there are also good reasons why publishers may want to control the use
 - *Security*: Publishers may want to control which bidders are trusted to inject images and JavaScript into their pages.
 
 {: .alert.alert-info :}
-**User syncing default behavior**  
+**User syncing default behavior**
 If you don't tweak any of the settings described in this section, the default behavior of Prebid.js is to wait 3 seconds after the auction ends, and then allow every adapter to drop up to 5 image-based user syncs.
 
 For more information, see the sections below.
@@ -1740,7 +1812,7 @@ var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?'
 + 'sz=640x480&iu=/19968336/prebid_cache_video_adunit&impl=s&gdfp_req=1'
 + '&env=vp&output=xml_vast2&unviewed_position_start=1&hl=en&url=http://www.example.com'
 + '&cust_params=section%3Dblog%26anotherKey%3DanotherValue';
- 
+
 var videoUrl = pbjs.adServers.dfp.buildVideoUrl({
     adUnit: videoAdUnit,
     url: adserverTag