From 5d2beafa58556ba30c76cc585bdff89657734ee6 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 1 Nov 2017 15:46:04 -0400 Subject: [PATCH 1/5] WIP - draft still too complex --- dev-docs/publisher-api-reference.md | 114 ++++++++++++++++++++++------ 1 file changed, 91 insertions(+), 23 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index f0eb98ad52..545e2c8c5e 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -1232,38 +1232,47 @@ unsubscribe(); // no longer listening ### pbjs.adServers.dfp.buildVideoUrl(options) ⇒ `String` {: .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). 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 returns a DFP video ad tag URL which is built by combining publisher-provided URL parameters with Prebid.js key-values. ++ [Overview](#buildVideoUrl-overview) ++ [With the `options.params` argument](#options-params-argument) ++ [With the `options.url` argument](#options-url-argument) -This method takes a single `options` object as an argument, described below: + -{: .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. | +#### Overview -The `options.params` object is described below: +This method returns a DFP video ad tag URL built by combining publisher-provided URL parameters with Prebid.js key-values. -{: .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"` | +It can be called with an object of query string parameters, or with a video ad server URL. -{: .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. +In addition, it can be used with our without Prebid Cache, a server-side asset cache hosted by Prebid.org. -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). +Most users should probably use the `options.params` argument, with Prebid Cache enabled, and let Prebid.js build the DFP video ad tag URL for you. + +However, you can use the `options.url` argument for scenarios such as (but not limited to): + +- You are not using an ad server, and you want to insert the winning VAST content into your player directly +- You are using a video ad server that can accept a standalone VAST URL, as opposed to having to pass the VAST URL as a query string parameter -#### Example Usage +Important items to note: -For a usage example in context, see [Show Video Ads with DFP]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html). +- If this method is called with both `options.params` and `options.url` arguments, the parsed URL from `options.url` will be overwritten with any matching query string parameter components from `options.params`. +- Your (optional) usage of Prebid Cache, a server-side asset cache hosted by Prebid.org, may change how the method is used, and how bidders are required to respond, depending on the argument type ([`options.params` object](#options-params-argument), [`options.url` string](#options-url-argument)), or both. For more information, see [Usage scenarios and expected behavior](#usage-scenarios-and-expected-behavior). + + + +#### With the `options.params` argument + +Use as shown below. For more information, including links to live examples, see [Show Video Ads with DFP]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html). ```javascript +/* Prebid Cache is enabled in this example. See table in overview +section above for how turning it off affects usage. */ +pbjs.setConfig({ + usePrebidCache: true +}); + pbjs.requestBids({ bidsBackHandler: function(bids) { var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ @@ -1271,8 +1280,8 @@ pbjs.requestBids({ params: { iu: '/19968336/prebid_cache_video_adunit', cust_params: { - section: "blog", - anotherKey: "anotherValue" + section: "blog", + anotherKey: "anotherValue" }, hl: "en", output: "vast", @@ -1290,4 +1299,63 @@ This call returns the following DFP video ad tag URL: 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 ``` +The `options` object has the following fields: + +{: .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. | +| url | string | (Required, unless `params` is present) The video ad server URL. When given alongside `params`, parsed URL will be overwritten with any matching components of `params`. | +| params | object | (Required, unless `url` is present) Querystring parameters that will be used to construct the DFP video ad tag URL. Publisher-supplied values will override values set by Prebid.js. | + +The `options.params` object is described below: + +{: .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"` | + +{: .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 about the options supported by the DFP API, see [the DFP API docs](https://support.google.com/dfp_premium/answer/1068325?hl=en#env). + + + +#### With the `options.url` argument + +Use as shown below. + +```javascript +var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' ++ 'sz=640x480&iu=/19968336/prebid_video_adunit&impl=s&gdfp_req=1' ++ '&env=vp&output=xml_vast2&correlator=' + Date.now(); + +var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + adUnit: videoAdUnit, + url: adserverTag +}); +``` + + + +#### Usage scenarios and expected behavior + +The table below lists the expected behavior of this method when called with various configurations. + +FIXME: In the PR comment (https://github.com/prebid/Prebid.js/pull/1663) options.params with cache DISABLED is not mentioned. Does it work? + +FIXME: are updates to video bidder adapter docs required? e.g., to note that they must always supply a vastUrl as described at https://corpwiki.appnexus.com/x/8jWcBw + +{: .table .table-bordered .table-striped } +| Argument | Prebid Cache Enabled? | Notes | +|------------------------------------------------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `options.params` object containing query string parameters | Yes | If you set `description_url`, we use that; otherwise this method will automagically build it for you. | +| `options.params` object containing query string parameters | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | +| `options.url` string containing a video ad server URL | Yes | DOES NOT WORK (?) according to https://corpwiki.appnexus.com/x/8jWcBw - or is it simply the case that the bidder must provide `bid.vastUrl` (as below)? | +| `options.url` string containing a video ad server URL | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | + From 10ce92ce86d68c909fb812cd2391155dc62b2ec8 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Fri, 3 Nov 2017 18:18:21 -0400 Subject: [PATCH 2/5] Further WIP on `dfp.buildVideoUrl`, needs review --- dev-docs/publisher-api-reference.md | 129 +++++++++++++--------------- 1 file changed, 62 insertions(+), 67 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 545e2c8c5e..17dde555ad 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -1234,41 +1234,22 @@ unsubscribe(); // no longer listening {: .alert.alert-info :} This method was added in [0.26.0](https://github.com/prebid/Prebid.js/releases/tag/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). -+ [Overview](#buildVideoUrl-overview) -+ [With the `options.params` argument](#options-params-argument) -+ [With the `options.url` argument](#options-url-argument) +This method returns a DFP video ad tag URL built by combining publisher-provided URL parameters with Prebid.js key-values. The ad tag URL calls DFP, letting `options.bid` (or the auction's winning bid for this ad unit, if undefined) compete alongside the rest of the demand in DFP. - ++ [Examples](#buildVideoUrl-example-usage): Code samples showing how to call it. ++ [The `options` object](#buildVideoUrl-options-object): Field definitions on the `options` argument. ++ [The `options.params` object](#buildVideoUrl-options-params): Field definitions on the `options.params` sub-object. ++ [Usage scenarios and expected behavior](#buildVideoUrl-usage-scenarios-and-expected-behavior): How the method's different arguments interact with each other and Prebid Cache usage. -#### Overview + -This method returns a DFP video ad tag URL built by combining publisher-provided URL parameters with Prebid.js key-values. +#### Examples -It can be called with an object of query string parameters, or with a video ad server URL. - -In addition, it can be used with our without Prebid Cache, a server-side asset cache hosted by Prebid.org. - -Most users should probably use the `options.params` argument, with Prebid Cache enabled, and let Prebid.js build the DFP video ad tag URL for you. - -However, you can use the `options.url` argument for scenarios such as (but not limited to): - -- You are not using an ad server, and you want to insert the winning VAST content into your player directly -- You are using a video ad server that can accept a standalone VAST URL, as opposed to having to pass the VAST URL as a query string parameter - -Important items to note: - -- If this method is called with both `options.params` and `options.url` arguments, the parsed URL from `options.url` will be overwritten with any matching query string parameter components from `options.params`. -- Your (optional) usage of Prebid Cache, a server-side asset cache hosted by Prebid.org, may change how the method is used, and how bidders are required to respond, depending on the argument type ([`options.params` object](#options-params-argument), [`options.url` string](#options-url-argument)), or both. For more information, see [Usage scenarios and expected behavior](#usage-scenarios-and-expected-behavior). - - - -#### With the `options.params` argument - -Use as shown below. For more information, including links to live examples, see [Show Video Ads with DFP]({{site.baseurl}}/dev-docs/show-video-with-a-dfp-video-tag.html). +In this example, we use `options.params`, and have Prebid Cache enabled: ```javascript -/* Prebid Cache is enabled in this example. See table in overview -section above for how turning it off affects usage. */ +/* Prebid Cache is enabled in this example. See table in section +above for how turning it off affects usage. */ pbjs.setConfig({ usePrebidCache: true }); @@ -1299,63 +1280,77 @@ This call returns the following DFP video ad tag URL: 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 ``` +In this example, we are using `options.url` to pass in the video ad server directly: + +```javascript +var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' ++ 'sz=640x480&iu=/19968336/prebid_video_adunit&impl=s&gdfp_req=1' ++ '&env=vp&output=xml_vast2&correlator=' + Date.now(); + +var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ + adUnit: videoAdUnit, + url: adserverTag +}); +``` + + + + + +#### The `options` object + The `options` object has the following fields: {: .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. | -| url | string | (Required, unless `params` is present) The video ad server URL. When given alongside `params`, parsed URL will be overwritten with any matching components of `params`. | -| params | object | (Required, unless `url` is present) Querystring parameters that will be used to construct the DFP video ad tag URL. Publisher-supplied values will override values set by Prebid.js. | +| 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. 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`. | + + + +#### The `options.params` object + +The `options.params` object contains the parameters needed to form a URL which hits the [DFP API](https://support.google.com/dfp_premium/answer/1068325?hl=en). It has the following fields: -The `options.params` object is described below: +FIXME: is "arbitraryKey" still supported? not seeing anything explicitly mentioning it in the code at a glance, but may have missed it. It's also not mentioned in the JSDoc. {: .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 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. Any key-values given here will be merged with Prebid.js' 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"` | +| `description_url` | string | (Optional) Describes the video. Required for Ad Exchange. Prebid.js will build this for you unless you pass it explicitly. {: .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 about the options supported by the DFP API, see [the DFP API docs](https://support.google.com/dfp_premium/answer/1068325?hl=en#env). - + -#### With the `options.url` argument - -Use as shown below. - -```javascript -var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' -+ 'sz=640x480&iu=/19968336/prebid_video_adunit&impl=s&gdfp_req=1' -+ '&env=vp&output=xml_vast2&correlator=' + Date.now(); +#### Usage scenarios and expected behavior -var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ - adUnit: videoAdUnit, - url: adserverTag -}); -``` +Your (optional) usage of Prebid Cache, a server-side asset cache hosted by Prebid.org, may change how the method is used, and how bidders are required to respond, depending on the argument type ([`options.params`](#options-params-argument), [`options.url`](#options-url-argument)), or both. For more information, see [Example Usage](#buildVideoUrl-example-usage) and [Usage scenarios and expected behavior](#buildVideoUrl-usage-scenarios-and-expected-behavior). - +Reasons you might pass the `options.url` field include the following use cases: +- You are not using an ad server, and you want to insert the winning VAST content into your player directly +- You are using a video ad server that can accept a standalone VAST URL, as opposed to having to pass the VAST URL as a query string parameter -#### Usage scenarios and expected behavior The table below lists the expected behavior of this method when called with various configurations. -FIXME: In the PR comment (https://github.com/prebid/Prebid.js/pull/1663) options.params with cache DISABLED is not mentioned. Does it work? +FIXME: In the PR comment (https://github.com/prebid/Prebid.js/pull/1663) options.params with cache DISABLED is not mentioned. Does it work? -FIXME: are updates to video bidder adapter docs required? e.g., to note that they must always supply a vastUrl as described at https://corpwiki.appnexus.com/x/8jWcBw +FIXME: are updates to video bidder adapter docs required? e.g., to note that they must always supply a vastUrl as described at https://corpwiki.appnexus.com/x/8jWcBw {: .table .table-bordered .table-striped } -| Argument | Prebid Cache Enabled? | Notes | -|------------------------------------------------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options.params` object containing query string parameters | Yes | If you set `description_url`, we use that; otherwise this method will automagically build it for you. | -| `options.params` object containing query string parameters | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | -| `options.url` string containing a video ad server URL | Yes | DOES NOT WORK (?) according to https://corpwiki.appnexus.com/x/8jWcBw - or is it simply the case that the bidder must provide `bid.vastUrl` (as below)? | -| `options.url` string containing a video ad server URL | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | - - +| Argument | Prebid Cache Enabled? | Notes | +|---------------------------------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------| +| `options.params` only | Yes | If you set `description_url`, we use that; otherwise this method will automagically build it for you. | +| `options.params` only | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | +| `options.params` and `options.url` together | Yes | DOES NOT WORK (?) according to https://corpwiki.appnexus.com/x/8jWcBw - or is it simply the case that the bidder must provide `bid.vastUrl` (as below)? | +| `options.params` and `options.url` together | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | From 0fdbc7976387cd143db6d46601d03aed1907dfaf Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 8 Nov 2017 15:47:43 -0500 Subject: [PATCH 3/5] More Prebid Cache / `options.url` interactions (Also: some edits for brevity/clarity/etc.) --- dev-docs/publisher-api-reference.md | 71 ++++++++++++++++------------- 1 file changed, 39 insertions(+), 32 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 17dde555ad..77baef7411 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -1232,24 +1232,29 @@ unsubscribe(); // no longer listening ### pbjs.adServers.dfp.buildVideoUrl(options) ⇒ `String` {: .alert.alert-info :} -This method was added in [0.26.0](https://github.com/prebid/Prebid.js/releases/tag/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 built by combining publisher-provided URL parameters with Prebid.js key-values. The ad tag URL calls DFP, letting `options.bid` (or the auction's winning bid for this ad unit, if undefined) compete alongside the rest of the demand in DFP. +This method returns a DFP video ad tag URL. The tag is built by combining publisher-provided parameters with Prebid.js targeting parameters, and then used by your video player. -+ [Examples](#buildVideoUrl-example-usage): Code samples showing how to call it. -+ [The `options` object](#buildVideoUrl-options-object): Field definitions on the `options` argument. -+ [The `options.params` object](#buildVideoUrl-options-params): Field definitions on the `options.params` sub-object. -+ [Usage scenarios and expected behavior](#buildVideoUrl-usage-scenarios-and-expected-behavior): How the method's different arguments interact with each other and Prebid Cache usage. +For a longer 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). + +For more information, see the sections below. + ++ [Examples](#buildVideoUrl-example-usage): *Code samples showing how to build a video ad tag URL*. ++ [The `options` object](#buildVideoUrl-options-object): *Field definitions for the method's only argument*. ++ [The `options.params` object](#buildVideoUrl-options-params): *Field definitions for the `options.params` sub-object*. ++ [Usage scenarios and expected behavior](#buildVideoUrl-usage-scenarios-and-expected-behavior): *How the method's different arguments interact with each other and your (optional) usage of the Prebid Cache*. #### Examples -In this example, we use `options.params`, and have Prebid Cache enabled: +In this example, we use the [`options.params`](#buildVideoUrl-options-params) argument to build up the ad tag: ```javascript -/* Prebid Cache is enabled in this example. See table in section -above for how turning it off affects usage. */ +/* Prebid Cache is enabled in this example. See elsewhere in this +section for how turning it off affects the usage of +`dfp.buildVideoUrl`. */ pbjs.setConfig({ usePrebidCache: true }); @@ -1280,7 +1285,7 @@ This call returns the following DFP video ad tag URL: 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 ``` -In this example, we are using `options.url` to pass in the video ad server directly: +In this example, we use the [`options.url`](#buildVideoUrl-options-object) argument to pass in the video ad server directly: ```javascript var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' @@ -1315,15 +1320,12 @@ The `options` object has the following fields: The `options.params` object contains the parameters needed to form a URL which hits the [DFP API](https://support.google.com/dfp_premium/answer/1068325?hl=en). It has the following fields: -FIXME: is "arbitraryKey" still supported? not seeing anything explicitly mentioning it in the code at a glance, but may have missed it. It's also not mentioned in the JSDoc. - {: .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. Any key-values given here will be merged with Prebid.js' 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"` | -| `description_url` | string | (Optional) Describes the video. Required for Ad Exchange. Prebid.js will build this for you unless you pass it explicitly. +| 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 merged with Prebid's targeting values and sent to DFP on the video ad tag URL. For more information, see the [DFP docs on `cust_params`](https://support.google.com/dfp_premium/answer/1068325?hl=en#cust_params) | `{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. | | {: .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. @@ -1334,23 +1336,28 @@ For more information about the options supported by the DFP API, see [the DFP AP #### Usage scenarios and expected behavior -Your (optional) usage of Prebid Cache, a server-side asset cache hosted by Prebid.org, may change how the method is used, and how bidders are required to respond, depending on the argument type ([`options.params`](#options-params-argument), [`options.url`](#options-url-argument)), or both. For more information, see [Example Usage](#buildVideoUrl-example-usage) and [Usage scenarios and expected behavior](#buildVideoUrl-usage-scenarios-and-expected-behavior). - -Reasons you might pass the `options.url` field include the following use cases: -- You are not using an ad server, and you want to insert the winning VAST content into your player directly -- You are using a video ad server that can accept a standalone VAST URL, as opposed to having to pass the VAST URL as a query string parameter +How you call `dfp.buildVideoUrl` may change depending on: ++ Whether you pass in query string parameters via `options.params`, the ad server URL via `options.url`, or both. ++ Whether you choose to use Prebid Cache, a server-side asset cache hosted by Prebid.org. -The table below lists the expected behavior of this method when called with various configurations. +Reasons you might pass the `options.url` field include: -FIXME: In the PR comment (https://github.com/prebid/Prebid.js/pull/1663) options.params with cache DISABLED is not mentioned. Does it work? +- You are not using an ad server, and you want to insert the winning VAST content into your player directly +- You are using a video ad server that can accept a standalone VAST URL, as opposed to having to pass the VAST URL as a query string parameter -FIXME: are updates to video bidder adapter docs required? e.g., to note that they must always supply a vastUrl as described at https://corpwiki.appnexus.com/x/8jWcBw +The table below lists the expected behavior of this method when called with various combinations of arguments and cache usage. {: .table .table-bordered .table-striped } -| Argument | Prebid Cache Enabled? | Notes | -|---------------------------------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options.params` only | Yes | If you set `description_url`, we use that; otherwise this method will automagically build it for you. | -| `options.params` only | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | -| `options.params` and `options.url` together | Yes | DOES NOT WORK (?) according to https://corpwiki.appnexus.com/x/8jWcBw - or is it simply the case that the bidder must provide `bid.vastUrl` (as below)? | -| `options.params` and `options.url` together | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. | +| Argument | Prebid Cache Enabled? | Notes | +|------------------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `options.params` only | Yes | None. | +| `options.params` only | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | +| `options.params` and `options.url` | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | +| `options.params` and `options.url` | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | +| `options.url` only | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | +| `options.url` only | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. Prebid sets `description_url` to `bid.vastUrl`. | + +{: .alert.alert-info :} +**Bid Responses and Prebid Cache** +Video bidders must supply either `bid.vastUrl` or `bid.vastXml`. They may supply both. If the video bidder supplies *only* `bid.vastXml` and Prebid Cache is disabled, this will not work and the bid will be dropped from the auction (if Prebid Cache is enabled, this same scenario is fine). If a video bidder supplies neither `bid.vastUrl` or `bid.vastXml`, the bid is dropped. From c80d0300c4adce3f081b1d6de2081bb2592be853 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 8 Nov 2017 15:49:33 -0500 Subject: [PATCH 4/5] Re-order table entries for easier scanning --- dev-docs/publisher-api-reference.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 77baef7411..d46a0c6d7b 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -1353,10 +1353,10 @@ The table below lists the expected behavior of this method when called with vari |------------------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `options.params` only | Yes | None. | | `options.params` only | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | -| `options.params` and `options.url` | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | -| `options.params` and `options.url` | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | | `options.url` only | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | | `options.url` only | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. Prebid sets `description_url` to `bid.vastUrl`. | +| `options.params` and `options.url` | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | +| `options.params` and `options.url` | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | {: .alert.alert-info :} **Bid Responses and Prebid Cache** From 4de2282494e3f8cabe36798419c5c2bf8894e554 Mon Sep 17 00:00:00 2001 From: Rich Loveland Date: Wed, 15 Nov 2017 16:04:58 -0500 Subject: [PATCH 5/5] Revise based on feedback --- dev-docs/publisher-api-reference.md | 151 ++++++++++------------------ 1 file changed, 53 insertions(+), 98 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index d46a0c6d7b..3eec62b748 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -45,7 +45,7 @@ This page has documentation for the public API methods of Prebid.js. * [.aliasBidder(adapterName, aliasedName)](#module_pbjs.aliasBidder) * [.setConfig(options)](#module_pbjs.setConfig) * [.getConfig([string])](#module_pbjs.getConfig) - * [.adServers.dfp.buildVideoUrl(options)](#module_pbjs.adServers.dfp.buildVideoUrl) ⇒ `String` + * [.adServers.dfp.buildVideoUrl(options)](#module_pbjs.adServers.dfp.buildVideoUrl) @@ -344,7 +344,6 @@ Returns a bool if all the bids have returned or timed out
- ### pbjs.enableSendAllBids() @@ -472,6 +471,7 @@ pbjs.setPriceGranularity(customConfigObject); ### pbjs.renderAd(doc, id) + This function will render the ad (based on params) in the given iframe document passed through. Note that doc SHOULD NOT be the parent document page as we can't doc.write() asynchronously. This function is usually used in the ad server's creative. **Kind**: static method of [pbjs](#module_pbjs) @@ -489,6 +489,7 @@ This function will render the ad (based on params) in the given iframe document ### pbjs.removeAdUnit(adUnitCode) + Remove adUnit from the pbjs configuration **Kind**: static method of [pbjs](#module_pbjs) @@ -505,6 +506,7 @@ Remove adUnit from the pbjs configuration ### pbjs.requestBids(requestObj) + Request bids. When `adUnits` or `adUnitCodes` are not specified, request bids for all ad units added. **Kind**: static method of [pbjs](#module_pbjs) @@ -731,7 +733,6 @@ pbjs.bidderSettings = { {% endhighlight %} - ##### 2.3. bidCpmAdjustment Some bidders return gross prices instead of the net prices (what the publisher will actually @@ -757,7 +758,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 @@ -960,10 +960,9 @@ Example use: pbjs.setBidderSequence('fixed'); /* defaults to 'random' as of 0.27.0 */ ``` - +
-

