adding customGptSlotMatching to top-level config

dev-docs/modules/bidViewable.md

@@ -48,19 +48,16 @@ The default logic used to find a matching Prebid.js bid for a GPT slot is
 | `bidViewability` | Required | Object | Configuration object |
 | `bidViewability.enabled` | Required | Boolean | when set to true, the module will emit BID_VIEWABLE when applicable. Default: `false` |
 | `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. Default: `false` |
-| `bidViewability.customMatchFunction` | Optional | function(bid, slot) | this function will be used to find the matching winning bid for the GPT slot. See above for the default. |
+
+Custom slot matching (which winning bid maps to which GPT slot) can be set via top-level [customGptSlotMatching](/dev-docs/publisher-api-reference/setConfig.html#setConfig-customGptSlotMatching) in setConfig.
 
 ## Example of setting module config
 
 ```javascript
     pbjs.setConfig({
         bidViewability: {
             enabled: true,
-            firePixels: true,
-            customMatchFunction: function(bid, slot){
-                console.log('using custom match function....');
-                return bid.adUnitCode === slot.getAdUnitPath();
-            }
+            firePixels: true
         }
     });
 ```

dev-docs/modules/gpt-pre-auction.md

@@ -49,7 +49,6 @@ Optional initialization parameters:
 {: .table .table-bordered .table-striped }
 | Param | Required? | Type | Description | Example |
 | enabled | no | boolean | allows turning off of module. Default value is true | true |
-| customGptSlotMatching | no | function | GPT slot matching function should match the customSlotMatching function sent to [setTargetingForGptAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html) | |
 | useDefaultPreAuction | no | boolean | (PBJS 6.5+) If true, use default behavior for determining GPID and PbAdSlot. Defaults to false. | true |
 | customPreAuction | no | function | (PBJS 6.5+) Custom function for defining the GPID and PbAdSlot. | |
 | customPbAdSlot | no | function | Custom PB AdSlot function. (Note, this function will be deprecated in the future.) | |
@@ -66,10 +65,6 @@ pbjs.setConfig({
         ...
         return "customPbAdSlot";
     },
-    customGptSlotMatching: function(gptSlotObj) {
-        ...
-        return true; // or false
-    },
     mcmEnabled: true
     }
 });
@@ -80,7 +75,7 @@ pbjs.setConfig({
 When this module is turned on, it uses the BEFORE_REQUEST_BIDS event to insert functionality that:
 
 * loops through each adunit in the auction
-* maps the PBJS adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync including customGptSlotMatching
+* maps the PBJS adunit to the GPT slot using the same algorithm as setTargetingForGPTAsync; custom slot matching can be set via top-level [customGptSlotMatching](/dev-docs/publisher-api-reference/setConfig.html#setConfig-customGptSlotMatching) in setConfig
 
 ### Defining the AdServer name and adslot
 

dev-docs/publisher-api-reference/setConfig.md

@@ -145,6 +145,22 @@ pbjs.setConfig({
 });
 ```
 
+### Custom Slot Matching (GPT)
+
+<a name="setConfig-customGptSlotMatching"></a>
+
+When using GPT (Google Publisher Tag), you can set a top-level `customGptSlotMatching` function that controls how Prebid matches ad units to GPT slots. This function receives a GoogleTag slot and returns a filter function for adUnitCode. It is used by [setTargetingForGPTAsync](/dev-docs/publisher-api-reference/setTargetingForGPTAsync.html), the [GPT Pre-Auction module](/dev-docs/modules/gpt-pre-auction.html), [setPAAPIConfigForGPT](/dev-docs/publisher-api-reference/setPAAPIConfigForGPT.html), and the [Bid Viewability - GAM module](/dev-docs/modules/bidViewable.html).
+
+```javascript
+pbjs.setConfig({
+  customGptSlotMatching: function(slot) {
+    return function(adUnitCode) {
+      return adUnitCode === slot.getAdUnitPath() || slot.getSlotElementId() === adUnitCode;
+    };
+  }
+});
+```
+
 ### Change prerendering behavior
 
 When a page is [prerendered](https://developer.chrome.com/docs/web-platform/prerender-pages), by default Prebid will delay auctions until it is activated.

dev-docs/publisher-api-reference/setTargetingForGPTAsync.md

@@ -1,6 +1,6 @@
 ---
 layout: api_prebidjs
-title: pbjs.setTargetingForGPTAsync([codeArr], customSlotMatching)
+title: pbjs.setTargetingForGPTAsync([codeArr])
 description: setTargetingForGPTAsync API
 sidebarType: 1
 ---
@@ -14,7 +14,6 @@ Set query string targeting on GPT ad units after the auction.
 | Param | Scope | Type | Description |
 | --- | --- | --- | -- |
 | [codeArr] | Optional | `array` | an array of adUnitCodes to set targeting for. |
-| customSlotMatching | Optional | `function` | gets a GoogleTag slot and returns a filter function for adUnitCode. |
 
 This function matches AdUnits that have returned from the auction to a GPT ad slot and adds the `hb_`
 targeting attributes to the slot so they get sent to GAM.
@@ -23,14 +22,14 @@ Here's how it works:
 
 1. For each AdUnit code that's returned from auction or is specified in the `codeArr` parameter:
 2. For each GPT ad slot on the page:
-3. If the `customSlotMatching` function is defined, call it. Else, try to match the AdUnit `code` with the GPT slot name. Else try to match the AdUnit `code` with the ID of the HTML div containing the slot.
+3. If a `customGptSlotMatching` function is set in [setConfig](/dev-docs/publisher-api-reference/setConfig.html#setConfig-customGptSlotMatching), use it. Else, try to match the AdUnit `code` with the GPT slot name. Else try to match the AdUnit `code` with the ID of the HTML div containing the slot.
 4. On the first slot that matches, add targeting from the bids on the AdUnit. Exactly which targets are added depends on the status of [enableSendAllBids](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-Bids-Control) and [auctionKeyMaxChars](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls).
 
 {% capture tipAlert %} To see which targeting key/value pairs are being added to each slot, you can use the GPT Console. From the javascript console, run `googletag.openConsole();` {% endcapture %}
 
 {% include alerts/alert_tip.html content=tipAlert %}
 
-The `customSlotMatching` parameter allows flexibility in deciding which div id
+The optional [customGptSlotMatching](/dev-docs/publisher-api-reference/setConfig.html#setConfig-customGptSlotMatching) config (set via `pbjs.setConfig`) allows flexibility in deciding which div id
 the ad results should render into. This could be useful on long-scrolling pages... instead of setting the timeout of auctions
 short to make sure they get good viewability, the logic can find an appropriate placement for the auction
 result depending on where the user is once the auction completes.
@@ -49,6 +48,6 @@ function pickInViewDiv(slot) {
 };
 
 // make sure we render the results from the auction in a div that is visible in the viewport (example infinite scrolling, instead of rendering a ad in the top of the list that will never be visible (made up example))
-
-setTargetingForGPTAsync(adUnit, pickInViewDiv);
+pbjs.setConfig({ customGptSlotMatching: pickInViewDiv });
+setTargetingForGPTAsync(adUnit);
 ```