Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document pbjs.adServers.dfp.buildVideoUrl update to accept ad server URL #422

Merged
merged 5 commits into from
Nov 15, 2017
Merged

Document pbjs.adServers.dfp.buildVideoUrl update to accept ad server URL #422

Changes from 2 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5d2beaf
WIP - draft still too complex
Nov 1, 2017
10ce92c
Further WIP on `dfp.buildVideoUrl`, needs review
Nov 3, 2017
0fdbc79
More Prebid Cache / `options.url` interactions
Nov 8, 2017
c80d030
Re-order table entries for easier scanning
Nov 8, 2017
4de2282
Revise based on feedback
Nov 15, 2017
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
117 changes: 90 additions & 27 deletions dev-docs/publisher-api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1232,47 +1232,37 @@ 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.
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 takes a single `options` object as an argument, described below:
+ [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.

{: .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. |

The `options.params` object is described below:
<a name="buildVideoUrl-example-usage" />

{: .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"` |
#### Examples

{: .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).

#### Example Usage

For a usage example in context, 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 section
above for how turning it off affects usage. */
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"
section: "blog",
anotherKey: "anotherValue"
},
hl: "en",
output: "vast",
Expand All @@ -1290,4 +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
});
```

</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. |
Copy link
Contributor

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.params and Options.url are passed to buildVideoUrl?

Copy link
Collaborator

@matthewlane matthewlane Nov 9, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Right, options.params isn't required, the pub can pass either options.params, options.url, or both, but not neither.

If both params and url are passed in, the url is parsed, and any equivalent params that are present will overwrite those that were present in the url (in other words, in the event of collisions, params takes 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

| 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:

<span style="color: rgb(255,0,0);">FIXME</span>: 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.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As far as I can tell, no. I hadn't seen usage of this before, and it seems like sending custom key-value pairs is covered by the cust_params field, so possibly cust_params is a replacement for that


{: .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.

{: .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

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


The table below lists the expected behavior of this method when called with various configurations.

<span class="FIXME" style="color: rgb(255,0,0);">FIXME</span>: In the PR comment (https://github.com/prebid/Prebid.js/pull/1663) options.params with cache DISABLED is not mentioned. Does it work?
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, if the correct adserver adunit id is used. In our example case, /19968336/prebid_cache_video_adunit is the adunit id used when prebid-cache is enabled, which is correct. If prebid-cache is disabled, that same adunit id will no longer work, but /19968336/prebid_video_adunit will because it is expecting a vast url rather than a prebid-cache key


<span style="color: rgb(255,0,0);">FIXME</span>: are updates to video bidder adapter docs required? e.g., to note that they must always supply a <code>vastUrl</code> as described at https://corpwiki.appnexus.com/x/8jWcBw
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Video bidders must supply either vastUrl or vastXml. They may supply both. If the video bidder supplies only 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 vastUrl or vastXml, the bid is dropped.


{: .table .table-bordered .table-striped }
Copy link
Contributor

@mjacobsonny mjacobsonny Nov 9, 2017 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 |
|---------------------------------------------+-----------------------+---------------------------------------------------------------------------------------------------------------------------------------------------------|
| `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. |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The bidder must contain bid.vastUrl, correct, but if there is also a bid.vastXml it will still work, the xml just wouldn't be used.

| `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)? |
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Correct, Prebid doesn't set a description_url in this case

| `options.params` and `options.url` together | No | Bidder must respond with **only** `bid.vastUrl` - `bid.vastXml` won't work. |