added ignoreBidderCacheKey docs (#2720)

* added ignoreBidderCacheKey docs

* edits and some general cleanup

Co-authored-by: Jean Stemp <jstemp@appnexus.com>

_includes/adops/adops-gam-video-setup.html

@@ -36,19 +36,20 @@ <h2 id="line-item-setup">Line Item Setup</h2>
 <p>Be sure to duplicate your line item and video creative for each Prebid price bucket you intend to create. </p>
 <p class="alert alert-warning">By default, Prebid.js caps all CPMs at $20.  As a video seller, you may expect to see CPMs higher than $20.  In order to receive those bids, you’ll need to make sure your dev team implements custom price buckets as described in the <a href="/dev-docs/show-video-with-a-dfp-video-tag.html#implement-custom-price-buckets">engineering setup instructions</a>.  Once those changes are made on the engineering side, there should be no changes required from the ad ops side to support CPMs over $20.</p>
 
-<p class="alert alert-success"><b>Multiple Cache Services</b><br>You might need separate video line items for each cache service being used. For example, if both AppNexus and Rubicon Project are bidders, you’ll either need to create separate line items to support the different cache URLs required or provide separately-targeted creatives, as described below.</p>
-
 <h2 id="creative-setup">Creative Setup</h2>
 
 When setting up video creatives, it's important to understand where the VAST XML is stored for each of your bidders. The most common place to store VAST XML is AppNexus' cache, but some bidders (such as RubiconProject and SpotX) use their own cache services. To support such
-bidders, you will need to have either:
+bidders, you will need to choose one of the following approaches:
 <ul>
-<li>a separate line item for each bidder, or</li>
-<li>a creative for each cache service utilized by your implementation.</li>
+<li>Create a separate line item for each bidder.</li>
+<li>Include a creative for each cache service utilized by your implementation.</li>
+<li>Use the <a href="/dev-docs/publisher-api-reference.html#setConfig-vast-cache">ignoreBidderCacheKey</a> option on setConfig({cache}).</li>
 </ul>
 
 <h3 id="creative-single-cache">Single Cache Location</h3>
 
+If you only use bidders that provide full VAST responses, no special setup is needed. Otherwise, do the following:
+
 <p>1. For each line item you create, click on the <b>Creatives</b> tab, click the <b>ADD CREATIVE</b> button, and choose the size you're entering.</p>
 
 <p>2. In the dialog that appears, choose <b>Redirect</b>.</p>
@@ -71,7 +72,7 @@ <h3 id="creative-single-cache">Single Cache Location</h3>
 
 <p class="alert alert-info"><strong>Prebid Cache and the VAST creative URL warning</strong><br />
    Google Ad Manager will show you a warning stating that fetching VAST from the creative
-   URL failed.  This is expected, since the creative URL above points
+   URL failed. This is expected, since the creative URL above points
    to a server-side asset cache hosted by Prebid Server.</p>
 
 <p>4. Set the <b>Duration</b> to <b>1</b>.</p>
@@ -82,6 +83,15 @@ <h3 id="creative-single-cache">Single Cache Location</h3>
 
 <h3 id="creative-multiple-cache">Multiple Cache Locations</h3>
 
+If you're utilizing any bidders that cache their own VAST, you have two options:
+
+<ul>
+<li>If you're using Prebid.js 4.28 or later, you can specify the <a href="/dev-docs/publisher-api-reference.html#setConfig-vast-cache">ignoreBidderCacheKey</a> option on setConfig({cache}). This will cause the browser to generate a VAST wrapper and cache it in your standard location. Then you can use the instructions
+above for "Single Cache Location". The tradeoff is that this approach requires
+the video player to unwrap one extra level of VAST.</li>
+<li>Utilize creative-level targeting in the ad server. Keep reading for more details.</li>
+</ul>
+
 To set up multiple video creatives in the same line item (i.e., to run AppNexus, Rubicon, and SpotX all together in the same video line item), you can utilize creative targeting.
 <br/>
 <br/>

_includes/send-all-bids-keyword-targeting.md

@@ -1,14 +1,8 @@
-{% capture infoNote %}
 **Important:** Google Ad Manager has a key-value key character [limit](https://support.google.com/dfp_premium/answer/1628457?hl=en#Key-values) of up to **20 characters**. Some of the keys without truncation will exceed 20 chars. Prebid.js automatically truncates the key length to 20 characters. For example, `hb_adid_longBidderName` is truncated to `hb_adid_longBidderNa` (`me` is truncated). Note that the key is case-sensitive. To get the exact key-value keys for each bidder, find them at [Bidder Params](/dev-docs/bidders.html).
-{% endcapture %}
-
-{% include alerts/alert_note.html content=infoNote %}
-
 
 {: .table .table-bordered .table-striped }
 | Default Key   | Scope    | Description                                                                                     | Example   |
 | :----         |:----     | :----                                                                                           | :----     |
 | `hb_pb_BIDDERCODE`       | Required | The price bucket. Used by the line item to target. Case sensitive and truncated to 20 chars. The `BIDDERCODE` is documented at [Bidder Params](/dev-docs/bidders.html). | `hb_pb_rubicon` = `2.10`    |
 | `hb_adid_BIDDERCODE`     | Required | The ad Id. Used by the ad server creative to render ad. Case sensitive and truncated to 20 chars. The `BIDDERCODE` is documented at [Bidder Params](/dev-docs/bidders.html). | `hb_adid_longBidderNa` = `234234`  |
 | `hb_size_BIDDERCODE`   | Optional | This is not required for adops. Case sensitive and truncated to 20 chars. | `hb_size_appnexus` = `300x250` |
-

adops/send-all-bids-adops.md

@@ -13,23 +13,24 @@ sidebarType: 3
 
 This page shows how to set up your ad server so that you can send all bids and report on them.
 
-As a publisher, you may wish to have your ad server see **all** header bidding bids (instead of seeing only the winning bids in each auction).  Reasons you might want this behavior include:
+* TOC
+{: toc }
+
+## Overview
+
+As a publisher, you may want to have your ad server see **all** header bidding bids (instead of seeing only the winning bids in each auction).  Reasons you might want this behavior include:
 
-+ You want your ad server to see all header bidding bids, so that your ad server can report on bid prices, instead of only winning prices
++ You want your ad server to see all header bidding bids so that your ad server can report on bid prices instead of only winning prices.
 
-+ You have a contractual agreement with your header bidding partner
++ You have a contractual agreement with your header bidding partner.
 
 {: .alert.alert-success :}
 See the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#setConfig-Send-All-Bids) for more details.
 
-* TOC
-{: toc }
-
-## Overview
 
-+ Your developers may optionally add `enableSendAllBids: true` to `pbjs.setConfig()`.  This is not strictly necessary, as `enableSendAllBids` defaults to `true`.  For details, see the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#setConfig-Send-All-Bids).
+If you decide to send all bids to the ad sever, your developers have the option of explicity adding `enableSendAllBids: true` to `pbjs.setConfig()`.  However, since the default value is `true` this addition is not strictly necessary.  For details, see the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#setConfig-Send-All-Bids).
 
-+ From the ad ops side, you may choose to set up one order per bidder, so that each order can have a set of line items using targeting keywords that include the bidder's name.  For example, if you are working with [Rubicon]({{site.baseurl}}/dev-docs/bidders.html#rubicon), you would use `hb_pb_rubicon` in your line item's key-value targeting, and `hb_adid_rubicon` in the creative.
+From the ad ops side, you can choose to set up one order per bidder, which allows for each order to have a set of line items using targeting keywords that include the bidder's name.  For example, if you are working with [Rubicon](/dev-docs/bidders.html#rubicon), you would use `hb_pb_rubicon` in your line item's key-value targeting, and `hb_adid_rubicon` in the creative.
 
 {% include send-all-bids-keyword-targeting.md %}
 

dev-docs/publisher-api-reference.md

@@ -2490,12 +2490,19 @@ video player can retrieve them when it's ready. Players don't obtain the VAST XM
 the JavaScript DOM in Prebid.js, but rather expect to be given a URL where it can
 be retrieved. There are two different flows possible with Prebid.js around VAST XML caching:
 
-- Server-side caching:
-  Some video bidders (e.g. Rubicon Project) always cache the VAST XML on their servers as part of the bid. They provide a 'videoCacheKey', which is used in conjunction with the VAST URL in the ad server to retrieve the correct VAST XML when needed. In this case, Prebid.js has nothing else to do.
-- Client-side caching:
-  Video bidders that don't cache on their servers return the entire VAST XML body. In this scenario, Prebid.js needs to copy the VAST XML to a publisher-defined cache location on the network. In this scenario, Prebid.js POSTs the VAST XML to the named Prebid Cache URL. It then sets the 'videoCacheKey' to the key that's returned in the response.
+- Server-side caching:  
+  Some video bidders (e.g. Rubicon Project) always cache the VAST XML on their servers as part of the bid. They provide a 'videoCacheKey', which is used in conjunction with the VAST URL in the ad server to retrieve the correct VAST XML when needed. In this case, Prebid.js has nothing else to do. As of Prebid.js 4.28, a publisher may specify the `ignoreBidderCacheKey` flag to re-cache these bids somewhere else using a VAST wrapper.
+- Client-side caching:  
+  Video bidders that don't cache on their servers return the entire VAST XML body. In this scenario, Prebid.js needs to copy the VAST XML to a publisher-defined cache location on the network. Prebid.js POSTs the VAST XML to the named Prebid Cache URL. It then sets the 'videoCacheKey' to the key that's returned in the response.
 
-For client-side caching, set the Prebid Cache URL as shown here (substituting the correct URL for the one shown here):
+{: .table .table-bordered .table-striped }
+| Cache Attribute | Required? | Type | Description |
+|----+--------+-----+-------|
+| cache.url | yes | string | The URL of the Prebid Cache server endpoint where VAST creatives will be sent. |
+| cache.vasttrack | no | boolean | Passes additional data to the url, used for additional event tracking data. Defaults to `false`. |
+| cache.ignoreBidderCacheKey | no | boolean | If the bidder supplied their own cache key, setting this value to true adds a VAST wrapper around that URL, stores it in the cache defined by the `url` parameter, and replaces the original video cache key with the new one. This can dramatically simplify ad server setup because it means all VAST creatives reside behind a single URL. The tradeoff: this approach requires the video player to unwrap one extra level of VAST. Defaults to `false`. |
+
+Here's an example of basic client-side caching. Substitute your Prebid Cache URL as needed:
 
 {% highlight js %}
 pbjs.setConfig({
@@ -2508,6 +2515,17 @@ pbjs.setConfig({
 {: .alert.alert-warning :}
 The endpoint URL provided must be a Prebid Cache or be otherwise compatible with the [Prebid Cache interface](https://github.com/prebid/prebid-cache).
 
+As of Prebid.js 4.28, you can specify the `ignoreBidderCacheKey` option:
+
+{% highlight js %}
+pbjs.setConfig({
+        cache: {
+            url: 'https://my-pbs.example.com/cache',
+	    ignoreBidderCacheKey: true
+        }
+});
+{% endhighlight %}
+
 As of Prebid.js 2.36, you can track client-side cached VAST XML. This functionality is useful for publishers who want to allow their analytics provider to measure video impressions. The prerequisite to using this feature is the availability of a Prebid Server that supports:
 
 - the /vtrack endpoint
@@ -2519,7 +2537,7 @@ Given those conditions, the `vasttrack` flag can be specified:
 {% highlight js %}
 pbjs.setConfig({
         cache: {
-            url: '_PREBID_SERVER_URL_/vtrack',
+            url: 'https://my-pbs.example.com/vtrack',
             vasttrack: true
         }
 });