diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 3245cc5547..427f90e5c3 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -2031,6 +2031,7 @@ The `targetingControls` object passed to `pbjs.setConfig` provides some options |------------+---------+---------------------------------| | 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 | +| allowTargetingKeys | Array of Strings | Selects supported default targeting keys. | {: .alert.alert-info :} Note that this feature overlaps and can be used in conjunction with [sendBidsControl.bidLimit](/dev-docs/publisher-api-reference.html#setConfig-Send-Bids-Control). @@ -2075,6 +2076,59 @@ Between these two values (Prebid's targeting key count and the overall ad URL qu Between this feature and the overlapping [sendBidsControl.bidLimit](/dev-docs/publisher-api-reference.html#setConfig-Send-Bids-Control), you should be able to make sure that there's not too much data going to the ad server. +##### Details on the allowTargetingKeys setting + +When this property is set up, the `allowTargetingKeys` creates a default targeting key mask based on the default targeting keys defined in CONSTANTS.TARGETING_KEYS and CONSTANTS.NATIVE_KEYS. Any default keys that do not match the mask will not be sent to the adserver. This setting can be helpful if you find that your prebid implementation is by default sending key values that your adserver isn't configured to process. When extraneous key values are sent, the ad server request can be truncated, which can cause potential issues with the delivery or rendering of the ad. + +To accomplish this, Prebid does the following: +* Collect original targeting generated by the auction. +* Generate new targeting filtered against allowed keys. + * Custom targeting keys are always added to targeting. + * Default targeting keys are added to targeting only if they match an allowed key named in `setConfig`. +* New targeting replaces original targeting before targeting is flattened. + +The targeting key names and the associated prefix value filtered by `allowTargetingKeys`: +{: .table .table-bordered .table-striped } +| Name | Value | +|------------+------------| +| BIDDER | `hb_bidder` | +| AD_ID | `hb_adid` | +| PRICE_BUCKET | `hb_pb` | +| SIZE | `hb_size` | +| DEAL | `hb_deal` | +| SOURCE | `hb_source` | +| FORMAT | `hb_format` | +| UUID | `hb_uuid` | +| CACHE_ID | `hb_cache_id` | +| CACHE_HOST | `hb_cache_host` | +| title | `hb_native_title` | +| body | `hb_native_body` | +| body2 | `hb_native_body2` | +| privacyLink | `hb_native_privacy` | +| privacyIcon | `hb_native_privicon` | +| sponsoredBy | `hb_native_brand` | +| image | `hb_native_image` | +| icon | `hb_native_icon` | +| clickUrl | `hb_native_linkurl` | +| displayUrl | `hb_native_displayurl` | +| cta | `hb_native_cta` | +| rating | `hb_native_rating` | +| address | `hb_native_address` | +| downloads | `hb_native_downloads` | +| likes | `hb_native_likes` | +| phone | `hb_native_phone` | +| price | `hb_native_price` | +| salePrice | `hb_native_saleprice` | + +Below is an example config containing `allowTargetingKeys` excluding all default targeting keys except `hb_bidder`, `hb_adid`, and `hb_pb`: + +```javascript +config.setConfig({ + targetingControls: { + allowTargetingKeys: ['BIDDER', 'AD_ID', 'PRICE_BUCKET'] + } +}); +```