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 all 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
93 changes: 59 additions & 34 deletions dev-docs/publisher-api-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<a name="module_pbjs.getAdserverTargeting"></a>

Expand Down Expand Up @@ -344,7 +344,6 @@ Returns a bool if all the bids have returned or timed out

<hr class="full-rule">


<a name="module_pbjs.enableSendAllBids"></a>

### pbjs.enableSendAllBids()
Expand Down Expand Up @@ -472,6 +471,7 @@ pbjs.setPriceGranularity(customConfigObject);
<a name="module_pbjs.renderAd"></a>

### 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)
Expand All @@ -489,6 +489,7 @@ This function will render the ad (based on params) in the given iframe document
<a name="module_pbjs.removeAdUnit"></a>

### pbjs.removeAdUnit(adUnitCode)

Remove adUnit from the pbjs configuration

**Kind**: static method of [pbjs](#module_pbjs)
Expand All @@ -505,6 +506,7 @@ Remove adUnit from the pbjs configuration
<a name="module_pbjs.requestBids"></a>

### 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)
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -960,10 +960,9 @@ Example use:
pbjs.setBidderSequence('fixed'); /* defaults to 'random' as of 0.27.0 */
```

<a name="module_pbjs.onEvent"></a>
<hr class="full-rule" />

<p>
</p>
<a name="module_pbjs.onEvent"></a>

### pbjs.onEvent(event, handler, id)

Expand Down Expand Up @@ -1045,6 +1044,8 @@ The example below shows how to use these methods:

{% endhighlight %}

<hr class="full-rule" />

<a name="module_pbjs.enableAnalytics"></a>

### pbjs.enableAnalytics(config)
Expand All @@ -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).

<hr class="full-rule" />

<a name="module_pbjs.aliasBidder"></a>

### pbjs.aliasBidder(adapterName, aliasedName)
Expand All @@ -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`

<hr class="full-rule" />

<a name="module_pbjs.setConfig"></a>

### pbjs.setConfig(options)
Expand Down Expand Up @@ -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.

<hr class="full-rule" />

<a name="module_pbjs.getConfig"></a>

### pbjs.getConfig([string])
Expand Down Expand Up @@ -1227,41 +1234,48 @@ unsubscribe(); // no longer listening

{% endhighlight %}

<hr class="full-rule" />

<a name="module_pbjs.adServers.dfp.buildVideoUrl"></a>

### 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 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 returns a DFP video ad tag URL which is built by combining publisher-provided URL parameters with Prebid.js key-values.
#### Argument Reference

This method takes a single `options` object as an argument, described below:
##### 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({
Expand All @@ -1271,23 +1285,34 @@ 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);
}
});
```

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`.

</div>