Interstitial Ads additions (#2851)

* removed sizes from RP bid params

* added interstitial page and config to adUnit

* interstitial page corrections

* Update InterstitialAds.md

* Update InterstitialAds.md

Co-authored-by: MartianTribe <steve@martiantribe.com>

_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)

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 often placed at natural transition points of the user's experince, such as moving from one page to the next. These ads are generally center aligned overlaying user content. 
+
+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)