From 623ca7a58ce3274e500dd5ab30083b86d3b72384 Mon Sep 17 00:00:00 2001 From: bretg Date: Wed, 24 Feb 2021 14:18:33 -0500 Subject: [PATCH 1/2] added ignoreBidderCacheKey docs --- _includes/adops/adops-gam-video-setup.html | 18 ++++++++++++---- adops/send-all-bids-adops.md | 2 +- dev-docs/publisher-api-reference.md | 24 +++++++++++++++++++--- 3 files changed, 36 insertions(+), 8 deletions(-) diff --git a/_includes/adops/adops-gam-video-setup.html b/_includes/adops/adops-gam-video-setup.html index aee18dea07..8cd49fed04 100644 --- a/_includes/adops/adops-gam-video-setup.html +++ b/_includes/adops/adops-gam-video-setup.html @@ -36,19 +36,20 @@

Line Item Setup

Be sure to duplicate your line item and video creative for each Prebid price bucket you intend to create.

By default, Prebid.js caps all CPMs at $20. As a video seller, you may expect to see CPMs higher than $20. In order to receive those bids, you’ll need to make sure your dev team implements custom price buckets as described in the engineering setup instructions. Once those changes are made on the engineering side, there should be no changes required from the ad ops side to support CPMs over $20.

-

Multiple Cache Services
You might need separate video line items for each cache service being used. For example, if both AppNexus and Rubicon Project are bidders, you’ll either need to create separate line items to support the different cache URLs required or provide separately-targeted creatives, as described below.

-

Creative Setup

When setting up video creatives, it's important to understand where the VAST XML is stored for each of your bidders. The most common place to store VAST XML is AppNexus' cache, but some bidders (such as RubiconProject and SpotX) use their own cache services. To support such -bidders, you will need to have either: +bidders, you will need to choose an approach:

Single Cache Location

+If you only use bidders that provide full VAST responses, no special setup is needed. +

1. For each line item you create, click on the Creatives tab, click the ADD CREATIVE button, and choose the size you're entering.

2. In the dialog that appears, choose Redirect.

@@ -71,7 +72,7 @@

Single Cache Location

Prebid Cache and the VAST creative URL warning
Google Ad Manager will show you a warning stating that fetching VAST from the creative - URL failed. This is expected, since the creative URL above points + URL failed. This is expected, since the creative URL above points to a server-side asset cache hosted by Prebid Server.

4. Set the Duration to 1.

@@ -82,6 +83,15 @@

Single Cache Location

Multiple Cache Locations

+If you're utilizing any bidders that cache their own VAST, you have two options: + + + To set up multiple video creatives in the same line item (i.e., to run AppNexus, Rubicon, and SpotX all together in the same video line item), you can utilize creative targeting.

