From 8056d675dc71b7343b48abcf5e7947b5c24bb872 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 15 Nov 2017 16:07:58 -0500 Subject: [PATCH] Document `pbjs.adServers.dfp.buildVideoUrl` update to accept ad server URL (#422) * WIP - draft still too complex * Further WIP on `dfp.buildVideoUrl`, needs review * More Prebid Cache / `options.url` interactions (Also: some edits for brevity/clarity/etc.) * Re-order table entries for easier scanning * Revise based on feedback --- dev-docs/publisher-api-reference.md | 88 ++++++++++++++++++----------- 1 file changed, 55 insertions(+), 33 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 35dd791f0d..6c916058be 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -366,7 +366,6 @@ Returns a bool if all the bids have returned or timed out
- ### pbjs.enableSendAllBids() @@ -767,7 +766,6 @@ pbjs.bidderSettings = { {% endhighlight %} - ##### 2.3. bidCpmAdjustment Some bidders return gross prices instead of the net prices (what the publisher will actually @@ -793,7 +791,6 @@ pbjs.bidderSettings = { In the above example, the AOL bidder will inherit from "standard" adserverTargeting keys, so that you don't have to define the targeting keywords again. - ##### 2.4. sendStandardTargeting This boolean flag minimizes key/value pairs sent to the ad server when @@ -996,10 +993,9 @@ Example use: pbjs.setBidderSequence('fixed'); /* defaults to 'random' as of 0.27.0 */ ``` - +
-

-

+ ### pbjs.onEvent(event, handler, id) @@ -1081,6 +1077,8 @@ The example below shows how to use these methods: {% endhighlight %} +
+ ### pbjs.enableAnalytics(config) @@ -1091,6 +1089,8 @@ For usage, see [Integrate with the Prebid Analytics API]({{site.baseurl}}/dev-do For a list of analytics adapters, see [Analytics for Prebid]({{site.baseurl}}/overview/analytics.html). +
+ ### pbjs.aliasBidder(adapterName, aliasedName) @@ -1114,6 +1114,8 @@ If you define an alias and are using `pbjs.sendAllBids`, you must also set up ad + `hb_size_newalias` + `hb_deal_newalias` +
+ ### pbjs.setConfig(options) @@ -1230,6 +1232,8 @@ ERROR: setConfig options must be an object If you don't see that message, you can assume the config object is valid. +
+ ### pbjs.getConfig([string]) @@ -1263,41 +1267,48 @@ unsubscribe(); // no longer listening {% endhighlight %} +
+ -### pbjs.adServers.dfp.buildVideoUrl(options) ⇒ `String` +### pbjs.adServers.dfp.buildVideoUrl(options) {: .alert.alert-info :} -This method was added in 0.26.0. For a usage example and instructions showing how to build Prebid.js to include this method, see [Show Video Ads with DFP]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html). +This method was added in [0.26.0](https://github.com/prebid/Prebid.js/releases/tag/0.26.0). -This method returns a DFP video ad tag URL which is built by combining publisher-provided URL parameters with Prebid.js key-values. +This method combines publisher-provided parameters with Prebid.js targeting parameters to build a DFP video ad tag URL that can be used by a video player. -This method takes a single `options` object as an argument, described below: +#### Argument Reference + +##### The `options` object {: .table .table-bordered .table-striped } -| Field | Type | Description | -|--------|--------|-------------------------------------------------------------------------------------------------------------------------------------------------| -| adUnit | object | (Required) The Prebid adUnit to which the returned URL will map. | -| bid | object | (Optional) The Prebid bid for which targeting will be set. If this is not defined, Prebid will use the bid with the highest CPM for the adUnit. | -| params | object | (Required) Querystring parameters that will be used to construct the DFP video ad tag URL. | +| Field | Type | Description | +|----------+--------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `adUnit` | object | *Required*. The Prebid ad unit to which the returned URL will map. | +| `params` | object | *Optional*. Querystring parameters that will be used to construct the DFP video ad tag URL. Publisher-supplied values will override values set by Prebid.js. See below for fields. | +| `url` | string | *Optional*. The video ad server URL. When given alongside params, the parsed URL will be overwritten with any matching components of params. | +| `bid` | object | *Optional*. The Prebid bid for which targeting will be set. If this is not defined, Prebid will use the bid with the highest CPM for the adUnit. | + +{: .alert.alert-warning :} +One or both of options.params and options.url is required. In other words, you may pass in one, the other, or both, but not neither. -The `options.params` object is described below: +##### The `options.params` object {: .table .table-bordered .table-striped } -| Field | Type | Description | Example | -|----------------|--------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------| -| iu | string | (Required) DFP adUnit ID. For more information, see the [DFP documentation on `iu`](https://support.google.com/dfp_premium/answer/1068325?hl=en#iu) | `/19968336/prebid_cache_video_adunit` | -| cust_params | object | (Optional) Key-value pairs that will be sent to DFP on the video ad tag URL. If present, any key-values here will be merged with Prebid standard targeting key-values. For more information, see the [DFP documentation on `cust_params`](https://support.google.com/dfp_premium/answer/1068325?hl=en#cust_params) | {section: "blog", anotherKey: "anotherValue"} | -| "arbitraryKey" | string | (Optional) Any additional querystring parameters that will be used to construct the DFP video ad tag URL. | `output: "vast"` | +| Field | Type | Description | Example | +|-------------------+--------+-----------------------------------------------------------------------------------------------------------------------------+-------------------------------------------------| +| `iu` | string | *Required*. DFP ad unit ID. | `/19968336/prebid_cache_video_adunit` | +| `cust_params` | object | *Optional*. Key-value pairs merged with Prebid's targeting values and sent to DFP on the video ad tag URL. | `{section: "blog", anotherKey: "anotherValue"}` | +| `description_url` | string | *Optional*. Describes the video. Required for Ad Exchange. Prebid.js will build this for you unless you pass it explicitly. | `http://www.example.com` | -{: .alert.alert-info :} -Note: Prebid.js will choose reasonable default values for any required DFP URL parameters that are not included in the `options.params` object. +For more information on any of these params, see [the DFP video tag documentation](https://support.google.com/dfp_premium/answer/1068325?hl=en). -For more information about the options supported by the DFP API, see [the DFP API docs](https://support.google.com/dfp_premium/answer/1068325?hl=en#env). +#### Examples -#### Example Usage +There are several different ways to build up your video URL, as shown in the examples below: -For a usage example in context, see [Show Video Ads with DFP]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html). +Using `options.params` only: ```javascript pbjs.requestBids({ @@ -1307,12 +1318,12 @@ pbjs.requestBids({ params: { iu: '/19968336/prebid_cache_video_adunit', cust_params: { - section: "blog", - anotherKey: "anotherValue" + section: "blog", + anotherKey: "anotherValue" }, hl: "en", - output: "vast", - url: "http://www.referer-url.com" + output: "xml_vast2", + url: "http://www.example.com", } }); invokeVideoPlayer(videoUrl); @@ -1320,10 +1331,21 @@ pbjs.requestBids({ }); ``` -This call returns the following DFP video ad tag URL: +Using `options.url` only: +```javascript +var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' ++ 'sz=640x480&iu=/19968336/prebid_cache_video_adunit&impl=s&gdfp_req=1' ++ '&env=vp&output=xml_vast2&unviewed_position_start=1&hl=en&url=http://www.example.com' ++ '&cust_params=section%3Dblog%26anotherKey%3DanotherValue'; + +var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + adUnit: videoAdUnit, + url: adserverTag +}); ``` -https://pubads.g.doubleclick.net/gampad/ads?env=vp&gdfp_req=1&output=vast&unviewed_position_start=1&correlator=1507127916397&sz=640x480&url=http://www.referer-url.com&iu=/19968336/prebid_cache_video_adunit&cust_params=hb_bidder%3DappnexusAst%26hb_adid%3D26d4996ee83709%26hb_pb%3D10.00%26hb_size%3D640x480%26hb_uuid%3D16c887cf-9986-4cb2-a02f-8e9bd025f875%26section%3Dblog%26anotherKey%3DanotherValue&hl=en -``` + +{: .alert.alert-warning :} +In the event of collisions, querystring values passed via `options.params` take precedence over those passed via `options.url`.