Add multiformat docs: developers, ad ops, example code

_config.yml

@@ -69,6 +69,9 @@ nav_sections:
   - top_nav: dev_docs
     code: quick-start
     name: DEVELOPER QUICK START
+  - top_nav: dev_docs
+    code: prebid-multi-format
+    name: PREBID MULTI-FORMAT (ALPHA)
   - top_nav: dev_docs
     code: prebid-video
     name: PREBID VIDEO (BETA)

adops/setting-up-prebid-multi-format-in-dfp.md

@@ -0,0 +1,85 @@
+---
+layout: page
+title: Setting up Prebid Multi-Format in DFP
+head_title: Setting up Prebid Multi-Format in DFP
+description: Setting up Prebid Multi-Format in DFP
+pid: 3
+hide: false
+top_nav_section: adops
+nav_section: tutorials
+---
+
+<div class="bs-docs-section" markdown="1">
+
+# Setting up Prebid Multi-Format in DFP
+{: .no_toc}
+
+This page shows how to set up your ad server so that you can serve multi-format ads.
+
+Multi-Format ads allow you to declare multiple media types on a single ad unit.  For example, you can set up one ad on the page that could show a banner, native, or outstream video ad, depending on which had the highest bid.
+
+{: .alert.alert-info :}
+For instructions on how to set up multi-format ads from the engineering side, see [Show Multi-Format Ads with Prebid.js]({{site.baseurl}}/dev-docs/show-multi-format-ads.html).
+
+* TOC
+{: toc }
+
+## Step 1. Add an Ad Unit
+
+In DFP, [create an ad unit](https://support.google.com/dfp_premium/answer/177203?hl=en).
+
+Decide what combination of formats will be permitted on the ad unit.  This will determine what sizes you allow to serve.  The ad unit's sizes must be configured properly to support the combination of formats that will be permitted.
+
+If your ad unit will support native ads, you may want to create a custom **Prebid Native Format** and at least one **Prebid Native Style**.  Examples of each are given in [Setting up Prebid Native in DFP][nativeAdSetup].
+
+## Step 2. Add an Order
+
+In DFP, create a new order.  This order will be associated with the multiple line items needed to run multi-format auctions.
+
+## Step 3. Add Line Items and Creatives for each Media Type
+
+Multi-format ad units which support native require at least two distinct sets of line items and creatives:
+
++ One for [banners and/or outstream video][bannerAdSetup].  Banners and outstream videos will serve into a DFP banner creative.
+
++ One for [native][nativeAdSetup].  Native ads will serve into a native creative with native format and styles.
+
+### Banner/Outstream
+
+Follow the instructions for creating line items and creatives in [Send all bids to the ad server][bannerAdSetup], with the following changes:
+
++ Add key-value targeting for **'hb_format' is ('banner' OR 'video')**
+    + This will ensure that the appropriate ad server line item is activated for banner / outstream bids
+    + For bidder-specific line items, specify `hb_format_{BIDDER_CODE}`, e.g., `hb_format_appnexus`
+
+    ![Set hb_format to 'banner,video']({{site.baseurl}}/assets/images/ad-ops/multi-format/hb_format_video_banner.png)
+
++ Make sure that you're targeting the right sizes for both banner ads and any outstream ads you want to serve in this slot, e.g.,
+    + 1x1 for outstream (or whatever size you pass into DFP as your outstream impression)
+    + whatever banner sizes are valid for your site / use case
+
+### Native
+
+Follow the instructions for creating line items, creatives, custom native formats, and native styles in [Show Native Ads][nativeAdSetup], with the following changes:
+
++ Add key-value targeting for **'hb_format' is 'native'**
+
+    ![Set 'hb_format' to 'native']({{site.baseurl}}/assets/images/ad-ops/multi-format/hb_format_native.png)
+
++ Make sure you're targeting the right sizes for the native ads you want to serve:
+    + Fixed-size native, where you specify one or more absolute sizes
+    + Fluid, which expands to fit whatever space it's put in
+    + For more information on fluid vs. fixed, see [the DFP docs](https://support.google.com/dfp_premium/answer/6366914?hl=en)
+
+## Related Topics
+
++ [Show Multi-Format Ads with Prebid.js]({{site.baseurl}}/dev-docs/show-multi-format-ads.html) (Engineering setup)
++ [Multi-Format Example]({{site.baseurl}}/dev-docs/examples/multi-format-example.html) (Example code)
+
+</div>
+
+<!-- Reference Links -->
+
+[bannerAdSetup]: {{site.baseurl}}/adops/send-all-bids-adops.html
+[nativeAdSetup]: {{site.baseurl}}/adops/setting-up-prebid-native-in-dfp.html
+[createCustomNativeFormat]: {{site.baseurl}}/adops/setting-up-prebid-native-in-dfp.html#create-a-custom-native-ad-format

dev-docs/bidder-adaptor.md

@@ -96,7 +96,7 @@ Module that connects to Example's demand sources
             code: 'test-div',
             mediaTypes: {
                 banner: {
-                    sizes: [[300, 50]],   // a mobile size
+                    sizes: [[320, 50]],   // a mobile size
                 }
             },
             bids: [
@@ -223,9 +223,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:

dev-docs/docs-by-format.md

@@ -20,18 +20,20 @@ For ad ops and other ad server-related information, see [our Ad Ops documentatio
 {:toc}
 
 {: .table .table-bordered .table-striped }
-| Format              | Page                                                                                                                             |
-|---------------------+----------------------------------------------------------------------------------------------------------------------------------|
-| *AMP*               | [How Prebid on AMP Works]({{site.github.url}}/dev-docs/how-prebid-on-amp-works.html)                                             |
-|                     | [Show Prebid Ads on AMP Pages (Alpha)]({{site.github.url}}/dev-docs/show-prebid-ads-on-amp-pages.html)                           |
-| *Video* (instream)  | [Show Video Ads with a DFP Video Tag]({{site.github.url}}/dev-docs/show-video-with-a-dfp-video-tag.html) (With lots of examples) |
-|                     | [How to Add a New Video Bidder Adapter]({{site.github.url}}/dev-docs/how-to-add-a-new-video-bidder-adaptor.html)                 |
-| *Video* (outstream) | [Show Outstream Video Ads]({{site.github.url}}/dev-docs/show-outstream-video-ads.html)                                           |
-|                     | [Outstream Video Example]({{site.github.url}}/dev-docs/examples/outstream-video-example.html)                                    |
-| *Standard Display*  | [Basic Prebid.js Example]({{site.github.url}}/dev-docs/examples/basic-example.html)                                              |
-|                     | [Getting Started]({{site.github.url}}/dev-docs/getting-started.html)                                                             |
-|                     | [Ad Unit Refresh / Infinite Scroll Example]({{site.github.url}}/dev-docs/examples/adunit-refresh.html)                           |
-| *Native*            | [Show Native Ads with Prebid.js]({{site.github.url}}/dev-docs/show-native-ads.html) (Engineering setup)                          |
-|                     | [Setting up Prebid Native in DFP]({{site.github.url}}/adops/setting-up-prebid-native-in-dfp.html) (Ad Ops setup)                 |
+| Format                                                              | Page                                                                                                                             |
+|---------------------------------------------------------------------+----------------------------------------------------------------------------------------------------------------------------------|
+| *Multi-Format (banner, native, outstream video all in one ad unit)* | [Show Multi-Format Ads with Prebid.js]({{site.baseurl}}/dev-docs/show-multi-format-ads.html) (Engineering setup)                  |
+|                                                                     | [Setting up Prebid Multi-Format in DFP]({{site.baseurl}}/adops/setting-up-prebid-multi-format-in-dfp.html) (Ad ops setup)         |
+| *AMP*                                                               | [How Prebid on AMP Works]({{site.github.url}}/dev-docs/how-prebid-on-amp-works.html)                                             |
+|                                                                     | [Show Prebid Ads on AMP Pages (Alpha)]({{site.github.url}}/dev-docs/show-prebid-ads-on-amp-pages.html)                           |
+| *Video* (instream)                                                  | [Show Video Ads with a DFP Video Tag]({{site.github.url}}/dev-docs/show-video-with-a-dfp-video-tag.html) (With lots of examples) |
+|                                                                     | [How to Add a New Video Bidder Adapter]({{site.github.url}}/dev-docs/how-to-add-a-new-video-bidder-adaptor.html)                 |
+| *Video* (outstream)                                                 | [Show Outstream Video Ads]({{site.github.url}}/dev-docs/show-outstream-video-ads.html)                                           |
+|                                                                     | [Outstream Video Example]({{site.github.url}}/dev-docs/examples/outstream-video-example.html)                                    |
+| *Standard Display*                                                  | [Basic Prebid.js Example]({{site.github.url}}/dev-docs/examples/basic-example.html)                                              |
+|                                                                     | [Getting Started]({{site.github.url}}/dev-docs/getting-started.html)                                                             |
+|                                                                     | [Ad Unit Refresh / Infinite Scroll Example]({{site.github.url}}/dev-docs/examples/adunit-refresh.html)                           |
+| *Native*                                                            | [Show Native Ads with Prebid.js]({{site.github.url}}/dev-docs/show-native-ads.html) (Engineering setup)                          |
+|                                                                     | [Setting up Prebid Native in DFP]({{site.github.url}}/adops/setting-up-prebid-native-in-dfp.html) (Ad Ops setup)                 |
 
 </div>

dev-docs/examples/multi-format-example.md

@@ -0,0 +1,20 @@
+---
+layout: example
+title: Prebid.js Multi-Format Example
+description: Prebid.js Multi-Format Example
+top_nav_section: dev_docs
+nav_section: quick-start
+hide: true
+about:
+- Multi-Format ads allow you to declare multiple media types on a single ad unit
+- Set up one ad unit that could show a banner, native, or outstream video ad
+- Any bidder that supports at least one of the listed media types can participate in the auction for that ad unit
+- For engineering setup instructions, see <a href="/dev-docs/show-multi-format-ads.html">Show Multi-Format Ads</a>
+- For ad ops setup instructions, see <a href="/adops/setting-up-prebid-multi-format-in-dfp.html">Setting up Prebid Multi-Format in DFP</a>
+- <em>Note</em> - Outstream ads only work sporadically in the embedded JSFiddle below; try the Prebid.org-hosted <a href="/examples/multi_format_example.html">Multi-Format Example</a>
+jsfiddle_link: jsfiddle.net/prebid/mg81j0rw/12/embedded/html,result
+code_lines: 110
+code_height: 2389
+use_old_example_style: false
+pid: 11
+---

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 were removed in version 1.0.  For more information about the changes, see [the release announcement]({{site.baseurl}}/blog/prebid-1-is-released).  
 After a transition period, documentation for these methods will be removed from Prebid.org (likely early 2018).
 
 <a name="module_pbjs"></a>
@@ -605,7 +605,8 @@ 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)
++ [Multi-format](#adUnit-multi-format)
+
 
 <a name="adUnit-native">
 
@@ -727,7 +728,7 @@ pbjs.addAdUnits({
 })
 ```
 
-<a name="adUnit-multiformat">
+<a name="adUnit-multi-format">
 
 ##### Multi-format
 
@@ -1119,7 +1120,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.
@@ -1307,9 +1308,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" />
@@ -1435,7 +1436,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.
@@ -1818,7 +1819,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