diff --git a/dev-docs/show-outstream-video-ads.md b/dev-docs/show-outstream-video-ads.md index 450a8cc999..e7021607ee 100644 --- a/dev-docs/show-outstream-video-ads.md +++ b/dev-docs/show-outstream-video-ads.md @@ -3,8 +3,6 @@ layout: page_v2 title: Show Outstream Video Ads description: Show Outstream Video Ads with Prebid.js pid: 10 -top_nav_section: dev_docs -nav_section: prebid-video sidebarType: 4 --- @@ -67,52 +65,51 @@ To display an outstream video, two things are needed: Prebid.js will select the `renderer` used to display the outstream video in the following way: -1. If a `renderer` is associated with the Prebid adUnit, it will be used to display any outstream demand associated with that adUnit. Below, we will provide an example of an adUnit with an associated `renderer`. If that renderer is specified as backup only, it will only be used when no other renderer is found. -2. If no `renderer` is specified on the Prebid adUnit, Prebid will invoke the renderer associated with the winning (or selected) demand partner video bid. Choosing a backup only renderer allows publishers to access demand with or without an attached renderer. +1. If a `renderer` is associated with the Prebid adUnit's video mediaType, it will be used to display any outstream demand associated with that adUnit with a mediaType of "video". (This is the preferred method.) +2. If a `renderer` is associated with the Prebid adUnit, it will be used to display any outstream demand associated with that adUnit. Below, we will provide an example of an adUnit with an associated `renderer`. This is legacy, and number 1 is the preferred way. +3. If no `renderer` is specified on the Prebid adUnit, Prebid will invoke the renderer associated with the winning (or selected) demand partner video bid. {: .alert.alert-warning :} At this time, since not all demand partners return a renderer with their video bid responses, we recommend that publishers associate a `renderer` with their Prebid video adUnits, if possible. By doing so, any Prebid adapter that supports video will be able to provide demand for a given outstream slot. -Renderers are associated with adUnits through the `adUnit.renderer` object. This object contains three fields: +Renderers are associated with adUnits in two ways. +Primarily through the `adUnit.renderer` object. But also, especially for multiFormat adUnits, through the specified mediaType `adUnit.mediaTypes.video.renderer`. +This object contains these fields: 1. `url` -- Points to a file containing the renderer script. 2. `render` -- A function that tells Prebid.js how to invoke the renderer script. 3. `backupOnly` -- Optional field, if set to true, buyer or adapter renderer will be preferred + +In a multiFormat adUnit, you might want the renderer to only apply to only one of the mediaTypes. You can do this by defining the renderer on the media type itself. {% highlight js %} pbjs.addAdUnit({ code: 'video1', + // This renderer would apply to all prebid creatives... + renderer: { + url: 'example.com/publishersCustomRenderer.js', + render: function(bid) { renderAdUnit(...) } + }, mediaTypes: { video: { context: 'outstream', - playerSize: [640, 480] - } - }, - renderer: { - url: 'https://acdn.adnxs.com/video/outstream/ANOutstreamVideo.js', - backupOnly: true, // prefer demand renderer - render: function (bid) { - adResponse = { - ad: { - video: { - content: bid.vastXml, - player_height: bid.playerHeight, - player_width: bid.playerWidth - } - } + playerSize: [640, 480], + // but a renderer passed in here would apply only to this mediaType. + // This renderer would override the above renderer if it exists. + renderer: { + url: 'example.com/videoRenderer.js', + render: function (bid) { renderVideo(...) } } - // push to render queue because ANOutstreamVideo may not be loaded yet. - bid.renderer.push(() => { - ANOutstreamVideo.renderAd({ - targetId: bid.adUnitCode, // target div id to render video. - adResponse: adResponse - }); - }); - } - } + }, + display: { + // With the renderer property excluded here, the display bids would + // use the renderer defined on the adUnit level. + ..., + }, + }, + ... }); - {% endhighlight %} Some demand partners that return a renderer with their video bid responses may support renderer configuration with the `adUnit.renderer.options` object. These configurations are bidder specific and may include options for skippability, player size, and ad text, for example. An example renderer configuration follows: @@ -137,7 +134,7 @@ pbjs.addAdUnit({ {% endhighlight %} -For more technical information about renderers, see [the pull request adding the 'Renderer' type](https://github.com/prebid/Prebid.js/pull/1082) +For more technical information about renderers, see [the pull request originally adding the 'Renderer' type](https://github.com/prebid/Prebid.js/pull/1082) and [the pull request allowing the 'renderer' type in the mediaType](https://github.com/prebid/Prebid.js/pull/5760). ## Step 2: Show ads in the page body