Document pbjs.adServers.dfp.buildVideoUrl update to accept ad server URL
#422
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -1232,47 +1232,42 @@ 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). | ||
|
|
||
| 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. | ||
|
|
||
| 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*. | ||
|
|
||
| <a name="buildVideoUrl-example-usage" /> | ||
|
|
||
| #### Examples | ||
|
|
||
| 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 elsewhere in this | ||
| section for how turning it off affects the usage of | ||
| `dfp.buildVideoUrl`. */ | ||
| pbjs.setConfig({ | ||
| usePrebidCache: true | ||
| }); | ||
|
|
||
| pbjs.requestBids({ | ||
| bidsBackHandler: function(bids) { | ||
| var videoUrl = pbjs.adServers.dfp.buildVideoUrl({ | ||
| adUnit: videoAdUnit, | ||
| params: { | ||
| iu: '/19968336/prebid_cache_video_adunit', | ||
| cust_params: { | ||
| section: "blog", | ||
| anotherKey: "anotherValue" | ||
| }, | ||
| hl: "en", | ||
| output: "vast", | ||
|
|
@@ -1290,4 +1285,79 @@ 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: | ||
|
|
||
| ```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 | ||
| }); | ||
| ``` | ||
|
|
||
| </div> | ||
|
|
||
| <a name="buildVideoUrl-options-object" /> | ||
|
|
||
| #### 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`. | | ||
|
|
||
| <a name="buildVideoUrl-options-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). | ||
|
|
||
| <a name="buildVideoUrl-usage-scenarios-and-expected-behavior" /> | ||
|
|
||
| #### Usage scenarios and expected behavior | ||
|
|
||
| How you call `dfp.buildVideoUrl` may change depending on: | ||
|
There was a problem hiding this comment. I think we need to rework or possibly eliminate this section. Options.params and Options.url are not really intended for distinct sets of use-cases. We allow users to either pass an existing adserver URL or an object containing adserver URL querystring parameters for convenience. |
||
|
|
||
| + 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 } | ||
|
There was a problem hiding this comment. I think we need to figure out how to represent more clearly the information in the table below, as it seems a bit confusing to me at the moment. |
||
| | Argument | Prebid Cache Enabled? | Notes | | ||
|
There was a problem hiding this comment. @matthewlane based on your comment update re: how/when Are the descriptions of what happens in each of these cases correct? There was a problem hiding this comment. @rmloveland One update for the notes in
default values aren't merged in this case, the resulting url is just based off the input url with adserver targeting attached. All other descriptions look good to me |
||
| |------------------------------------+-----------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | ||
| | `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-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. | ||
|
There was a problem hiding this comment. I think we can get rid of the last sentence: "If a video bidder supplies neither |
||
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I don't think that Options.params is required. It should be acceptable to invoke buildVideoUrl with an Options object that contains either the "url" or "params" field.
@matthewlane can we confirm the expected behavior if both
Options.paramsandOptions.urlare passed tobuildVideoUrl?There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Right,
options.paramsisn't required, the pub can pass eitheroptions.params,options.url, or both, but not neither.If both
paramsandurlare passed in, the url is parsed, and any equivalentparamsthat are present will overwrite those that were present in the url (in other words, in the event of collisions,paramstakes precedence). Then everything else that happens when just params were passed in still happens (adding defaults, adserver targeting, etc.), everything is stringified back to a url, and this is returned