+
+# 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`
+
+ 
+
++ 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'**
+
+ 
+
++ 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)
+
+
+
+
+
+[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
new file mode 100644
index 0000000000..206fb0747b
Binary files /dev/null and b/assets/images/ad-ops/multi-format/hb_format_native.png differ
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
new file mode 100644
index 0000000000..3b7f43dd2b
Binary files /dev/null and b/assets/images/ad-ops/multi-format/hb_format_video_banner.png differ
diff --git a/dev-docs/bidder-adaptor.md b/dev-docs/bidder-adaptor.md
index b74ca59c86..501c82bd8f 100644
--- 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
index ca970d401c..ba73d0f3ea 100644
--- 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) |
diff --git a/dev-docs/examples/multi-format-example.md b/dev-docs/examples/multi-format-example.md
new file mode 100644
index 0000000000..57c4beb6b0
--- /dev/null
+++ 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
+
+# Show Multi-Format Ads with Prebid.js
+{: .no_toc }
+
+This page has instructions for showing multi-format ads using Prebid.js.
+
+An ad unit is said to be multi-format if it supports at least two of the following media types:
+
++ Banner
++ Native
++ Video
+
+Once declared, any bidder that supports at least one of the media types can participate in the auction for that ad unit.
+
+{: .alert.alert-info :}
+For ad ops setup instructions, see [Setting up Prebid Multi-Format in DFP]({{site.baseurl}}/adops/setting-up-prebid-multi-format-in-dfp.html).
+
+* TOC
+{:toc}
+
+## How Multi-Format Ads Work
+
+Prebid multi-format ad units allow direct competition between banner, native, and/or video bids.
+
+At a high level, Prebid.js supports multi-format ads as follows:
+
+1. An ad unit may define a [`mediaTypes`]({{site.baseurl}}/dev-docs/publisher-api-reference.html#addAdUnits-MediaTypes) object to specify one or more supported formats and their respective properties.
+2. Each bidder specified on a given ad unit will be eligible to bid if the bidder supports at least one of the media types specified via `adUnit.mediaTypes`.
+3. Prebid.js sends bid requests to each eligible bidder.
+
+The following key is added to your ad server targeting, and set to the value of the bid response's `mediaType` property.
+
++ `hb_format`
+
+The ad ops team will reference this key in the ad server to set targeting. For ad ops setup instructions, see [Setting up Prebid Multi-Format in DFP]({{site.baseurl}}/adops/setting-up-prebid-multi-format-in-dfp.html).
+
+## Prerequisites
+
+Keep the following prerequisites in mind during the implementation:
+
++ Make sure to work with bidders that support demand for the media types you want, particularly native and video. To see which bidders have native and/or video demand, see [Bidders with Video and Native Demand]({{site.baseurl}}/dev-docs/bidders.html#bidders-with-video-and-native-demand).
+
+## Implementation
+
+This section describes the implementation using code samples, but ignores some of the details that are common to all Prebid.js setups.
+
+### 1. Add multi-format ad units
+
+The ad unit below supports the banner, native, and video media types.
+
+```javascript
+
+ pbjs.addAdUnits({
+ code: 'div-banner-outstream-native',
+ mediaTypes: {
+ banner: {
+ sizes: [
+ [300, 250],
+ [300, 50]
+ ]
+ },
+ native: {
+ image: {
+ sizes: [
+ [300, 250],
+ [300, 50]
+ ]
+ }
+ },
+ video: {
+ context: 'outstream',
+ playerSize: [640, 480]
+ },
+ },
+ bids: [
+
+ {
+ bidder: 'bannerBidder',
+ params: {
+ placementId: '481'
+ }
+ },
+
+ {
+ bidder: 'nativeBidder',
+ params: {
+ titleAsset: '516'
+ }
+ },
+
+ {
+ bidder: 'videoBidder',
+ params: {
+ vidId: '234'
+ }
+ },
+
+ ]
+ });
+```
+
+### 2. Add your tag to the page body
+
+Add a tag like the following to your page. Depending on who wins the auction, a banner, outstream, or native ad should serve.
+
+```html
+
+```
+
+## Working Examples
+
++ [Multi-Format Example]({{site.baseurl}}/examples/multi_format_example.html)
+
+## Related Topics
+
++ [Setting up Prebid Multi-Format in DFP]({{site.baseurl}}/adops/setting-up-prebid-multi-format-in-dfp.html)
+
+