refactored enableSendAllBids docs

adops/deals.md

@@ -4,16 +4,10 @@ title: Enable Deals
 head_title: Enable Deals in Prebid for Header Bidding
 description: Enable Deals in Prebid for Header Bidding Analysis.
 pid: 4
-
 hide: false
-
-top_nav_section: adops
-nav_section: tutorials
 sidebarType: 3
 ---
 
-
-
 # Enable Deals in Prebid
 {:.no_toc}
 
@@ -50,8 +44,14 @@ hb_deal_appnexus = APN_456
 // hb_adid, hb_size, and hb_adid omitted
 ```
 
-{: .bg-info :}
-Whether your Ad Ops setup [sends all bids to the ad server](/adops/send-all-bids-adops.html) or just [sends the top bid to the ad server](/adops/step-by-step.html), Prebid.js will generate the deal key-values for every bidder. The reason is that you may want to give deals higher priorities in the ad server, which needs to see all deal-enabled bids.
+{% capture noteAlert %}
+We recommend confirming with your development team that the page is set up to send all deal targeting to the ad server. There are two ways to do this:  
+- Set the `enableSendAllBids` to **true**.  
+- Set `enableSendAllBids` to **false** and `alwaysIncludeDeals` to **true**. This option will minimize the number of targeting variables sent to the ad server.  
+See the [enableSendAllBids](/dev-docs/publisher-api-reference.html#setConfig-Send-All-Bids) documentation for details.
+{% endcapture %}
+
+{% include alerts/alert_note.html content=noteAlert %}
 
 <br>
 
@@ -133,4 +133,3 @@ e.g. if the line item is targeted to `hb_deal_pubmatic`, then the creative needs
 
 If however, the line item is targeted to `hb_deal` (without a bidder code),
 then the simplified creative setup in the [step-by-step instructions](/adops/step-by-step.html#step-2-add-a-creative) will be fine.
-

dev-docs/publisher-api-reference.md

@@ -1358,37 +1358,73 @@ pbjs.setConfig({ timeoutBuffer: 300 });
 
 <a name="setConfig-Send-All-Bids" />
 
-Sending all bids is the default, but should you wish to turn it off:
+When enableSendAllBids is **true** (the default), the page will send keywords for all bidders to your ad server. The ad server can then make the decision on which bidder will win. Some ad servers, such as Google Ad Manager, can then generate reporting on historical bid prices from all bidders.
 
-{% highlight js %}
-pbjs.setConfig({ enableSendAllBids: false })
-{% endhighlight %}
-
-When sendAllBids mode is on, your page will send keywords for all bidders to your ad server. The ad server will then make the decision on which will win. Some ad servers, such as Google Ad Manager, can then generate reporting on historical bid prices from all bidders.
+However, there will be a set of ad server targeting values for each bidder, so if you run many bidders this could cause an issue with how much data is being sent to the ad server.
 
-Note that this config must be set before `pbjs.setTargetingForGPTAsync()` or `pbjs.getAdserverTargeting()`.
+There are several ways to address the issue of sending too much data to the ad server:
 
-After this method is called, `pbjs.getAdserverTargeting()` will give you the below JSON (example). `pbjs.setTargetingForGPTAsync()` will apply the below keywords in the JSON to GPT (example below)
+1. Set `enableSendAllBids` to **false**. This will minimize the number of targeting variables sent to the ad server; only the top bid will be sent.
+1. Define the `auctionKeyMaxChars` setting. This allows you to establish a limit on the number of bytes sent to the ad server. See [targetingControls](#setConfig-targetingControls) for more details.
+1. Set `enableSendAllBids` to **false** and `targetingControls.alwaysIncludeDeals` to **true**. This will send the top bid and any deals.
+1. Set `enableSendAllBids` to **false**, `targetingControls.alwaysIncludeDeals` to **true**, and `auctionKeyMaxChars`. This will send the top bid and any deals up to the maximum number of characters.
 
+Note that targeting config must be set before either `pbjs.setTargetingForGPTAsync()` or `pbjs.getAdserverTargeting()` is called.
 
-{% include send-all-bids-keyword-targeting.md %}
+##### Example results where enableSendAllBids is true
 
 {% highlight bash %}
 {
   "hb_adid_audienceNetw": "1663076dadb443d",
   "hb_pb_audienceNetwor": "9.00",
   "hb_size_audienceNetw": "300x250",
+  "hb_format_audienceNe": "banner",
+  "hb_source_audienceNe": "client",
+  "hb_adid_rubicon": "3485968928",
+  "hb_pb_rubicon": "8.00",
+  "hb_size_rubicon": "300x250",
+  "hb_deal_rubicon": "11111111",
+  "hb_format_rubicon": "banner",
+  "hb_source_rubicon": "client",
   "hb_adid_appnexus": "191f4aca0c0be8",
   "hb_pb_appnexus": "10.00",
   "hb_size_appnexus": "300x250",
-  // also sends the highest bid in the these variables:
+  "hb_format_appnexus": "banner",
+  "hb_source_appnexus": "client",
+  // the winning bid is copied to attributes without a suffix
   "hb_bidder": "appnexus",
   "hb_adid": "191f4aca0c0be8",
   "hb_pb": "10.00",
   "hb_size": "300x250",
+  "hb_format": "banner"
 }
 {% endhighlight %}
 
+You can see how the number of ad server targeting variable could get large
+when many bidders are present.
+
+{% capture noteAlert %}
+The Prebid recommendation is to leave `enableSendAllBids` as **true** when ad server targeting volume is not a concern. This approach is more transparent and leaves the decisioning in the ad server.
+{% endcapture %}
+
+{% include alerts/alert_note.html content=noteAlert %}
+
+##### Example of setting enableSendAllBids to false
+
+Turning off `enableSendAllBids` will cause the system to return only the
+winning bid. However, this could be a problem if you need to support [deals](/adops/deals.html), as often a deal may be chosen to win over an open market bid.
+
+To make sure that deal bids are sent along with the winning bid in the enableSendAllBids:false scenario, use the `alwaysIncludeDeals` flag that's part of [targetingControls](#setConfig-targetingControls):
+
+```javascript
+pbjs.setConfig({
+  enableSendAllBids: false,
+  targetingControls: {
+    alwaysIncludeDeals: true
+  }
+});
+```
+
 <a name="setConfig-Bidder-Order" />
 
 #### Use Bid Cache
@@ -1807,18 +1843,24 @@ When user syncs are run, regardless of whether they are invoked by the platform
 
 The `targetingControls` object passed to `pbjs.setConfig` provides some options to influence how an auction's targeting keys are generated and managed.
 
-Below is an example config with the `targetingControls` object:
+{: .table .table-bordered .table-striped }
+| Attribute        | Type    | Description             |
+|------------+---------+---------------------------------|
+| auctionKeyMaxChars | integer | Specifies the maximum number of characters the system can add to ad server targeting. |
+| alwaysIncludeDeals | boolean | If [enableSendAllBids](#setConfig-Send-All-Bids) is false, set this value to `true` to ensure that deals are sent along with the winning bid |
+
+##### Details on the auctionKeyMaxChars setting
+
+Below is an example config containing `auctionKeyMaxChars`:
 
 ```javascript
 pbjs.setConfig({
   targetingControls: {
-    auctionKeyMaxChars: 5000
+    auctionKeyMaxChars: 5000,
   }
 });
 ```
 
-##### Details on the auctionKeyMaxChars setting
-
 When this property is set up, the `auctionKeyMaxChars` setting creates an effective ceiling for the number of auction targeting keys that are passed to an ad server.  This setting can be helpful if you know that your ad server has a finite limit to the amount of query characters it will accept and process.  When there is such a limit, query characters that exceed the threshold are normally just dropped and/or ignored, which can cause potential issues with the delivery or rendering of the ad.
 
 Specifically, Prebid will go through the following steps with this feature: