From 0640337280308a5413f0c41c8e26c64471e2b8ea Mon Sep 17 00:00:00 2001 From: Mike Menetto Date: Wed, 16 Sep 2020 14:47:45 -0700 Subject: [PATCH 1/2] initial check-in: document targetingControls.allowTargetingKeys --- dev-docs/publisher-api-reference.md | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 3245cc5547..f4f7157df5 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,26 @@ 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 + +Below is an example config containing `allowTargetingKeys`: + +```javascript +config.setConfig({ + targetingControls: { + allowTargetingKeys: ['BIDDER', 'AD_ID', 'PRICE_BUCKET'] + } +}); +``` + +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. From db8de9ac03d3de3e7b0c74e4fc3a1fc1367f08c3 Mon Sep 17 00:00:00 2001 From: Mike Menetto Date: Thu, 24 Sep 2020 09:25:18 -0700 Subject: [PATCH 2/2] update documentation to include the names and values of the default targeting keys. also changed presentation order so implementation example appears after context. --- dev-docs/publisher-api-reference.md | 53 +++++++++++++++++++++++------ 1 file changed, 43 insertions(+), 10 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index f4f7157df5..427f90e5c3 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -2078,16 +2078,6 @@ Between this feature and the overlapping [sendBidsControl.bidLimit](/dev-docs/pu ##### Details on the allowTargetingKeys setting -Below is an example config containing `allowTargetingKeys`: - -```javascript -config.setConfig({ - targetingControls: { - allowTargetingKeys: ['BIDDER', 'AD_ID', 'PRICE_BUCKET'] - } -}); -``` - 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: @@ -2097,6 +2087,49 @@ To accomplish this, Prebid does the following: * 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'] + } +}); +``` + #### Configure Responsive Ads