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

include a renderer for a specific mediaType #2343

Merged
merged 5 commits into from
Nov 5, 2020
Merged

include a renderer for a specific mediaType #2343

Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
5d5d5e5
add documentation noting that you can include the renderer for a spec…
msperone Sep 16, 2020
9da2e8a
Merge pull request #1 from prebid/master
MikeSperone Sep 16, 2020
08aff62
Merge branch 'master' into mediaType-renderers
bretg Oct 14, 2020
c90629f
Merge remote-tracking branch 'origin/master' into mediaType-renderers
msperone Nov 4, 2020
f128640
Show mediaType renderer is preferred.
msperone Nov 4, 2020
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
59 changes: 28 additions & 31 deletions dev-docs/show-outstream-video-ads.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
bretg marked this conversation as resolved.
Show resolved Hide resolved
nav_section: prebid-video
sidebarType: 4
---

Expand Down Expand Up @@ -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',
Copy link
Collaborator

Choose a reason for hiding this comment

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

i think we should make this an example of the new "preferred" way and remove this altogether? what do you think

Copy link
Collaborator

Choose a reason for hiding this comment

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

also I would change line 171 to refer to your pull request, 5760

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:
Expand All @@ -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

Expand Down