Add multiformat docs: developers, ad ops, example code (#561)

* WIP multiformat docs * Flesh out prerequisites/implementation of dev doc * Add multi-format docs to 'Docs by Format' * Add a quick example of *why* to do this * Outline steps on ad ops page * Clarify multi-format on 'Docs by format' page * Various dev doc fixups * Update JSFiddle, overview bullet points in example * Update multiformat fiddle * Key is now called `hb_format` * s/multi-format/multiformat/ * Use 'appnexus' bidder and Prebid.js v1 * s/multi-format/multiformat/ * Be clear that it's *outstream* video * Use title case * Update multiformat example link * Fill in multiformat ad ops instructions Because these are basically the same as the banner/native instructions, I've filled them in as the "diffs" between our existing, published, vetted instructions. * Add native aspect ratio info to AN adapter docs (#543) * Add native aspect ratios to AppNexus adapter docs Also did some general cleanup and formatting while I was in there. * Update field defs a bit; add OpenRTB native link * Remove OpenRTB note based on feedback * Add banner, video, and native sections * WIP native updates across several pages * Tweak language in AN bidder doc links * Edit down to a single native example; s/Ast//g * Update native example code; s/Ast//g * Show `mediaTypes.native.image.sizes` in examples In addition to updating the basic examples to use sizes for images and icons, we add a section to both the API reference and the 'Show Native Ads' page that lists both ways to define sizes for image-like assets. Since the content is the same, it's in a shared file sourced using the Liquid `include` keyword. * Fix code formatting issue with included file * `adUnit.sizes` is ignored on native ad units * Remove `adUnit.sizes` since banner sizes are used * Remove redundant `adUnit.sizes` from native ad * Use correct syntax for native "image-type" ad * Add multiformat ad unit information (#541) * Add multiformat ad unit information * Update default targeting keys * Update based on review feedback * Change key to hb_format * Add note about including banner media type if supported * update tag samples with multiformat syntax (#528) * update tag samples with multiformat syntax * reverting part of change on show-native-ads.md * s/multiformat/multi-format/g * We don't need an order per demand partner * Remove ambiguous comment on fluid vs. fixed native * Update multi-format language in dev setup intro * Update multi-format description based on feedback * Update 'How it works' based on feedback * Update ad unit language based on feedback * Fix Prebid.org-hosted multiformat example Somehow a native example was erroneously added -- probably as a placeholder. It has been replaced with a slightly modified version [*] of the multi-format example kindly provided by @matthewlane. [*] It was modified to (1) use Prebid.js v1.2 from the CDN and (2) to use the 'appnexus' rather than the old AST adapter * Update JSFiddle in multiformat example To address the following points: 1. Removing mention of the internal dev URL as mentioned by Jacobson 2. Making the code the same as that of prebid.org/examples/multi_format_example.html * Add ad unit creation step with sizing/native info * Clarify line item setup language * Update k-v targeting instructions per feedback - Use slightly different language/notation - Add screenshots * Check in screenshots of multi-format ad ops setup * Update native format language per feedback * Clarify that it's banner and/or outstream * Note bidder-specific line item targeting keys * Update targeting description per feedback * Update native size note, per feedback * Fix mobile size per feedback * Hide multi-format example from site's left nav * Belatedly add link to the 1.0 release announcement * Fix typo * Use Prebid.org-hosted multi-format example (Also, add it to the `/examples` index page.) * s/div-banner-outstream/div-banner-native/g * Add a third example: 'banner-outstream' * Update examples to set `cache.url` to `false` I'm told this is connected somehow to the following issue, but ¯\_(ツ)_/¯ prebid/Prebid.js#1976 * Update placement IDs in Prebid.org-hosted example In order for outstream to work, we need a placement configured to work with VAST 3.0 since that is what the test outstream creative requires. * Update JSFiddle to use updated placement IDs * Get banner/outstream examples working: use 300x250 Also, added a note to the JSFiddle multi-format example page that the Fiddle works sporadically for outstream, so check out the Prebid.org-hosted example (which works closer to 100% of the time) * Fix broken formatting on JSFiddle example page
prebid · Jan 29, 2018 · 9a54080 · 9a54080
1 parent 95e1db0
commit 9a54080
Show file tree

Hide file tree

Showing 11 changed files with 487 additions and 26 deletions.
diff --git a/_config.yml b/_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)

diff --git a/adops/setting-up-prebid-multi-format-in-dfp.md b/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
diff --git a/assets/images/ad-ops/multi-format/hb_format_native.png b/assets/images/ad-ops/multi-format/hb_format_native.png
diff --git a/assets/images/ad-ops/multi-format/hb_format_video_banner.png b/assets/images/ad-ops/multi-format/hb_format_video_banner.png
diff --git a/dev-docs/bidder-adaptor.md b/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:

diff --git a/dev-docs/docs-by-format.md b/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>
diff --git a/dev-docs/examples/multi-format-example.md b/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
+---
diff --git a/dev-docs/publisher-api-reference.md b/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