-

+ ### pbjs.onEvent(event, handler, id) @@ -1045,6 +1044,8 @@ The example below shows how to use these methods: {% endhighlight %} +
+ ### pbjs.enableAnalytics(config) @@ -1055,6 +1056,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) @@ -1078,6 +1081,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) @@ -1194,6 +1199,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]) @@ -1227,38 +1234,50 @@ 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](https://github.com/prebid/Prebid.js/releases/tag/0.26.0). -This method returns a DFP video ad tag URL. The tag is built by combining publisher-provided parameters with Prebid.js targeting parameters, and then used by your video player. +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. -For a longer 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). +#### Argument Reference -For more information, see the sections below. +##### The `options` object -+ [Examples](#buildVideoUrl-example-usage): *Code samples showing how to build a video ad tag URL*. -+ [The `options` object](#buildVideoUrl-options-object): *Field definitions for the method's only argument*. -+ [The `options.params` object](#buildVideoUrl-options-params): *Field definitions for the `options.params` sub-object*. -+ [Usage scenarios and expected behavior](#buildVideoUrl-usage-scenarios-and-expected-behavior): *How the method's different arguments interact with each other and your (optional) usage of the Prebid Cache*. +{: .table .table-bordered .table-striped } +| 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 + +{: .table .table-bordered .table-striped } +| 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` | + +For more information on any of these params, see [the DFP video tag documentation](https://support.google.com/dfp_premium/answer/1068325?hl=en). #### Examples -In this example, we use the [`options.params`](#buildVideoUrl-options-params) argument to build up the ad tag: +There are several different ways to build up your video URL, as shown in the examples below: -```javascript -/* Prebid Cache is enabled in this example. See elsewhere in this -section for how turning it off affects the usage of -`dfp.buildVideoUrl`. */ -pbjs.setConfig({ - usePrebidCache: true -}); +Using `options.params` only: +```javascript pbjs.requestBids({ bidsBackHandler: function(bids) { var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ @@ -1270,8 +1289,8 @@ pbjs.requestBids({ anotherKey: "anotherValue" }, hl: "en", - output: "vast", - url: "http://www.referer-url.com" + output: "xml_vast2", + url: "http://www.example.com", } }); invokeVideoPlayer(videoUrl); @@ -1279,85 +1298,21 @@ pbjs.requestBids({ }); ``` -This call returns the following DFP video ad tag URL: - -``` -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 -``` - -In this example, we use the [`options.url`](#buildVideoUrl-options-object) argument to pass in the video ad server directly: +Using `options.url` only: ```javascript var adserverTag = 'https://pubads.g.doubleclick.net/gampad/ads?' -+ 'sz=640x480&iu=/19968336/prebid_video_adunit&impl=s&gdfp_req=1' -+ '&env=vp&output=xml_vast2&correlator=' + Date.now(); - ++ '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 }); ``` - - - - -#### The `options` object - -The `options` object has the following fields: - -{: .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. 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`. | - - - -#### The `options.params` object - -The `options.params` object contains the parameters needed to form a URL which hits the [DFP API](https://support.google.com/dfp_premium/answer/1068325?hl=en). It has the following fields: - -{: .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 merged with Prebid's targeting values and sent to DFP on the video ad tag URL. For more information, see the [DFP docs on `cust_params`](https://support.google.com/dfp_premium/answer/1068325?hl=en#cust_params) | `{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. | | - -{: .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 about the options supported by the DFP API, see [the DFP API docs](https://support.google.com/dfp_premium/answer/1068325?hl=en#env). - - - -#### Usage scenarios and expected behavior - -How you call `dfp.buildVideoUrl` may change depending on: - -+ Whether you pass in query string parameters via `options.params`, the ad server URL via `options.url`, or both. -+ Whether you choose to use Prebid Cache, a server-side asset cache hosted by Prebid.org. - -Reasons you might pass the `options.url` field include: - -- You are not using an ad server, and you want to insert the winning VAST content into your player directly -- You are using a video ad server that can accept a standalone VAST URL, as opposed to having to pass the VAST URL as a query string parameter - -The table below lists the expected behavior of this method when called with various combinations of arguments and cache usage. - -{: .table .table-bordered .table-striped } -| Argument | Prebid Cache Enabled? | Notes | -|------------------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `options.params` only | Yes | None. | -| `options.params` only | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | -| `options.url` only | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | -| `options.url` only | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. Prebid sets `description_url` to `bid.vastUrl`. | -| `options.params` and `options.url` | Yes | Prebid attaches the bid's adserver targeting and rebuilds the URL based on the input by merging publisher input with default values. It does not set `description_url` to `bid.vastUrl`. | -| `options.params` and `options.url` | No | Bidder's response must contain `bid.vastUrl` for video ad to serve. | +{: .alert.alert-warning :} +In the event of collisions, querystring values passed via `options.params` take precedence over those passed via `options.url`. -{: .alert.alert-info :} -**Bid Responses and Prebid Cache** -Video bidders must supply either `bid.vastUrl` or `bid.vastXml`. They may supply both. If the video bidder supplies *only* `bid.vastXml` and Prebid Cache is disabled, this will not work and the bid will be dropped from the auction (if Prebid Cache is enabled, this same scenario is fine). If a video bidder supplies neither `bid.vastUrl` or `bid.vastXml`, the bid is dropped. +