From 38a5ac30665a1facc212f4057b7d2cdb1bca5f50 Mon Sep 17 00:00:00 2001 From: Matt Lane Date: Tue, 9 Jan 2018 15:45:34 -0800 Subject: [PATCH 1/5] Add multiformat ad unit information --- dev-docs/publisher-api-reference.md | 68 +++++++++++++++++++++++++++-- 1 file changed, 64 insertions(+), 4 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index d8ce356c42..deb95b33be 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -566,7 +566,7 @@ See the table below for the list of properties on the ad unit. For example ad u | `code` | Required | String | Unique identifier that you create and assign to this ad unit. Used to set query string targeting on the ad. If using GPT, we recommend setting this to slot element ID. | | `sizes` | Required | Array[Number] or Array[Array[Number]] | All the sizes that this ad unit can accept. Examples: `[400, 600]`, `[[300, 250], [300, 600]]`. For 1.0 and later, prefer [`mediaTypes.banner.sizes`](#adUnit-banner). | | `bids` | Required | Array[Object] | Each bid represents a request to a bidder. For a list of properties, see [Bids](#addAdUnits-Bids) below. | -| `mediaTypes` | Optional | Object | Defines the media type of the ad. For a list of properties, see [Media Types](#addAdUnits-MediaTypes) below. | +| `mediaTypes` | Optional | Object | Defines one or multiple media types the ad unit supports. For a list of properties, see [Media Types](#addAdUnits-MediaTypes) below. | | `labelAny` | optional | array | An array of string labels, used for showing responsive ads. With the `labelAny` operator, just one label has to match for the condition to be true. Works with the `sizeConfig` object passed in to [pbjs.setConfig]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setConfig). | | `labelAll` | optional | array | An array of string labels, used for showing responsive and conditional ads. With the `labelAll` conditional, every element of the target array must match an element of the label array in order for the condition to be true. Works with the `sizeConfig` object passed in to [pbjs.setConfig]({{site.baseurl}}/dev-docs/publisher-api-reference.html#module_pbjs.setConfig). | @@ -594,9 +594,9 @@ See the table below for the list of properties in the `mediaTypes` object of the {: .table .table-bordered .table-striped } | Name | Scope | Type | Description | |----------+--------------------------------------------------------------+--------+--------------------------------------------------------------------------------------------------------------------| -| `native` | Required, unless either of the other properties are present. | Object | Defines properties of a native ad. For an example native ad unit, see [the native example below](#adUnit-native). | -| `video` | Required, unless either of the other properties are present. | Object | Defines properties of a video ad. For examples, see [the video examples below](#adUnit-video). | -| `banner` | Required, unless either of the other properties are present. | Object | Defines properties of a banner ad. For examples, see [the banner example below](#adUnit-banner). | +| `native` | optional | Object | Defines properties of a native ad. For an example native ad unit, see [the native example below](#adUnit-native). | +| `video` | optional | Object | Defines properties of a video ad. For examples, see [the video examples below](#adUnit-video). | +| `banner` | optional. If no other properties are specified, this is the default | Object | Defines properties of a banner ad. For examples, see [the banner example below](#adUnit-banner). | @@ -605,6 +605,7 @@ See the table below for the list of properties in the `mediaTypes` object of the + [Native](#adUnit-native) + [Video](#adUnit-video) + [Banner](#adUnit-banner) ++ [Multi-format](#adUnit-multiformat) @@ -724,6 +725,65 @@ pbjs.addAdUnits({ }) ``` + + +##### Multi-format + +Multiple media formats may be declared on a single ad unit, allowing any bidder that supports at least one of those media formats to participate in the auction. Any bidder that isn't compatible with the specified `mediaTypes` will be dropped from the ad unit. If `mediaTypes` is not specified on an ad unit, `banner` is the assumed format and any banner bidder is eligible for inclusion. + +For examples of a multi-format ad units and behavior, see below. + +```javascript +// each bidder supports at least one of the formats, so all will participate +pbjs.addAdUnits({ + code: 'div-banner-outstream-native', + mediaTypes: { + banner: {}, + native: {}, + video: {context: 'outstream'}, + }, + bids: [ + { + bidder: 'bannerBidder', + params: {placementId: '481'} + }, + { + bidder: 'nativeBidder', + params: {titleAsset: '516'} + }, + { + bidder: 'videoBidder', + params: {vidId: '234'} + }, + ] +}); +``` + +```javascript +// only nativeBidder and videoBidder will participate +pbjs.addAdUnits({ + code: 'div-native-outstream', + mediaTypes: { + native: {}, + video: {context: 'outstream'}, + }, + bids: [ + { + bidder: 'bannerBidder', + params: {placementId: '481'} + }, + { + bidder: 'nativeBidder', + params: {titleAsset: '516'} + }, + { + bidder: 'videoBidder', + params: {vidId: '234'} + }, + ] +}); +``` +
From 418e3a0e7b28a0cb655e9af8a837933149b4129b Mon Sep 17 00:00:00 2001 From: Matt Lane Date: Tue, 9 Jan 2018 15:49:02 -0800 Subject: [PATCH 2/5] Update default targeting keys --- dev-docs/publisher-api-reference.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index deb95b33be..3b728b3759 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -863,7 +863,7 @@ per adapter as needed. Both scenarios are described below. **Keyword targeting for all bidders** -The below code snippet is the *default* setting for ad server targeting. For each bidder's bid, Prebid.js will set 5 keys (`hb_bidder`, `hb_adid`, `hb_pb`, `hb_size`, `hb_source`) with their corresponding values. The key value pair targeting is applied to the bid's corresponding ad unit. Your ad ops team will have the ad server's line items target these keys. +The below code snippet is the *default* setting for ad server targeting. For each bidder's bid, Prebid.js will set 6 keys (`hb_bidder`, `hb_adid`, `hb_pb`, `hb_size`, `hb_source`, `hb_mediatype`) with their corresponding values. The key value pair targeting is applied to the bid's corresponding ad unit. Your ad ops team will have the ad server's line items target these keys. If you'd like to customize the key value pairs, you can overwrite the settings as the below example shows. *Note* that once you updated the settings, let your ad ops team know about the change, so they can update the line item targeting accordingly. See the [Ad Ops](../adops.html) documentation for more information. @@ -902,6 +902,11 @@ pbjs.bidderSettings = { val: function (bidResponse) { return bidResponse.source; } + }, { + key: 'hb_mediatype', + val: function (bidResponse) { + return bidResponse.mediaType; + } }] } } From c7fe6a18443d9f8566e0a49417b84e8f9ee867f3 Mon Sep 17 00:00:00 2001 From: Matt Lane Date: Fri, 12 Jan 2018 08:29:08 -0800 Subject: [PATCH 3/5] Update based on review feedback --- dev-docs/publisher-api-reference.md | 19 +++++++++++++------ 1 file changed, 13 insertions(+), 6 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 3b728b3759..d2f3dc42fc 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -594,9 +594,9 @@ See the table below for the list of properties in the `mediaTypes` object of the {: .table .table-bordered .table-striped } | Name | Scope | Type | Description | |----------+--------------------------------------------------------------+--------+--------------------------------------------------------------------------------------------------------------------| +| `banner` | optional. If no other properties are specified, this is the default | Object | Defines properties of a banner ad. For examples, see [the banner example below](#adUnit-banner). | | `native` | optional | Object | Defines properties of a native ad. For an example native ad unit, see [the native example below](#adUnit-native). | | `video` | optional | Object | Defines properties of a video ad. For examples, see [the video examples below](#adUnit-video). | -| `banner` | optional. If no other properties are specified, this is the default | Object | Defines properties of a banner ad. For examples, see [the banner example below](#adUnit-banner). | @@ -738,9 +738,16 @@ For examples of a multi-format ad units and behavior, see below. pbjs.addAdUnits({ code: 'div-banner-outstream-native', mediaTypes: { - banner: {}, - native: {}, - video: {context: 'outstream'}, + banner: { sizes: [[300, 250], [300, 600]] }, + native: { + title: {required: true}, + image: {required: true}, + body: {required: false}, + }, + video: { + context: 'outstream', + playerSize: [400, 600], + }, }, bids: [ { @@ -764,8 +771,8 @@ pbjs.addAdUnits({ pbjs.addAdUnits({ code: 'div-native-outstream', mediaTypes: { - native: {}, - video: {context: 'outstream'}, + native: { type: 'image' }, + video: { context: 'outstream', playerSize: [400, 600] }, }, bids: [ { From 3918514d79bbe1d50c713c17fbed76682ad00a6e Mon Sep 17 00:00:00 2001 From: Matt Lane Date: Mon, 22 Jan 2018 09:58:13 -0800 Subject: [PATCH 4/5] Change key to hb_format --- dev-docs/publisher-api-reference.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index d2f3dc42fc..602757cb3f 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -14,7 +14,7 @@ pid: 10 This page has documentation for the public API methods of Prebid.js. {: .alert.alert-danger :} -Methods marked as deprecated will be removed in version 1.0 (scheduled for release Q4 2017). +Methods marked as deprecated will be removed in version 1.0 (scheduled for release Q4 2017). After a transition period, documentation for these methods will be removed from Prebid.org (likely early 2018). @@ -870,7 +870,7 @@ per adapter as needed. Both scenarios are described below. **Keyword targeting for all bidders** -The below code snippet is the *default* setting for ad server targeting. For each bidder's bid, Prebid.js will set 6 keys (`hb_bidder`, `hb_adid`, `hb_pb`, `hb_size`, `hb_source`, `hb_mediatype`) with their corresponding values. The key value pair targeting is applied to the bid's corresponding ad unit. Your ad ops team will have the ad server's line items target these keys. +The below code snippet is the *default* setting for ad server targeting. For each bidder's bid, Prebid.js will set 6 keys (`hb_bidder`, `hb_adid`, `hb_pb`, `hb_size`, `hb_source`, `hb_format`) with their corresponding values. The key value pair targeting is applied to the bid's corresponding ad unit. Your ad ops team will have the ad server's line items target these keys. If you'd like to customize the key value pairs, you can overwrite the settings as the below example shows. *Note* that once you updated the settings, let your ad ops team know about the change, so they can update the line item targeting accordingly. See the [Ad Ops](../adops.html) documentation for more information. @@ -910,7 +910,7 @@ pbjs.bidderSettings = { return bidResponse.source; } }, { - key: 'hb_mediatype', + key: 'hb_format', val: function (bidResponse) { return bidResponse.mediaType; } @@ -1117,7 +1117,7 @@ For an example showing how to use this method, see [Show Video Ads with a DFP Vi This method is deprecated as of version 0.27.0 and will be removed in version 1.0 (scheduled for release Q4 2017). Please use [`setConfig`](#module_pbjs.setConfig) instead. {: .alert.alert-danger :} -**BREAKING CHANGE** +**BREAKING CHANGE** As of version 0.27.0, To encourage fairer auctions, Prebid will randomize the order bidders are called by default. To replicate legacy behavior, call `pbjs.setBidderSequence('fixed')`. This method shuffles the order in which bidders are called. @@ -1305,9 +1305,9 @@ pbjs.setConfig({ bidderTimeout: 3000 }); {% endhighlight %} {: .alert.alert-warning :} -**Bid Timeouts and JavaScript Timers** -Note that it's possible for the timeout to be triggered later than expected, leading to a bid participating in the auction later than expected. This is due to how [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) works in JS: it queues the callback in the event loop in an approximate location that *should* execute after this time but *it is not guaranteed*. -With a busy page load, bids can be included in the auction even if the time to respond is greater than the timeout set by Prebid.js. However, we do close the auction immediately if the threshold is greater than 200ms, so you should see a drop off after that period. +**Bid Timeouts and JavaScript Timers** +Note that it's possible for the timeout to be triggered later than expected, leading to a bid participating in the auction later than expected. This is due to how [`setTimeout`](https://developer.mozilla.org/en-US/docs/Web/API/WindowOrWorkerGlobalScope/setTimeout) works in JS: it queues the callback in the event loop in an approximate location that *should* execute after this time but *it is not guaranteed*. +With a busy page load, bids can be included in the auction even if the time to respond is greater than the timeout set by Prebid.js. However, we do close the auction immediately if the threshold is greater than 200ms, so you should see a drop off after that period. For more information about the asynchronous event loop and `setTimeout`, see [How JavaScript Timers Work](https://johnresig.com/blog/how-javascript-timers-work/). @@ -1433,7 +1433,7 @@ However, there are also good reasons why publishers may want to control the use - *Security*: Publishers may want to control which bidders are trusted to inject images and JavaScript into their pages. {: .alert.alert-info :} -**User syncing default behavior** +**User syncing default behavior** If you don't tweak any of the settings described in this section, the default behavior of Prebid.js is to wait 3 seconds after the auction ends, and then allow every adapter to drop up to 5 image-based user syncs. For more information, see the sections below. @@ -1812,7 +1812,7 @@ 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 From 5d32eabad3ff21728ef16378e1e1deb9147b5f66 Mon Sep 17 00:00:00 2001 From: Matt Lane Date: Tue, 23 Jan 2018 10:14:50 -0800 Subject: [PATCH 5/5] Add note about including banner media type if supported --- dev-docs/bidder-adaptor.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/dev-docs/bidder-adaptor.md b/dev-docs/bidder-adaptor.md index 258b640e01..a6ec1fcab9 100644 --- a/dev-docs/bidder-adaptor.md +++ b/dev-docs/bidder-adaptor.md @@ -208,9 +208,9 @@ Sample array entry for `validBidRequests[]`: {% endhighlight %} {: .alert.alert-success :} -There are several IDs present in the bidRequest object: -- **Bid ID** is unique across ad units and bidders. -- **Auction ID** is unique per call to `requestBids()`, but is the same across ad units. +There are several IDs present in the bidRequest object: +- **Bid ID** is unique across ad units and bidders. +- **Auction ID** is unique per call to `requestBids()`, but is the same across ad units. - **Transaction ID** is unique for each ad unit with a call to `requestBids`, but same across bidders. This is the ID that DSPs need to recognize the same impression coming in from different supply sources. The ServerRequest objects returned from your adapter have this structure: @@ -336,6 +336,9 @@ export const spec = { {% endhighlight %} +{: .alert.alert-info :} +If your adapter supports banner and video media types, make sure to include `'banner'` in the `supportedMediaTypes` array as well + ### Step 2: Accept video parameters and pass them to your server Video parameters are often passed in from the ad unit in a `video` object.