Interstitial Ads additions

_data/sidebar.yml

@@ -506,6 +506,14 @@
   sectionTitle:
   subgroup: 8
 
+- sbSecId: 1
+  title: Interstitial Ads
+  link: /features/interstitialAds.html
+  isHeader: 0
+  isSectionHeader: 0
+  sectionTitle:
+  subgroup: 8
+
 - sbSecId: 1
   title: Timeouts
   link: /features/timeouts.html

dev-docs/adunit-reference.md

@@ -37,7 +37,7 @@ See the table below for the list of properties on the ad unit.  For example ad u
 | `mediaTypes` | Optional | Object                                | Defines one or more media types that can serve into the ad unit.  For a list of properties, see [`adUnit.mediaTypes`](#adUnit.mediaTypes) below.                                           |
 | `labelAny`   | Optional | Array[String]                         | Used for [conditional ads][conditionalAds].  Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive].                                                                    |
 | `labelAll`   | Optional | Array[String]                         | Used for [conditional ads][conditionalAds]. Works with `sizeConfig` argument to [pbjs.setConfig][configureResponsive].                                                                     |
-| `ortb2Imp`   | Optional | Object                         | Similar to [global first party data configuration](/dev-docs/publisher-api-reference.html#setConfig-fpd), but specific to this adunit. Note that the setConfig data is global to the logical OpenRTB object, but AdUnit-specific data is defined in the scope of a particular imp object. |
+| `ortb2Imp`   | Optional | Object                         | ortb2Imp is used to signal OpenRTB Imp objects at the adUnit grain. Similar to the global ortb2 field used for [global first party data configuration](/dev-docs/publisher-api-reference.html#setConfig-fpd), but specific to this adunit. The ortb2Imp object currently supports [first party data](#adUnit-fpd-example) and the [insterstitial](#adUnit-interstitial-example) signal |
 
 <a name="adUnit.bids" />
 
@@ -547,6 +547,29 @@ Notes:
 - Only contextual data should be added on the AdUnit; user-related data goes in the [global first party data](/dev-docs/publisher-api-reference.html#setConfig-fpd) config.
 - For additional help with analytics and reporting you can use the [Prebid Ad Slot](/features/pbAdSlot.html), a special type of first party data.
 
+<a name="adUnit-interstitial-example">
+
+### Interstitial Ads
+
+Example of an adunit-specific interstitial signal:
+
+{% highlight js %}
+pbjs.addAdUnits({
+    code: "test-div",
+    mediaTypes: {
+        banner: {
+            sizes: [[300,250]]
+        }
+    },
+    ortb2Imp: {
+    	instl:1
+    },
+    ...
+});
+{% endhighlight %}
+
+For more information on Interstitial ads, reference the [Interstitial feature page](/dev-docs/InterstitialAds.html).
+
 ## Related Topics
 
 + [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html)

dev-docs/bidders/rubicon.md

@@ -31,7 +31,6 @@ For both Prebid.js and Prebid Server, the Rubicon Project adapter requires setup
 | `accountId`    | required           | The publisher account ID                                                                                                    | `4934`                                                                            | `integer`         |
 | `siteId`       | required           | The site ID                                                                                                                 | `13945`                                                                           | `integer`         |
 | `zoneId`       | required           | The zone ID                                                                                                                 | `23948`                                                                           | `integer`         |
-| `sizes`        | optional           | Array of Rubicon Project size IDs. If not specified, the system will try to convert from the AdUnit's mediaTypes.banner.sizes.        | `[15]`                                                                              | `Array<integer>` |
 | `position`     | optional           | Set the page position. Valid values are "atf" and "btf".                                                                    | `'atf'`                                                                             | `string`         |
 | `userId`       | optional           | Site-specific user ID may be reflected back in creatives for analysis. Note that userId needs to be the same for all slots. | `'12345abc'`                                                                        | `string`         |
 | `floor`       | optional           | Sets the global floor -- no bids will be made under this value.                                                             | `0.50`                                                                              | `float`          |
@@ -50,8 +49,6 @@ The following video parameters are supported:
 {: .table .table-bordered .table-striped }
 | Name           | Scope              | Description                                                                                                                                                                                              | Example | Type      |
 |----------------|--------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------|-----------|
-| `playerWidth`  | optional | Video player width in pixels. If not specified, takes width set in mediaTypes.video.playerSize                                                                                                                                                                             | `'640'` | `string`  |
-| `playerHeight` | optional | Video player height in pixels. If not specified, takes height set in mediaTypes.video.playerSize                                                                                                                                                                            | `'360'` | `string`  |
 | `size_id`      | optional for Prebid.js, required for Prebid Server |  Integer indicating the Rubicon Project video ad format ID. If not set, Prebid.js can infer from mediaTypes.video.context | `201`   | `integer` |
 | `language`     | recommended | Indicates the language of the content video, in ISO 639-1/alpha2. Highly recommended for successful monetization for pre-, mid-, and post-roll video ads. Not applicable for interstitial and outstream. | `'en'`  | `string`  |
 

features/InterstitialAds.md

@@ -0,0 +1,78 @@
+---
+layout: page_v2
+title: Prebid.js Interstitial Ads
+description: Interstitial Ads - Prebid.js
+sidebarType: 1
+---
+
+# Interstitial Ads - Prebid.js
+{: .no_toc}
+
+* TOC
+{:toc}
+
+Interstitails ads are high engagement ads often placed at natural transition points of the user's experince, such as moving from one page to the next. Interstitial ads are generally center aligned overlaying user content, where the user is forced to close the ad to progress in their user experience to view content. Because the ad interupts the user's flow, marketers often pay a premium for such ads. 
+
+This document covers how to setup interstitial ad units.
+
+{: .alert.alert-warning :}
+Please check with each of your bidders to ensure they're reading the interstitial flag from the standard Prebid location.
+
+
+## How It Works
+
+The intended flow for publishers is the following:
+- Publisher traffics interstitial line item with appropriate size(s) ([GAM example](https://support.google.com/admanager/answer/9840201?hl=en))
+- Publisher defines ad server interstitial slot on the page ([GAM Example](https://developers.google.com/publisher-tag/samples/display-web-interstitial-ad))
+- Publisher defines the appropriate interstitial ad sizes within appriate adUnit.mediaType and supplies the adUnit Interstitial flag within the [AdUnit.ortb2Imp](/dev-docs/adunit-reference.html#adUnit-interstitial-example) config
+- Prebid requests bids for interstitial adUnits and invokes the ad server call from the requestBids callback
+
+## Ad Sizes
+Publishers are intended to set the desired size in the respective adUnit. 
+
+The below sizes are specials sizes to indicate the ad will be full screen for mobile or tablet devices:
+- 320x480: Fullscreen mobile phone portrait ad
+- 480x320: Fullscreen mobile phone landscape ad 
+- 768x1024: Fullscreen tablet portrait ad
+- 1024x768: Fullscreen tablet landscape ad
+
+## In-Page Example
+
+The Prebid Interstitial flag reflects the OpenRTB standard, specifying it at the imp level.
+
+
+### Supplying Interstitial Flag
+
+If an attribute is specific to an AdUnit, it can be passed this way:
+
+{% highlight js %}
+pbjs.addAdUnits({
+    code: "test-div",
+    mediaTypes: {
+        banner: {
+            sizes: [[300,250]]
+        }
+    },
+    ortb2Imp: {
+        intl:1
+    },
+    ...
+});
+{% endhighlight %}
+
+
+
+## How Bid Adapters Should Read Interstitial Flag
+
+To access global data, a Prebid.js bid adapter needs only to retrive the interstitial flag from the adUnit like this:
+
+{% highlight js %}
+utils.deepAccess(bidRequest.ortb2Imp, 'instl')
+{% endhighlight %}
+
+
+The assumption is that bid adapters will copy the values to the appropriate protocol location for their endpoint.
+
+## Related Topics
+
+- The [AdUnit Reference](/dev-docs/adunit-reference.html)