diff --git a/adops/send-all-bids-adops.md b/adops/send-all-bids-adops.md index 711efcab46..4177600b8c 100644 --- a/adops/send-all-bids-adops.md +++ b/adops/send-all-bids-adops.md @@ -29,7 +29,7 @@ See the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-refere + Your developers may optionally add `enableSendAllBids: true` to `pbjs.setConfig()`. This is not strictly necessary, as `enableSendAllBids` defaults to `true`. For details, see the [Publisher API Reference]({{site.baseurl}}/dev-docs/publisher-api-reference.html#setConfig-Send-All-Bids). -+ From the ad ops side, you may choose to set up one order per bidder, so that each order can have a set of line items using targeting keywords that include the bidder's name. For example, if you are working with [Rubicon]({{site.baseurl}}/dev-docs/bidders.html#rubicon), you would use `hb_pb_rubicon` in your line item's key-value targeting, and `hb_adid_rubicon` in the creative. ++ From the ad ops side, you may choose to set up one order per bidder, so that each order can have a set of line items using targeting keywords that include the bidder's name. For example, if you are working with [Rubicon](/dev-docs/bidders.html#rubicon), you would use `hb_pb_rubicon` in your line item's key-value targeting, and `hb_adid_rubicon` in the creative. {% include send-all-bids-keyword-targeting.md %} diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index f8d324d3e0..918ba3b8b4 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -2491,11 +2491,18 @@ the JavaScript DOM in Prebid.js, but rather expect to be given a URL where it ca be retrieved. There are two different flows possible with Prebid.js around VAST XML caching: - Server-side caching: - Some video bidders (e.g. Rubicon Project) always cache the VAST XML on their servers as part of the bid. They provide a 'videoCacheKey', which is used in conjunction with the VAST URL in the ad server to retrieve the correct VAST XML when needed. In this case, Prebid.js has nothing else to do. + Some video bidders (e.g. Rubicon Project) always cache the VAST XML on their servers as part of the bid. They provide a 'videoCacheKey', which is used in conjunction with the VAST URL in the ad server to retrieve the correct VAST XML when needed. In this case, Prebid.js has nothing else to do. As of PBJS 4.28, a publisher may specify the `ignoreBidderCacheKey` flag to re-cache these bids somewhere else using a VAST wrapper. - Client-side caching: Video bidders that don't cache on their servers return the entire VAST XML body. In this scenario, Prebid.js needs to copy the VAST XML to a publisher-defined cache location on the network. In this scenario, Prebid.js POSTs the VAST XML to the named Prebid Cache URL. It then sets the 'videoCacheKey' to the key that's returned in the response. -For client-side caching, set the Prebid Cache URL as shown here (substituting the correct URL for the one shown here): +{: .table .table-bordered .table-striped } +| Cache Attribute | Required? | Type | Description | +|----+--------+-----+-------| +| cache.url | yes | string | The URL of the Prebid Cache server endpoint where VAST creatives will be sent. | +| cache.vasttrack | no | boolean | Passes additional data to the url, used for additional event tracking data. Defaults to `false`. | +| cache.ignoreBidderCacheKey | no | boolean | If the bidder supplied their own cache key, setting this value to true: adds a VAST wrapper around that URL, stores it in the cache defined by the `url` parameter, and replaces the original video cache key with the new one. Defaults to `false`. This can dramatically simplify ad server setup because it means all VAST creatives reside behind a single URL. The tradeoff: this approach requires the video player to unwrap one extra level of VAST. | + +Here's an example of basic client-side caching. Substitute your Prebid Cache URL as needed: {% highlight js %} pbjs.setConfig({ @@ -2508,6 +2515,17 @@ pbjs.setConfig({ {: .alert.alert-warning :} The endpoint URL provided must be a Prebid Cache or be otherwise compatible with the [Prebid Cache interface](https://github.com/prebid/prebid-cache). +As of Prebid.js 4.28, you can specify the `ignoreBidderCacheKey` option: + +{% highlight js %} +pbjs.setConfig({ + cache: { + url: 'https://my-pbs.example.com/cache', + ignoreBidderCacheKey: true + } +}); +{% endhighlight %} + As of Prebid.js 2.36, you can track client-side cached VAST XML. This functionality is useful for publishers who want to allow their analytics provider to measure video impressions. The prerequisite to using this feature is the availability of a Prebid Server that supports: - the /vtrack endpoint @@ -2519,7 +2537,7 @@ Given those conditions, the `vasttrack` flag can be specified: {% highlight js %} pbjs.setConfig({ cache: { - url: '_PREBID_SERVER_URL_/vtrack', + url: 'https://my-pbs.example.com/vtrack', vasttrack: true } }); From a202470333ab4767e40331c3ed37890c90688519 Mon Sep 17 00:00:00 2001 From: Jean Stemp Date: Wed, 24 Feb 2021 16:58:07 -0800 Subject: [PATCH 2/2] edits and some general cleanup --- _includes/adops/adops-gam-video-setup.html | 12 ++++++------ _includes/send-all-bids-keyword-targeting.md | 6 ------ adops/send-all-bids-adops.md | 19 ++++++++++--------- dev-docs/publisher-api-reference.md | 10 +++++----- 4 files changed, 21 insertions(+), 26 deletions(-) diff --git a/_includes/adops/adops-gam-video-setup.html b/_includes/adops/adops-gam-video-setup.html index 8cd49fed04..4583b57ea4 100644 --- a/_includes/adops/adops-gam-video-setup.html +++ b/_includes/adops/adops-gam-video-setup.html @@ -39,16 +39,16 @@

Line Item Setup

Creative Setup

When setting up video creatives, it's important to understand where the VAST XML is stored for each of your bidders. The most common place to store VAST XML is AppNexus' cache, but some bidders (such as RubiconProject and SpotX) use their own cache services. To support such -bidders, you will need to choose an approach: +bidders, you will need to choose one of the following approaches:

Single Cache Location

-If you only use bidders that provide full VAST responses, no special setup is needed. +If you only use bidders that provide full VAST responses, no special setup is needed. Otherwise, do the following:

1. For each line item you create, click on the Creatives tab, click the ADD CREATIVE button, and choose the size you're entering.

@@ -86,7 +86,7 @@

Multiple Cache Locations

If you're utilizing any bidders that cache their own VAST, you have two options: