diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 746980ae74..75b1560aec 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -1190,145 +1190,194 @@ sbCollapseId: ad-ops - sbSecId: 3 - title: Ad Ops Tutorials + title: Overview link: isHeader: 1 - headerId: adopstuts + headerId: adopsoverview + isSectionHeader: + sectionTitle: + subgroup: 0 + +- sbSecId: 3 + title: 'Ad Ops Overview' + link: /adops/before-you-start.html + isHeader: 0 isSectionHeader: 0 - sectionTitle: Ad Ops + sectionTitle: subgroup: 0 - sbSecId: 3 - title: "Prebid" + title: Ad Ops Essentials + link: + isHeader: 1 + headerId: adopsess + isSectionHeader: 0 + sectionTitle: Ad Ops Essentials + subgroup: 1 + +- sbSecId: 3 + title: "Planning" link: isHeader: 0 isSectionHeader: 0 isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'AdOps View of Prebid' - link: /adops/before-you-start.html + title: 'Planning Guide' + link: /adops/adops-planning-guide.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Prebid Universal Creative' - link: /overview/prebid-universal-creative.html + title: 'Ad Server Integration' + link: /adops/ad-server-integration.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Send All Bids' - link: /adops/send-all-bids-adops.html + title: 'Send All Bids vs Top Price' + link: /adops/send-all-vs-top-price.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Enable Deals' - link: /adops/deals.html - Item: 1 + title: 'Line Item Creation' + link: /adops/line-item-creation.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: "Google Ad Manager" + title: 'Price Granularity' + link: /adops/price-granularity.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 3 + title: 'Creative Considerations' + link: /adops/creative-considerations.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 1 + +- sbSecId: 3 + title: "Ad Ops Information" link: isHeader: 0 isSectionHeader: 0 isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Guide to Prebid in Ad Manager' - link: /adops/step-by-step.html + title: 'Key Values' + link: /adops/key-values.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Setting up for AMP in GAM' - link: /adops/setting-up-prebid-for-amp-in-dfp.html + title: 'Prebid Universal Creative' + link: /overview/prebid-universal-creative.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Setting up Multi-Format in GAM' - link: /adops/setting-up-prebid-multi-format-in-dfp.html + title: 'Deals in Prebid' + link: /adops/deals.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 1 - sbSecId: 3 - title: 'Setting up Native in GAM' - link: /adops/gam-native.html + title: Ad Server Setup + link: + isHeader: 1 + headerId: adopssetup + isSectionHeader: + sectionTitle: + subgroup: 2 + +- sbSecId: 3 + title: "Google Ad Manager" + link: isHeader: 0 isSectionHeader: 0 + isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: 'Setting up Video in GAM' - link: /adops/setting-up-prebid-video-in-dfp.html + title: 'Guide to Prebid in Ad Manager' + link: /adops/step-by-step.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: 'Setting up Long-Form Video in GAM' - link: /adops/setting-up-prebid-ott-video-in-gam.html + title: 'Ad Manager Send All Bids' + link: /adops/send-all-bids-adops.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: "Mobile" - link: + title: 'Setting up for AMP in GAM' + link: /adops/setting-up-prebid-for-amp-in-dfp.html isHeader: 0 isSectionHeader: 0 - isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: Setup Native Ads - link: /prebid-mobile/adops-native-setup.html + title: 'Setting up Multi-Format in GAM' + link: /adops/setting-up-prebid-multi-format-in-dfp.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: Price Granularity - link: /prebid-mobile/adops-price-granularity.html + title: 'Setting up Native in GAM' + link: /adops/gam-native.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: Dr. Prebid Validation App - link: /prebid-mobile/dr-prebid.html + title: 'Setting up Video in GAM' + link: /adops/setting-up-prebid-video-in-dfp.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 + +- sbSecId: 3 + title: 'Setting up Long-Form Video in GAM' + link: /adops/setting-up-prebid-ott-video-in-gam.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 2 - sbSecId: 3 title: "Freewheel" @@ -1337,7 +1386,7 @@ isSectionHeader: 0 isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 title: 'Setting up Long-Form Video' @@ -1345,7 +1394,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 title: "AppNexus Publisher" @@ -1354,7 +1403,7 @@ isSectionHeader: 0 isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 title: 'Setting up Prebid' @@ -1362,17 +1411,16 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 title: "Smart Ad Server" link: - isHeader: 0 isSectionHeader: 0 isCatHeader: 1 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 title: 'Setting up Prebid' @@ -1380,32 +1428,32 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 0 + subgroup: 2 - sbSecId: 3 - title: Studies + title: Optimization link: isHeader: 1 - headerId: studies + headerId: optimization isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 3 - title: Optimize Header Bidding Setup - link: /overview/how-many-bidders-for-header-bidding.html + title: Analyze Header Bidding Setup + link: /overview/optimal-header-bidding-setup.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 3 - title: An Optimal Setup for Header Bidding - link: /overview/optimal-header-bidding-setup.html + title: Optimize Header Bidding Setup + link: /overview/how-many-bidders-for-header-bidding.html isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 + subgroup: 3 - sbSecId: 3 title: Reduce Header Bidding Latency With Prebid.js @@ -1413,15 +1461,7 @@ isHeader: 0 isSectionHeader: 0 sectionTitle: - subgroup: 2 - -- sbSecId: 3 - title: How to Simplify Line Item Setup - link: /overview/how-to-simplify-line-item-setup.html - isHeader: 0 - isSectionHeader: 0 - sectionTitle: - subgroup: 2 + subgroup: 3 #--------------Prebid Video--------------| @@ -1519,7 +1559,7 @@ subgroup: 1 - sbSecId: 4 - title: Integrating Prebid.js with video on your own + title: Integrating Prebid.js with video on your own link: /prebid-video/video-integrating-solo.html isHeader: 0 isSectionHeader: 0 @@ -2356,6 +2396,15 @@ sectionTitle: subgroup: 0 +- sbSecId: 8 + title: Dr. Prebid Validation App + link: /prebid-mobile/dr-prebid.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 0 + + #-------------- Prebid Identity --------------| - sbSecId: 9 diff --git a/adops/ad-server-integration.md b/adops/ad-server-integration.md new file mode 100644 index 0000000000..f4ecdb9696 --- /dev/null +++ b/adops/ad-server-integration.md @@ -0,0 +1,64 @@ +--- +layout: page_v2 +title: Ad Server Integration +head_title: Ad Server Integration +sidebarType: 3 +sbUUID: 3.2 +--- + +# Ad Server Integration +{: .no_toc } + +* TOC +{: toc } + +Before you start your Prebid implementation, you need to have signed on with an ad server. As an independent header bidding solution, Prebid was designed to work with any ad server. One step in determining how your integration is going to work is exploring the type of support your ad server has for header bidding and how you’re going to use it. We’re not able to provide details on all ad servers, but we can give you some general information on the most popular ad servers and those the Prebid community has documented. + +Note that not many ad servers currently have native support for header bidding. This is a reminder to check with your ad server to see what they support directly before you move forward. + +{: .alert.alert-success :} +If you want to include information about a particular ad server not documented here, create a PR in our [Github repo](https://github.com/prebid/prebid.github.io). + +## Google Ad Manager +Google Ad Manager (GAM) is currently the most-used ad server. Google is beta testing header bidding support in yield groups, a technology to help publishers manage external integrations. Because header bidding often involved the creation of hundreds or even thousands of line items, yield groups could be a useful option. Here are some things to consider when deciding whether to use GAM yield groups with Prebid: + +- As of this writing, the feature was still in beta testing. +- You must have a GAM premium GAM account to use yield groups. +- The following use cases currently don’t work with yield groups: Native, video, AMP, Post-Bid. Google is open to feedback from the community about these scenarios. +- The Prebid Universal Creative is not utilized. Google has ported some portions of the PUC to an internal creative. +- Not all Prebid bid adapters are supported. +- Aliases are not currently supported, but Google may eventually support aliases that are commonly used. There may also be future updates to support custom aliases. +- Google Publisher Toolkit (GPT) determines bid values using Prebid.js events. +- The yield group should win when the adjusted bid price is higher than the header bidding price bucket, which should typically occur if the publisher is rounding bids down, as is the Prebid default. +- While we haven’t seen any detailed performance testing, we hope that the improved auction dynamics from no longer using price bucketing will have beneficial effects on auction outcomes. + +For step-by-step instructions on using GAM, see the [Google Ad Manager Step by Step](/adops/step-by-step.html). + + +## Other Ad Servers + +We don’t currently have details on specific header bidding support in other ad servers. But practically speaking, these are the requirements to integrate Prebid into an ad server: + +- The ability to pass key-value pairs into the ad call. + + {: .alert.alert-info :} + See the [getAdserverTargeting function](/dev-docs/publisher-api-reference/getAdserverTargeting.html) for engineering instructions on creating whatever format is required. +- The ability to bulk create orders, line items, and creatives (or the equivalent). Since there can be hundreds - or even thousands - of objects to create, it's uncommon for people to create their ad server objects one-by-one. +- The ability to create hundreds or thousands of objects without exceeding ad server limits. + +For step-by-step instructions on using some of the other ad servers, see the following documentation: + +- [Xandr Monetize Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) +- [Smart Ad Server](/adops/setting-up-prebidjs-with-Smart-Ad-Server.html) +- [FreeWheel](/adops/setting-up-prebid-video-in-freewheel.html) + +## Next Step + +[Send All Bids vs Top Price](/adops/send-all-vs-top-price.html) + +## Further Reader + +- [Planning Guide](/adops/adops-planning-guide.html) +- [Key Values for Ad Ops](/adops/key-values.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) +- [Deals in Prebid](/adops/deals.html) diff --git a/adops/adops-planning-guide.md b/adops/adops-planning-guide.md new file mode 100644 index 0000000000..ce1e45e6ae --- /dev/null +++ b/adops/adops-planning-guide.md @@ -0,0 +1,67 @@ +--- +layout: page_v2 +title: Ad Operations Planning +head_title: Getting Started with Prebid for Header Bidding +sidebarType: 3 +sbUUID: 3.2 +--- + +# Ad Ops Planning Guide +{: .no_toc } + +* TOC +{: toc } + +There are several decisions you need to make as you’re planning out your Prebid implementation. The following diagram guides you through these decisions. Click on the boxes to navigate to detailed information about each one. (See below for an overview of these options.) + +Ad Ops Decisions + + + Ad Server Integration + Send All Bids vs Top Price + Line Item Creation + Price Granularity + Creative Considerations + + + + +{: .alert.alert-success :} +As you go through the steps, we recommend that you document all your decisions. Many of the decisions will need to be made only once when you first set up Prebid, so good documentation will help you and future users understand the decisions and why they were made. + +## Planning Process + +We’ve presented the decision steps in what we believe is a logical order, but you can go in any order that makes sense to you and your implementation. Here is a brief overview of each step so you can decide where to start. + +[Ad Server Integration](/adops/ad-server-integration.html): Determine what type of support your ad server has for header bidding and whether you want to add that into your configuration. + +[Send All Bids vs Top Price](/adops/send-all-vs-top-price.html): You can choose to send all bids that are received from header bidding demand partners, or send only the top bid. Learn the advantages and disadvantages of each. + +[Line Item Creation](/adops/line-item-creation.html): Here we provide you with some general recommendations and requirements for setting up your line items. + +[Price Granularity](/adops/price-granularity.html): The granularity you want in your line item pricing is dependent on your goals, your workload, and more. Learn how to balance everything to get the outcomes you want. + +[Creative Considerations](/adops/creative-considerations.html): Do you want to work with one universal creative, or have many different creatives? Should you use SafeFrames? These and other questions related to working with creatives are addressed here. + +Some additional resources that might be helpful as you work through your setup include: + +[Key Values for Ad Ops](/adops/key-values.html): Your line item setup is dependent on the key-value pairs the ad server receives in the ad request. Learn what key-value pairs are and how they’re used by Prebid, and the coordination required between ads op and engineering to ensure information gets to and from the ad server correctly. + +[Prebid Universal Creative](/overview/prebid-universal-creative.html): Simplify your line item setup with the Prebid Universal Creative. + +[Deals in Prebid](/adops/deals.html): You can negotiate deals with header bidding demand partners and have them compete with ad server inventory. You’ll need to create additional line items to support these deals. This document explains how to set up Prebid to make that happen. + +## Terminology + +Throughout this planning guide, we use the following terms to describe elements within the ad server. These terms may vary among different ad servers. + +**Order**: A container used to group line items that share similar properties. Orders contain information that applies to all line items attached to that order. Prebid integrations are typically set up with at least one order per bidder. + +**Line Item**: Line items contain the details of each bid, such as price, priority, and media format. Each line item has at least one creative attached. + +**Creative**: A creative is the ad that will be displayed in the ad slot if the associated line item wins the auction. In Prebid, creatives are entered in the ad server as an ad tag (or script) with directions to the actual media that will be displayed. + +**Key Value Pair (KVP)**: Additional parameters sent to the ad server to provide additional targeting or reporting information. Prebid sends keys with associated values that enable the ad server to match a line item to the bid and display the winning creative. A key value pair for a Prebid parameter can include things like the bid price or the name of the bidder. See [Key Values](/adops/key-values.html) for more information. + +## Next Step +[Ad Server Integration](/adops/ad-server-integration.html) diff --git a/adops/before-you-start.md b/adops/before-you-start.md index c00642c581..988dc45acc 100644 --- a/adops/before-you-start.md +++ b/adops/before-you-start.md @@ -6,126 +6,27 @@ sidebarType: 3 sbUUID: 3.2 --- - - # Ad Ops and Prebid {: .no_toc } -Prebid products are designed to integrate with the ad ops line item configuration on the publisher's selected ad server. Whether using Prebid.js, Prebid Server or Prebid Mobile, bid targeting parameters are passed to the ad server. The ad server then attempts to match the targeting parameters to a preset line item. If successful, that line item is compared to other line items and if the Prebid bid wins the auction, the creative is returned to the web page or app for display. - -{% capture importantNote %} -This page assumes you have read [Getting Started with Prebid.js](/overview/getting-started.html), though it applies to Prebid SDK and Server as well. -{% endcapture %} - -{% include alerts/alert_important.html content=importantNote %} - -* TOC -{: toc } - -## Supported ad servers - -The table below lists ad servers supported by Prebid and provides links to step by step documentation for the configurations those ad servers support. - -{: .table .table-bordered .table-striped } -| Server | Page | -|--------------+-----------------------------------------------------------------------------------------------------------------------------------------| -| **Google Ad Manager** | [Step by step guide to Google Ad Manager setup](/adops/step-by-step.html) | -| | [Send all bids to the ad server](/adops/send-all-bids-adops.html) | -| | [Setting up Prebid for AMP in Google Ad Manager](/adops/setting-up-prebid-for-amp-in-dfp.html) | -| | [Setting up Prebid Video in Google Ad Manager](/adops/setting-up-prebid-video-in-dfp.html) | -| | [Setting up Prebid Native in Google Ad Manager](/adops/gam-native.html) | -| **AppNexus** | [Setting up Prebid with the AppNexus Publisher Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) | -| **Smart Ad Server** | [Setting up Prebid.js with Smart Ad Server](/adops/setting-up-prebidjs-with-Smart-Ad-Server.html) | -| **FreeWheel** | [FreeWheel Guide for Premium Long-Form Video](/adops/setting-up-prebid-video-in-freewheel.html) | - -## Decide on price bucket granularity - -On a publisher's selected server the ad ops team will need to setup line items. These line items provide targeting information for the ad server, to include the CPM per impression. Prebid will pass in a bid's targeting parameters via key-values. The ad server will read these incoming targeting parameters and search through the line items for a match. - -Example: - -* Prebid.js is going to call your bidders for their price, then pass it into your ad server on the query-string. You want to target this bid price with a line item that earns you the same amount if it serves. - -* If you had 1-line item for every bid at a penny granularity of $0.01, $0.02, $0.03, ..., 1.23, ..., $4.56 you'd need 1,000 line items just to represent bids from $0-$10. We call this the “Exact” granularity option. - -* Creating 1,000 line items can be a hassle, so publishers typically use price buckets to represent price ranges that matter. For example, you could group bids into 10 cent increments, so bids of $1.06 or $1.02 would be rounded down into a single price bucket of $1.00. - -Our recommendation is to start with $1 or 10 cent granularity until you're more comfortable with Prebid.js. At $1, you only need to setup 10-20 line items – easy. When you're ready, get more granular with the price buckets to improve yield. - -{% capture dfpNote %} - -[Google Ad Manager has a limit](https://support.google.com/admanager/answer/1628457?hl=en#Trafficking) of 450 line items per order, which includes archived line items. If you are designing your own granularity setup, make sure you do not exceed that amount. Refer to our recommended pre-configured granularities in Prebid's API reference under the [Set Config Price Granularity instructions](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Price-Granularity). -{% endcapture %} - -{% include alerts/alert_note.html content= dfpNote %} - - -## One set of line items for all bidders vs. a set of line items for each bidder - -### One set of line items for all bidders - -One set of line items for all bidders is the recommended way of setting up your line items. Choose this option if you prefer an easier, low-maintenance setup: - -- It's quicker and easier to setup, because you only have to create one set of line items. -- It's easier to maintain because adding more bidders requires no change to your line item setup. -- It's less error-prone because you only need to maintain 3 keywords: - -{% include default-keyword-targeting.md %} - - -{% capture successNote %} -For instructions on setting up pre-bid with one set of line items for all bidders, see [Send Top Bid to Ad Server - Step by Step guide to Google Ad Manager setup](/adops/step-by-step.html). -{% endcapture %} - -{% include alerts/alert_tip.html content=successNote %} - - -### One set of line items for each bidder - -Choose one set of line items for each bidder if you: - -- Have to rely on line item reporting (not query string reporting) to get winning bid by bidder analytics - - With one set of line items for all bidders, Prebid.js only sends the highest bid to the ad server (the decision logic of choosing the highest bid can be customized by you). This is sufficient if the winning bids matter the most to you. For example, a bidder bidding 100% of time but losing in every auction still has a fill rate of 0%. However, if having access to all bid information is important to you, use one set of line items for each bidder. - -- Require bid landscape data for header bidding partners - - With one set of line items for all bidders, Prebid.js sends the bidder information (Which bidder has the highest price) via a keyword `bidder=bidder_name`. To run a report to attribute winning bids to bidders, you will need to rely on your ad server's keyword reports. Google Ad Manager supports this, but some ad servers do not. Google Ad Manager does not support running reports for more than 2 keywords. Therefore, if you have existing reports that already rely on keywords, and you want to add a winning bid by bidder dimension, use one set of line items for each bidder. - -- Requires setting more keyword targeting within your ad server. The table below lists the required and optional keys for targeting with each of your header bidder partners. - -{% include send-all-bids-keyword-targeting.md %} - -{% capture successNote %} -For instructions on setting up pre-bid with one set of line items for each bidder, see [Send all bids to the ad server - Ad Ops setup](/adops/send-all-bids-adops.html). -{% endcapture %} - -{% include alerts/alert_tip.html content=successNote %} - -## Safeframes - -[SafeFrames are defined by the IAB](https://www.iab.com/guidelines/safeframe/) as a "managed API-enabled iframe that opens a line of communication between the publisher page and the iframe-contained ad creative." +Ad Operations (Ad Ops) are the people who work directly with the ad server software to create, analyze, and update ad campaigns. In companies that use automated processes rather than working directly in the ad server UI, people in Ad Ops define the inputs to the automation that ensure campaigns run as expected. Whatever your actual job title or exact job description, when we refer to “Ad Ops” we’re talking about the non-engineering tasks involved in running and managing ad campaigns. -When setting up line items in your ad server, you'll need to consider whether to make the creatives safeframes or not. In general, for standard banner and native, safeframes are a good idea. Certain special mediatypes cannot use safeframes. +## Ad Ops Role in Prebid -### Bidders known to be incompatible with safeframes +To understand your role in implementing Prebid, you need to understand how header bidding works. You can get a general overview in our [Introduction to Header Bidding](/overview/intro-to-header-bidding.html) and [Introduction to Prebid](/overview/intro.html). But we’re going to provide a few more details here. -{% assign bidder_pages = site.pages | where: "layout", "bidder" | where: "safeframes_ok", false %} - +Header bidding is a process for collecting bids for an ad slot before the ad server is called. Those bids and their related targeting information are consolidated and sent along with the ad request to the ad server. -There may be others, please check with bidders directly if you have questions about their support. +When the ad request arrives at the ad server, the ad server reads the targeting information and looks for matching line items. This is where ad ops comes in. You need to ensure that those line items exist and are configured correctly. In order to do that, there are a number of decisions you need to make before you begin your ad server setup. Our [Ad Ops Planning](/adops/adops-planning-guide.html) guide will lead you through these decisions. -## Work together with your dev team +After you’ve completed your planning, move on to the appropriate setup documentation for your ad server. -Implementing header bidding requires much more collaboration with your dev team than normal Ad Ops setup. For example: +- [Google Ad Manager](/adops/step-by-step.html) +- [Xandr Monetize Ad Server](/adops/setting-up-prebid-with-the-appnexus-ad-server.html) +- [Smart Ad Server](/adops/setting-up-prebidjs-with-Smart-Ad-Server.html) +- [FreeWheel](/adops/setting-up-prebid-video-in-freewheel.html) -> Setting up price granularity requires you and the dev team working together to ensure the price buckets match. We have seen cases when the code on page sends $0.10 increments, while the line item setup expects $0.50 increments. This results in the ad server not catching 80% of the bids. -## Related Topics +## Next Step -- [Getting Started with Prebid.js](/overview/getting-started.html): How Prebid.js works at a high level. -- [Prebid.js and Ad Server Key Values](/features/adServerKvps.html) -- [What is Prebid?](/overview/intro.html): Overview and history of header bidding and Prebid.js. -+ [Docs by Format](/dev-docs/docs-by-format.html): Engineering and ad ops docs arranged by ad format (video, native, etc.). +Read the [Ad Ops Planning](/adops/adops-planning-guide.html) guide. diff --git a/adops/creative-considerations.md b/adops/creative-considerations.md new file mode 100644 index 0000000000..b078a16c0d --- /dev/null +++ b/adops/creative-considerations.md @@ -0,0 +1,125 @@ +--- +layout: page_v2 +title: Creative Considerations +head_title: Creative Considerations +sidebarType: 3 +sbUUID: 3.2 +--- + +# Creative Considerations +{: .no_toc } + +* TOC +{: toc } + +Some of the major decisions you need to make as you’re setting up your campaigns have to do with creatives. This document will provide information to help you make those decisions. + +{: .alert.alert-info :} +Throughout this discussion we’re assuming you’ve chosen to use the Prebid Universal Creative (PUC). See [Prebid Universal Creative](#prebid-universal-creative) below for advantages and disadvantages of this approach. For more information on the PUC as well as alternatives, see the [Prebid Universal Creative Overview](/overview/prebid-universal-creative.html). + +## Creatives Overview + +When you set up a line item for a campaign in your ad server, you have to add images or ad tags that will be displayed for that campaign. Header bidding line items have a particular kind of ad tag. + +The Prebid ad tag is entered into creatives on the ad server in the form of a script that will enable Prebid to find the bid that goes with a winning line item. Depending on your ad server, you’ll have to declare your creative as a Third Party creative (Google Ad Manager), or set it to use HTML, or some other means of entering an ad tag (the Prebid script) rather than an image. + +## Prebid Universal Creative + +The first decision you’ll need to make when it comes to creatives (with the exception of VAST video) is whether you want to use the Prebid Universal Creative (PUC). The PUC is a collection of rendering routines that can pull a particular ad ID from the Prebid cache and do the right thing to display it. You can find full details about the PUC in the [Prebid Universal Creative Overview](/overview/prebid-universal-creative.html). For now we’ll focus on the advantages and disadvantages to using the PUC. + +The big advantage to using the PUC is that it’s the simplest approach to configuring Prebid in your ad server. It provides a robust mechanism that can be used across several formats, platforms, devices, and ad servers. + +The primary disadvantage to using the PUC is that it takes an extra fetch to load the PUC file vs doing everything inline to the creative. Also, in version 1.14.1 and earlier of the PUC, loading a “universal” creative means that more bytes are loaded than are actually necessary for the display of a single creative. This all leads to a very slight performance penalty. + +You’ll need to determine whether the ease of implementation is worth the small performance penalty. + + +## Creative Naming + +You can name your creatives whatever makes sense to your organization. We recommend names in the following format: Prebid - Type - Size - N. For example, a banner creative using the PUC would be `Prebid - banner - 1x1 - 1`. + +## Creative Modes + +No matter what type of media you’re working with, you need to decide how you’re going to represent the size options in the ad server. There are three creative size modes: + +- Creatives are all sized 1x1 +- Creatives are sized their actual size +- Line items are targeted per size + +### All Creatives 1x1 + +If you select this mode, in the ad server you’ll set the size of all your Prebid creatives to 1x1. The creatives will then be resized based on the value supplied by the demand partner in the hb_size key. This is the simplest option to implement and requires the fewest number of creatives to be created. + +If you’re working with Google Ad Manager (GAM) we recommend you create one general 1x1 creative, then duplicate it to attach 3 - 5 identical creatives to each line item. The reason for this is that GAM doesn’t make a distinction between creatives with images attached and creatives with a script that could be used to retrieve one of many different images. It treats every creative as an individual image, and allows each one to be served to only one ad unit per page. + +For Prebid line items, this means that if your page has multiple ad slots that fit the same line item targeting, GAM would allow only one of them to display the creative, not realizing that one creative could point to different images. Attaching multiple identical creatives to each line item ensures that creatives from a line item matching the targeting on multiple ad slots can serve on the same page. + +For example, say you're using "low" granularity, which means that one line item covers bids from $1.00 to $1.49. If you have three creatives associated with that line item, the page could not display anymore than three Prebid bids in that price range. If you have infinite scroll pages, you'll have to consider the tradeoff for how many copies of creatives you want to have. + +### Creative Actual Size + +With this mode, you set specific sizes on the creatives. This mode allows for more precise reporting if you’re interested in knowing the exact sizes of creatives being served from Prebid. As with the 1x1 option, we recommend you create 3 - 5 duplicate creatives of each size. The downside is that this requires a lot of creatives per line item. If you specify 20 sizes, you would need as many as 100 duplicate creatives. + +### One Line Item Per Size + +We recommend against using this mode, but are aware some publishers use it for reporting purposes. With this mode, you would target your line item based on the value of the hb_size key. This would require you to create one line item for every size, for every bidder, for every price. The number of line items required could get extremely large. Here’s an example (see [Price Granularity](/adops/price-granularity.html) for more details): + +- Bidders: 10 +- Price Increment: 0.10 +- Price Cap: 20 +- Sizes: 5 +- Send all bids + +This scenario would require you to create 10,000 line items (10 x 200 x 5). If you were to use either 1x1 mode or creative-level sizing you would need only 2,000 line items. + +## Banner and Outstream Creatives + +As we mentioned, each creative requires an ad tag script that will call the [Prebid Universal Creative](/overview/prebid-universal-creative.html) to display the correct image. + +One decision you'll want to make is which version of the PUC you want to use. Prebid hosts a copy, which you're free to use. But some publishers might want to use their own copy of the PUC so as to have greater control over the upgrade windows. + +{: .alert.alert-info :} +Engineers can find the PUC code in the [Prebid Github repository](https://github.com/prebid/prebid-universal-creative). + +## Native +Native ads require close collaboration between web designers, engineering, and ad ops. The primary decision to be made that affects ad ops is where to store the rendering template. Your options are: + +- The ad server +- The page's Prebid.js adunit +- An external script + +If you already have templates stored in your ad server for some native ads, it might make sense to also store the templates for Prebid there and keep everything together and consistent. This also gives ad ops control over when templates change. + +The second two options require engineering to make any changes when template updates are required. Because native ad formatting is tied to the look of the site, these options could fit in with normal site maintenance. + +Each option requires a different PUC ad tag to be used in the associated creatives, so be sure to get the correct script (and CSS file) from the engineers. + +{: .alert.alert-info :} +Engineering details outlining each template storage option can be found in the [Prebid.js Native Implementation Guide](/prebid/native-implementation.html). + +## VAST Video +VAST video (instream and long-form video) does not use the PUC. Instead, video bids provide VAST that Prebid caches to obtain a cache ID that can be retrieved with a URL. The cache ID is passed as a key value to the ad server. (See [Video Overview](/prebid-video/video-overview.html) for details.) + +When you’re running campaigns with video creatives, the primary decision you need to make is where to cache your video bids. You’ll enter this location in the creative you add to the line item. The cache location is typically independent of the bidders. The most common cache location is https://prebid.adnxs.com. See [Setting Up Video In GAM](/adops/setting-up-prebid-video-in-dfp.html) for detailed instructions on configuring a video creative in GAM. + +## SafeFrames + +Another decision you need to make with regards to banner and native creatives is whether to run them in SafeFrames. A SafeFrame is defined by the IAB as “a managed API-enabled iframe that opens a line of communication between the publisher page and the iframe-contained ad creative.” SafeFrames provide an added layer of security by separating the ad from your web page. + +We recommend using SafeFrames for banner and native creatives, but there are some things to keep in mind if you do this. For example: + +- Some creatives, such as richmedia formats, can’t render in SafeFrames. +- Some bidders do not support the use of SafeFrames. + +If you don't trust all your bidders to provide creatives that can safely run inside of SafeFrames, then you'll want to consider using [Send All Bids](/adops/send-all-vs-top-price.html) (the default), which will enable you to allow some bidders to use SafeFrames and some not. + +[Prebid documentation for each bidder](/dev-docs/bidders.html) provides information on whether the bidder supports SafeFrames. + +Be sure to check with bidders directly if you have questions about their SafeFrame support. + +## Further Reader + +- [Planning Guide](/adops/adops-planning-guide.html) +- [Key Values for Ad Ops](/adops/key-values.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) +- [Deals in Prebid](/adops/deals.html) diff --git a/adops/deals.md b/adops/deals.md index f2c838e137..61c6d0d703 100644 --- a/adops/deals.md +++ b/adops/deals.md @@ -1,135 +1,60 @@ --- layout: page_v2 -title: Enable Deals -head_title: Enable Deals in Prebid for Header Bidding -description: Enable Deals in Prebid for Header Bidding Analysis. -pid: 4 - +title: Deals in Prebid +head_title: Deals in Prebid sidebarType: 3 +sbUUID: 3.2 --- -# Enable Deals in Prebid -{:.no_toc} - -In order to enable deals for prebid, the ad ops setup is slightly different from the standard header bidding setup. Specifically: - -+ From the ad ops side, you'll create separate orders and line items that target the deal ID key-values. These line items will be at different (probably higher) priorities than your standard header bidding line items. - -+ From the dev side, if your page is using the standard prebid.js key-values, no change or work is required. - -{: .bg-info :} -In this example we will use the Google Ad Manager setup to illustrate, but the steps are basically the same for any ad server. +# Deals in Prebid +{: .no_toc } * TOC -{:toc} - -### Step 1: Understand Key-values - -Whenever a bidder responds with a bid containing a deal ID, Prebid.js will generate and attach deal-related key-values to the ad server call in the format: `hb_deal_BIDDERCODE = DEAL_ID`. - -For example, given the submitted bids, prices, and deals shown here: - -``` -bid 1: Bidder = Rubicon, CPM = 1.50, Deal ID = RBC_123 -bid 2: Bidder = AppNexus, CPM = 1.20, Deal ID = APN_456 -``` - -The key-values attached to the ad server call (that the line items will target) will be: - -``` -hb_pb_rubicon = 1.50 -hb_deal_rubicon = RBC_123 -hb_pb_appnexus = 1.20 -hb_deal_appnexus = APN_456 -// hb_adid, hb_size, and hb_adid omitted -``` - -{% capture noteAlert %} -We recommend confirming with your development team that the page is set up to send all deal targeting to the ad server. There are two ways to do this: -- Set the `enableSendAllBids` to **true**. -- Set `enableSendAllBids` to **false** and `alwaysIncludeDeals` to **true**. This option will minimize the number of targeting variables sent to the ad server. -See the [enableSendAllBids](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-All-Bids) documentation for details. -{% endcapture %} - -{% include alerts/alert_note.html content=noteAlert %} - -
- -### Step 2: Create Key-values - -For each header bidding partner you work with, create a keyword in the format of `hb_deal_BIDDERCODE`, e.g., `hb_deal_pubmatic`. For more examples of the keyword format, see the [API Reference for `pbjs.getAdserverTargeting`](/dev-docs/publisher-api-reference/getAdserverTargeting.html). - -
- -![Inventory Sizes]({{ site.github.url }}/assets/images/demo-setup/deals/key-val.png){: .pb-lg-img :} - -
- -### Step 3: Create Line Items for Deals - -In Google Ad Manager, create a new line item. - -Enter all the **Inventory sizes** for your deal (or deals): - -![Inventory Sizes]({{ site.github.url }}/assets/images/demo-setup/inventory-sizes.png){: .pb-md-img :} +{: toc } -
-Set the **priority** to the level you prefer. +In the same way that you can negotiate deals with advertisers in your ad server, you can also set up deals with your header bidding partners. When you do that, there are just a few things to keep in mind to ensure those deals get sent to the ad server and your line items are prepared to receive them. -![Inventory Sizes]({{ site.github.url }}/assets/images/demo-setup/deals/deal-priority.png){: .pb-lg-img :} +## Send Deal to Ad Server -
+In [Send All Bids vs Top Price](/adops/send-all-vs-top-price.html) we described those two options for sending bids to the ad server. There is also a third option created specifically for deals: Send top price and deals. -Set **Display Creatives** to *One or More* since we'll have one or more creatives attached to this line item. +### Deals with Send All Bids -Set **Rotate Creatives** to *Evenly*. +If you send all bids to the ad server, deals will be sent along with the rest of the bids. If you want your deals to be prioritized over the rest of the bids, be sure to inform the software engineers so they can configure Prebid for this scenario. -![Display and Rotation]({{ site.github.url }}/assets/images/demo-setup/display-and-rotation.png){: .pb-md-img :} +{: .alert.alert-info :} +See [Configure Send Bids Control](/dev-docs/publisher-api-reference/setConfig.html#configure-send-bids-control) for engineering instructions on this configuration. -
+### Deals with Send Top Price -Then you'll need to target the **inventory** that you want to this deal to run on. +If you decide to send only the top price bid, the deal might not be the top price, in which case it would not be sent and the ad server would never see it. To ensure deals make it to the ad server, the software engineers need to know that deal bids should be included along with the top priced bid. They can then configure Prebid to send both the top price and any deals that come through. -
+{: .alert.alert-info :} +See the [Send All Bids engineering reference](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Send-All-Bids) for engineering instructions on sending deals along with the top bid. -**Use Key-values targeting to target deal ID(s)** +## Deal Line Item Details -There are two ways to target deal IDs using *Key-values* targeting: +In [Line Item Creation](/adops/line-item-creation.html) we talked about some requirements and recommendations for setting up line items for Prebid. You can follow most of those settings for deals, with the modifications outlined here. -1. If you would like the deals to have the same priority and target the same inventory, you can include multiple deal IDs (as shown below). -2. Otherwise, you must create a separate line item for each deal ID you want to target. +### Deal Key Value Pairs -![Inventory Sizes]({{ site.github.url }}/assets/images/demo-setup/deals/targeting.png){: .pb-lg-img :} +From the ad server side, you need to create special line items for each deal. This is done through a key-value pair. (See [Key Values](/adops/key-values.html) for details on how key value pairs work.) -
+For each header bidding partner you negotiate deals with, create a keyword in the format hb_deal_BIDDERCODE, e.g., hb_deal_BidderA. Then when you create the line item for the deal, add in that code with the associated deal ID. For example, hb_deal_BidderA=BDA_123. -### Step 4: Attach Creatives to Line Items +{: .alert.alert-info :} +The actual value of the deal ID (BDA_123 in this example) will be obtained from the demand partner. -Like all line items, those that represent deals need to be associated with creatives that pass the correct adid back to Prebid.js for display. +### Start and End Dates -e.g. if the line item is targeted to `hb_deal_pubmatic`, then the creative needs to send `hb_adid_pubmatic` in the creative. Like this: +Prebid line items normally start immediately with no end date; the line item exists to receive a bid at any time, whenever it gets sent to the ad server. Because deals are negotiated with the demand partner, deals will have date ranges in accordance with the agreement. - - +## Further Reader -If however, the line item is targeted to `hb_deal` (without a bidder code), -then the simplified creative setup in the [step-by-step instructions](/adops/step-by-step.html#step-2-add-a-creative) will be fine. +- [Planning Guide](/adops/adops-planning-guide.html) +- [Key Values for Ad Ops](/adops/key-values.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) diff --git a/adops/key-values.md b/adops/key-values.md new file mode 100644 index 0000000000..bfe82a0a2a --- /dev/null +++ b/adops/key-values.md @@ -0,0 +1,109 @@ +--- +layout: page_v2 +title: Key Values +head_title: Key Values +sidebarType: 3 +sbUUID: 3.2 +--- + +# Key Values +{: .no_toc } + +* TOC +{: toc } + +Prebid uses key-value pairs to pass bid information to the ad server. This puts key values at the core of how Prebid works. Without key values, Prebid would have no way of communicating with ad servers, and therefore no way to make header bidding part of the auction. This document explains how bid information is sent to the ad server, what information is sent, and options for modifying the amount and types of information that is sent. + +## Sending Bids to the Ad Server + +Prebid sends information to the ad server about the bids it receives by creating a query string of key-value pairs (KVPs) and attaching it to the ad request that is sent to the ad server. A portion of that query string might look something like this: + +`?hb_pb=1.50&hb_adid=234234&hb_bidder=bidderA` + +In this example, hb_pb is the bid price bucket (1.50), hb_adid is an identifier for the specific bid (234234), and hb_bidder is the name of the bidding SSP or exchange (bidderA). In order for a bid that comes from the header bidding process to compete with bids on the ad server, you must have line items set up with key values that match the KVPs in the query string. + +## Prebid Keys + +This table lists the keys that can be sent from Prebid to the ad server. Depending on the media type, most of these keys are sent by default. + +{: .alert.alert-info :} +You can work with your engineers to modify the default list. See [Restricting Data Sent to the Ad Server](#restricting-data-sent-to-the-ad-server) below for more information. + +{: .table .table-bordered .table-striped } +| Key | Usage | Scenario | Description | Example Value | +| --- | ----- | -------- | ----------- | ------------- | +| hb_pb | targeting | All | The bid price bucket (adjusted for price granularity). | 2.10 | +| hb_adid | rendering | All | The ad ID. Used by the Prebid Universal Creative (PUC) ad server creative to render the winning Prebid ad. | 123456 | +| hb_bidder | targeting and reporting | Could be used for creative-level targeting in video scenarios; reporting for all scenarios | The bidder code. Used for logging and reporting to learn which bidder has higher fill rate/CPM. | BidderA | +| hb_size | rendering | Banner, native, outstream. Not used for video. | The size used for resizing the iframe for the winning creative. | 300x250 | +| hb_format | targeting and reporting | Needed only if there's a different set of line items for different media types | Used when creating a separate set of line items for banner vs video | video | +| hb_deal | targeting | All | Target private marketplace deals | 7777777 | +| hb_uuid | rendering | Video only | Carries the cache retrieval ID for VAST video creatives | 1111-2222-3333-4444 | +| hb_cache_id | rendering | Banner, native, outstream; mobile app only | Carries the cache retrieval ID for mobile bids | 2222-3333-4444-5555 | +| hb_cache_host | rendering | Banner, native, outstream; mobile app only | The host where the cached creative lives | https://mycachehost.example.com | +| hb_cache_path | rendering | Banner, native, outstream; mobile app only | The web path where the cached creative lives | /cache | +| hb_source | reporting | Server-to-server testing | Used to report the A/B test results for client- vs server-side performance. | s2s | +| hb_adomain | reporting and special | All | Used to report on VAST errors, set floors on certain buyers, monitor volume from a buyer, or track down bad creatives | example.com | + + +When you’re sending the [Top Price Bid](/adops/send-all-vs-top-price.html) to the ad server, the preceding keys are the only keys that will be sent. If you’re [Sending All Bids](/adops/send-all-vs-top-price.html), the preceding keys will be sent, plus the same set of keys specific to each bidder, with the bidder name appended. For example, if you receive bids from BidderA and BidderB, the keys hb_pb, hb_pb_BidderA, and hb_pb_BidderB will all be sent to the ad server with the values provided by the associated bidders. (Even in that scenario, the "winning" keys [hb_pb, etc.] will still have the values for the top bid.) + +## Key Value Pair Usage + +KVPs sent from Prebid are used in the ad server for a variety of purposes: targeting, reporting, creative rendering, and to supply additional information. + +### Targeting + +Targeting KVPs are used to pick out which line items match the request, or possibly which creative within a line item should be used. They will need to be entered in the line items you create to capture the bids coming in from Prebid. These key values can also be used in reports. + +{: .alert.alert-success :} +It's also possible to use regular ad server targeting values on header bidding line items. For example, if you want to have different price granularities in one country, you could create multiple sets of line items differentiated by country. + +### Reporting + +Some publishers rely on ad server KVPs for important business reporting. Reporting on the Prebid keys can help you determine the performance of your header bidding partners and your overall Prebid configuration. Key values that are for reporting only are not entered in line items. Depending on your ad server, reporting keys might need to be created in the ad server in order to be used in reporting. + +### Rendering + +These values are needed for rendering the creative properly when the Prebid line item is chosen. + +### Special Usage + +The hb_adomain key was created to provide additional information about a bid or to help with troubleshooting. See [setConfig](/dev-docs/publisher-api-reference/setConfig.html#details-on-the-allowtargetingkeys-setting) for engineering information on using the hb_adomain key. + + +## Restricting Data Sent to the Ad Server + +When Prebid creates the query string that is sent to the ad server, it includes a default set of keys (along with the associated values provided by the demand partners). However, you might not need or want all the default values, or maybe you need additional values. Because of this, Prebid provides tools that allow for modifications to the amount of data sent to the ad server. + +You’ll need to determine which keys you want sent and then work with your engineers to ensure the keys that are sent match those you’re expecting. Some things to consider: + +How much information do you need and want? +Does your ad server have restrictions on the amount of data it can receive? + +### Key Values in Your Configuration + +The information you need and want are entirely dependent on your configuration and usage requirements. Maybe not all the reporting keys are useful to you, in which case you can omit some or all of those keys. Making sure the keys you need match the keys that are sent to the ad server will help ensure the targeting and reporting you’ve set up on your ad server work correctly. + +### Query String Restrictions + +Some ad servers restrict the number of characters they’ll accept on the query string. When you use [Send All Bids](/adops/send-all-vs-top-price.html), the number of key value pairs sent to the ad server can be very large, depending on the number of bidders and ad slots.This large number of key value pairs can make for a very long query string. + +If the query string has too many characters, an ad server with restrictions could simply truncate the string to the length it will accept. This could prevent bids from being received, or could truncate a bidder’s key values to the point where they won’t match any line items. Fortunately, Prebid can be configured to deal with this issue. + +In addition to being able to specify which keys to send, Prebid can also be configured to limit the length of the query string that will be appended to the ad request. Prebid will prioritize the bids to ensure top bids and deals are included, along with all of their associated key value pairs. + +{: .alert.alert-info :} +For details on how Prebid prioritizes bids based on query string length, see “Details on the auctionKeyMaxChars setting“ under [Configure Targeting Controls](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls). + +Reducing the number of default keys sent and limiting the number of bidders will reduce the length of the query string. Work with your engineers to evaluate the typical length of your query strings and make modifications as necessary to achieve the best results for your organization. + +{: .alert.alert-info :} +For engineering information on configuration options, see [Prebid.js Controls](/features/adServerKvps.html#controls). In particular, note the following: + [Configure Targeting Controls](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls). + +## Further Reader + + - [Planning Guide](/adops/adops-planning-guide.html) + - [Prebid Universal Creative](/overview/prebid-universal-creative.html) + - [Deals in Prebid](/adops/deals.html) diff --git a/adops/line-item-creation.md b/adops/line-item-creation.md new file mode 100644 index 0000000000..8216b04e56 --- /dev/null +++ b/adops/line-item-creation.md @@ -0,0 +1,176 @@ +--- +layout: page_v2 +title: Line Item Creation +head_title: Line Item Creation +sidebarType: 3 +sbUUID: 3.2 +--- + +# Line Item Creation +{: .no_toc } + +* TOC +{: toc } + +The settings you apply when creating line items to capture bids coming in from the header bidding process are typically different from those you apply when creating line items for house ads. This document will walk you through some of the differences, and outline requirements and recommendations for creating line items to work with Prebid. + +{: .alert.alert-success :} +Manually configuring ad server elements for Prebid can be a fair amount of work. If you’re using Google Ad Manager (GAM), consider using our official command line tool, [Prebid Line Item Manager](/tools/line-item-manager.html#prebid-line-item-manager.html), to create the setup. Using this tool may save you time and help you avoid mistakes. + +## Advertisers and Orders + +Line items (and creatives) must, at some level, be associated with advertisers. When you create line items to capture Prebid bids, you won’t know who the actual advertisers are. Instead you need to create generic advertisers in your ad server that are used for Prebid. For example, you can create an advertiser named “Prebid Advertiser.” Or if you’re using Send All Bids, you can create one advertiser per bidder, such as “Prebid BidderA,” “Prebid BidderB,” etc. You then associate your line items and creatives with those advertisers. + +Depending on your ad server, line items are typically grouped within orders under each advertiser. + + +## Line Item Details + +You have many options for the way in which you set up your line items. The following are Prebid requirements, and also some recommendations, to ensure bids are captured correctly and to make keeping track of your header bidding line items easier. + +### At a Glance + +These tables show the Prebid line item recommendations and requirements. The following sections provide more details on each. + +**Required** + +{: .table .table-bordered .table-striped } +| Detail | Requirement | +| ------ | ----------- | +| Line Item Type | Price Priority (depending on your ad server) | +| Key Value Pricing | Include the number of decimal places that are defined in the price granularity precision. Normally this is two decimal places, e.g. hb_pb=0.50 or hb_pb=1.00 | + +**Recommended** + +{: .table .table-bordered .table-striped } +| Detail | Recommendation | +| ------ | -------------- | +| Line Item Groups | Determine the number of containers you'll need to store the line items based on price granularity, number of bidders, and ad server restrictions. Name your group in the format Prebid, format, bidder name (for [Send All Bids](/adops/send-all-vs-top-price.html)), and unique number; for example, `Prebid - banner - BidderA - 1`. | +| Line Item Name | Name each line item for the header bidding price bucket. Use the naming pattern Prebid, mediatype, bidder (for Send All Bids), and price bucket; for example, `Prebid - banner - BidderA - 1.50`. | +| Creative Name | In the creative name, include Prebid, the media type and the size (if applicable), and a unique identifying number (if more than one creative of a given size is attached to the line item). If using Send All Bids, also include the bidder name; for example, `Prebid - banner - BidderA - 1x1 - 1`. | +| Start and End Dates | Start immediately, no end date | +| Priority | Above house ads but below directly sold ads | +| Impression Goal | None | +| Media Types | Group media types by price granularity. This typically means you can group banner, outstream video, and native together but video will be a separate set of line items. | + +### Line Item Type + +If your ad server supports it, you should set your line item type to Price Priority, which will let it compete with bids from other sources. + +### Key Value Pricing + +When you enter your key values for price, you must include the number of digits following the decimal point that are specified with your [price granularity](/adops/price-granularity.html). This is known as the precision value. For example, if Prebid is configured with a precision of two decimal places, then when you enter a value for the key hb_pb you must include two decimal places in your value: 0.50 or 1.00 rather than 0.5 or 1. If you don’t include the correct number of decimal places, your line item will not match any header bidding values. + +For predefined Prebid price granularities the precision is 2; for custom price granularities this value can be defined in your Prebid configuration. + +{: .alert.alert-info :} +Engineering instructions for setting the precision value can be found in [setConfig Price Granularity](/dev-docs/publisher-api-reference/setConfig.html#setConfig-Price-Granularity). + +See [Key Values](/adops/key-values.html) for general information about key value pairs. + +### Line Item Groups + +If you are [sending all bids](/adops/send-all-vs-top-price.html) to the ad server, you’ll most likely want to group your line items by bidder. (In Google Ad Manager this means creating at least one set of orders per bidder, with that bidder’s line items attached to the order.) This allows each group to have a set of line items that use the same targeting keywords, all of which include the bidder’s name. For example, if you are working with BidderA, all line items within a group would use the key hb_pb_BidderA in the line item’s key-value targeting, and hb_adid_BidderA in the attached creative. + +Depending on your ad server and the number of line items you’re creating, you might need more than one group per bidder. For example, suppose you need to create 2000 line items for one bidder. If GAM is your ad server, you’re allowed only 450 line items per order, so you will need five orders per bidder to store the 2000 line items, for a total of 25 orders. + +We recommend naming the group to include “Prebid”, media type, the bidder name, and also a number or other identifier if you need more than one group per bidder. For example, `Prebid - banner - BidderA - 1`. For [Send Top Price Bid](/adops/send-all-vs-top-price.html) you can omit the bidder name: `Prebid - banner - 1`. + +### Line Item Name + +Because you’ll be creating one line item per price within each [price bucket](/adops/price-granularity.html), it’s helpful to name your line items based on the price. It can also be helpful to include the mediatype, since different types of media could be priced the same. Some examples include `Prebid - banner - 1.00`, `Prebid - video - 1.50`, etc. If you’re [sending all bids](/adops/send-all-vs-top-price.html), include the bidder code: `Prebid - banner - BidderA - 1.00`, `Prebid - banner - BidderA - 1.50`. + +### Creative Name + +We recommend naming creatives to include the media type, size (where applicable), and a number if there is more than one. For example, `Prebid - banner - BidderA - 1x1 - 1`; `Prebid - video - BidderA - 1`. + +### Start and End Dates + +With header bidding, start and end dates of the actual ad campaigns are controlled by the header bidding demand partners. The demand partners check their inventory and bid for an ad slot based on campaigns running on their systems. The line items you’re creating are generic and immortal line items created to capture a bid from a campaign your demand partner will be running at some point in the future. + +What this means is that you typically don’t want to include an end date in your line items. Your line item will always be active to read in bids coming from your demand partner. + +Set your start date to begin immediately. + +### Priority + +Unless you’re working with [deals](/adops/deals.html), bids received from header bidding will typically have a priority lower than directly sold ads but higher than any competing house ads. + +### Impression Goal + +We recommend you do not set an impression goal. Because these are general line items with (typically) no end date, there’s no need to set a goal. + +### Media Types + +Prebid supports many media types, and you can set up a single line item with multiple types. The media types you choose can impact the way in which you decide to organize your line items. + +Grouping media types within line items is typically dictated by the pricing structure: + +- Banner, outstream video, and native generally run together because they have similar pricing expectations and therefore can share [price granularities](/adops/price-granularity.html). +- Instream video is normally created as a separate set of line items because they are usually priced higher than other formats, often requiring custom price granularity. + +You must set a key value for each format used by an ad unit using the hb_format (or hb_format_BIDDER) key and setting its value to the appropriate format. For example, if the ad unit is set up as a banner ad, you would target hb_format=banner (along with the price, such as hb_pb=1.00). If your ad unit supports multiple types, set the key value to include all types: `hb_format` in `banner`,`native`. + +## Example Line Item Setup + +Here's an example that encapsulates a number of the key decisions outlined in this document. In this scenario, we’ve made the following decisions: + +- Send Top Bid +- Banner granularity: high +- Video granularity: custom +- Order naming pattern: Prebid - banner - N, Prebid - video - N +- Line Item naming pattern: Prebid - banner - PRICE, Prebid - video - PRICE +- Creative naming pattern: Prebid - banner - 1x1 - N, Prebid - video - N +- Choosing to make three copies of each creative + +The granularity we’ve chosen means we’ll be creating 2000 line items for banner and 1000 line items for video. Those line items will be named as shown here: + +- Order: Prebid - banner - 1 + - LI: Prebid - banner - 0.00 (If the bid is less than 1 penny, it rounds down to 0, but is still worth something) + - Creative: Prebid - banner - 1x1 - 1 + - Creative: Prebid - banner - 1x1 - 2 + - Creative: Prebid - banner - 1x1 - 3 + - LI: Prebid - banner - 0.01 + - ... creatives ... + - LI: Prebid - banner - 0.02 + - LI: Prebid - banner - 0.03 + - ... + - LI: Prebid - banner - 4.49 +- Order: Prebid - banner - 2 + - LI: Prebid - banner - 4.50 + - LI: Prebid - banner - 4.51 + - LI: Prebid - banner - 4.52 + - LI: Prebid - banner - 4.53 + - ... + - LI: Prebid - banner - 09.49 +- ... other banner orders up to 20.00 ... + +- Order: Prebid - video - 1 + - LI: Prebid - video - 0.00 + - Creative: Prebid - video - 1 + - Creative: Prebid - video - 2 + - Creative: Prebid - video - 3 + - LI: Prebid - video - 0.05 + - LI: Prebid - video - 0.10 + - ... +- ... + +If we had chosen Send All Bids (the Prebid default), every element shown above would be recreated for each bidder, and each name would include the bidder name. For example: + +- Order: Prebid - banner - BidderA - 1 + - LI: Prebid - banner - BidderA - 0.00 + - Creative: Prebid - banner - BidderA - 1x1 - 1 + - Creative: Prebid - banner - BidderA - 1x1 - 2 + - Creative: Prebid - banner - BidderA - 1x1 - 3 +- ... + +## Next Step + +[Price Granularity](/adops/price-granularity.html) + +## Further Reader + +- [Planning Guide](/adops/adops-planning-guide.html) +- [Key Values for Ad Ops](/adops/key-values.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) +- [Deals in Prebid](/adops/deals.html) diff --git a/adops/price-granularity.md b/adops/price-granularity.md new file mode 100644 index 0000000000..9cab9519e1 --- /dev/null +++ b/adops/price-granularity.md @@ -0,0 +1,181 @@ +--- +layout: page_v2 +title: Price Granularity +head_title: Price Granularity +sidebarType: 3 +sbUUID: 3.2 +--- + +# Price Granularity +{: .no_toc } + +* TOC +{: toc } + +Price granularity is a way to quantize bids so that you don't need to make an infinite number of line items. It allows you to balance the work of creating line items with the desire to optimize revenue from your header bidding partners. This document will explain price granularity in detail and why it’s necessary, and provide you with the information you need to make the best decisions for your Prebid implementation. + +## Price Granularity Explained + +When your ad server looks to fill an ad request, it takes many things into consideration. Broken down to its simplest form, we can say that the highest price that matches the targeting will win the auction for the ad slot. In a non-header bidding scenario, when you set up line items for your advertisers in your ad server, you specify the amount of money the advertiser is willing to spend for a particular ad unit based on whether it matches the targeting. For example, an advertiser might be willing to pay 1.52 CPM for an ad unit that targets people aged 18 - 25 who live in the U.S. So you set up your line item for that advertiser with a rate of 1.52 CPM. + +With header bidding, you have bids coming in from outside the ad server, so you don’t have any price information until the actual bid is passed into the ad server. Instead, it works like this: + +- Prebid contacts your demand partners, who find advertisers running campaigns that match the available contextual and user information. +- The demand partners send in their top bid or bids for the ad slot. +- Those bids are then sent to your ad server. + +With this process, you don’t know in advance what price your demand partner’s advertisers were willing to pay. So how do you know what price to target in your line items? Do you have to create a line item for every possible price that could come in? Given the fact that open market bids can be fractions of units (so a bid of 0.255 is acceptable), the number of line items you would have to create to cover every possibility is almost infinite. + +This is where price granularities come in. Price granularities allow you to group bids into “price buckets.” These buckets give you a definitive set of bid prices to target, and therefore a definitive set of line items to create. + +## Components of Price Granularity + +In Prebid, there are four components to price granularity. + +**Price increments**: The increments between prices you’ll be targeting in your line items. For example, if you choose .10 increments, you will create line items with prices of 0.00, 0.10, 0.20, 0.30, etc. Prebid comes with built-in options for .10 and .50 increments, and also allows you to define your own. + +**Price cap**: The maximum price allowed within a set of price increments. For example, if you choose an increment of .50 and a cap of 5.00, your line item pricing will range from 0.00 through 5.00 at .50 increments: 0.00, 0.50, 1.00, 1.50…5.00. + +**Price range**: An increment/price cap within a price granularity. You can have multiple price ranges within one price granularity, which allows you to specify different increments at different CPM values. For example, you might want a smaller increment (such as .10) for CPMs under 10, and larger increments (such as .50) for any CPM over 10. + +**Price bucket**: The actual price targeted in the line item. (Note the name of the key that is passed in with the bid price, hb_pb, stands for header bidding price bucket.) For example, if you’re using 0.50 increments and you have one bidder who bids 1.45 and another who bids 1.20, both will be rounded down and placed into the 1.00 price bucket. (See the next section for a description of Rounding.) + + +## Rounding + + +Bids received from your Prebid demand partners are rounded down according to your price granularity. If your granularity is .50, a bid of 2.95 will be rounded down to 2.50. Consider the following scenario: + +- Price granularity is set to .50 +- BidderA submits a bid for 2.75. +- BidderB submits a bid for 2.55. + +In this case, BidderA is the top bid at 2.75. If only the top bid is sent to the ad server, BidderA will be rounded down to 2.50 and sent. If all bids are sent, BidderA would still be the top bid, but both BidderA and BidderB bids will be rounded down to 2.50 and sent to the ad server. After reaching the ad server, both bids could lose to an ad server bidder that bid 2.51, even though both BidderA and BidderB initially bid higher than that. + +{: .alert.alert-warning :} +**Important**: Rounding does not impact the price paid, only the auction on the ad server. For example, if your bid for 2.75 is rounded down to 2.50 and wins on the ad server at 2.50, you will be paid 2.75. + +Bids also round down to reflect the top price in your granularity definition. If your price cap is 5.00 and you receive a bid of 20.00, that bid will be rounded down to 5.00. This is important to keep in mind for [video inventory](#video-price-granularity), which often sells for higher prices than other media types. + +{: .alert.alert-success :} +You might have noticed earlier that we gave examples of price buckets of 0.00. This is necessary because it captures bids that are less than the increment value, but are still valid bids. For example, if you have 0.10 granularity and a bid price of 0.02, that gets rounded down to 0.00. Even with a 0.01 granularity, there can be fractional bids, so a bid price of 0.005 would still have value but get rounded down to 0.00. It's not going to compete very well, but if the hb_pb=0.00 line item is chosen, the bidder will still pay their bid price of 0.005. + + +This rounding might initially sound like a bad idea. You’re obviously losing revenue when a lower bid price wins over a higher price, right? But there are advantages to using price granularities and price caps, which we’ll discuss below in “Pros and Cons.” + + +## Prebid Default Price Granularities + +Prebid provides several default price granularity options. Work with your software engineers to ensure the Prebid implementation is configured to match your line item setup. + +### Currency Considerations + +Before we get into the details of Prebid’s price granularity options we need to talk about different currencies. Prebid’s built-in granularity options were designed to represent typical bid prices in 2016 if your currency was USD, EUR, GBP, CAD, AUD, or other currency of similar value. So when you read the values below, think about whether your normal bid prices fall into these ranges. + + +If you’re working with currencies, such as JPY, INR, and CZK, that don’t fit into the predefined price granularities, you may need to define custom price buckets (explained below). See [Currency Module](/dev-docs/modules/currency.html) for more information and additional options for working with these currencies. Specifically note the granularity multiplier option, which lets you "scale up" the standard buckets to make sense for your currency. + +### Built-In Price Granularity Options + +{: .table .table-bordered .table-striped } +| Granularity | Increment | Cap | Number of Line Items Required per Bidder | +| ----------- | --------- | --- | ---------------------------------------- | +| low | 0.50 | 5.00 | 11 | +| medium | 0.10 | 20.00 | 201 | +| high | 0.01 | 20.00 | 2001 | +| auto | Sliding scale | Sliding scale | See [Auto](#auto) | +| dense | Sliding scale | Sliding scale | See [Dense](#dense) | +| custom | Custom sliding scale | Custom sliding scale | Dependent on scale | + + +#### Auto + +The auto option contains a series of predefined buckets. Any bid over the cap falls into the next highest bucket. + +{: .table .table-bordered .table-striped } +| Increment | Cap | Number of Line Items Required per Bidder | +| --------- | --- | ---------------------------------------- | +| 0.05 | 5.00 | 51 | +| 0.10 | 10.00 | 50 | +| 0.50 | 20.00 | 10 | +| Any bid > 20.00 | 20.00 | n/a | +| | | Total: 111 | + + +#### Dense + +Dense provides a sliding scale similar to auto, but with smaller granularity. Any bid over the cap falls into the next highest bucket. + +{: .table .table-bordered .table-striped } +| Increment | Cap | Number of Line Items Required per Bidder | +| --------- | --- | ---------------------------------------- | +| 0.01 | 3.00 | 301 | +| 0.05 | 8.00 | 100 | +| 0.50 | 20.00 | 24 | +| Any bid over 20.00 | 20.00 | n/a | +| | | Total: 425 | + + +#### Custom + +Custom buckets allow you to set your own price granularity. In determining what that granularity should be, we recommend analyzing your average bid prices from SSPs and placing them into a histogram. The price cap should be around your 95th-percentile bid, and there should be finer-grained buckets where more popular bid values are clustered. Note that if you use a [price floor](/dev-docs/modules/floors.html#price-floors-module), you shouldn't need fine-grained buckets below that floor. + +After you’ve determined what you’d like your granularity and caps to be, work with your software engineers to ensure the Prebid configuration matches your line item setup. + +## Pros and Cons + +As we mentioned earlier, you need to create a line item for every price that could come in from your header bidding demand partners. Without price buckets this could result in an almost infinite number of line items. Instead, you’ll need to weigh the pros and cons of high vs low granularity, and possibly adjust your granularities as you analyze the results of your Prebid implementation. + +The following examples give a general idea of the pros and cons of high and low granularity. + +### Example: High Price Granularity + +- 10 bidders +- Cap 20.00 +- Increment .01 +- Send top price: Minimum 2,000 line items +- Send all bids: Minimum 20,000 line items + +**Pro**: At .01 increments, there will be minimal price rounding (up to the price cap). All bids will compete at (or very near) the price the demand partner is willing to pay, maximizing revenue. + +**Con**: You have to create a lot of line items. The numbers shown above increase dramatically as you increase your price cap and your number of bidders. If you send all bids and add five more bidders, suddenly you need 10,000 more line items. + +### Example: Low Price Granularity + +- 10 bidders +- Cap 5.00 +- Increment 1.00 +- Send top price: Minimum 5 line items +- Send all bids: Minimum 50 line items + +**Pro**: Setting up your line items is a relatively quick process because you won’t need very many. You’re also less likely to run into volume limits your ad server might impose on numbers of line items. + +**Con**: Prices received from demand partners will be rounded down, so you could be losing money. A bid of 2.95 would be rounded down to 2.00, and lose to an ad server bid of 2.05. You’d be losing almost a dollar CPM. + +The following diagram, based on the high and low granularity scenarios with ten bidders we described above, illustrates just how quickly your line item count can grow. + +![Line Items Required per Price Granularity](/assets/images/ad-ops/planning/pg-line-items-required.png){: .center-image :} + +### Balanced Price Granularity + +Taking the pros and cons into consideration, you’ll want to balance your price granularity in a way that makes sense for your configuration. We recommend starting with the predefined Prebid price bucket that makes the most sense based on bids you expect, then adjusting as needed as you evaluate the results. The exceptions to this would be in the case of video (see below), and when you’re working with currencies that don’t fit well into the predefined values. In both these cases we recommend custom price granularities. + + +## Video Price Granularity + +The predefined price granularities in Prebid max out with price caps of 20.00. However, video inventory is often valued much higher. You don’t want to have a 20.00 price cap in place for inventory for which you’re expecting to receive 50.00 or more. For video inventory, we recommend you create custom price granularities. Determine the granularity and caps for your video inventory, and work with your software engineers to ensure they configure Prebid with custom price buckets to match your line items. + +## Mobile Price Granularity + +We’ve mentioned that you need to work with your software engineers to ensure the price buckets in the Prebid configuration match the line items you’re setting up in the ad server. However, if you’re setting up line items for advertising in a mobile app, your software engineers will be working with the Prebid Mobile SDK, which does not have price granularity controls; price buckets for mobile are set in Prebid Server. In this case you’ll need to work with your managed service provider to ensure price buckets are set up to match your line items. Note that from the ad server side, line item setup for price buckets is the same whether you’re working with mobile or web. + +## Next Step + +[Creative Considerations](/adops/creative-considerations) + +## Further Reader + +- [Planning Guide](/adops/adops-planning-guide.html) +- [Key Values for Ad Ops](/adops/key-values.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) +- [Deals in Prebid](/adops/deals.html) diff --git a/adops/send-all-vs-top-price.md b/adops/send-all-vs-top-price.md new file mode 100644 index 0000000000..de00664b6c --- /dev/null +++ b/adops/send-all-vs-top-price.md @@ -0,0 +1,154 @@ +--- +layout: page_v2 +title: Send All Bids vs Top Price +head_title: Send All Bids vs Top Price +sidebarType: 3 +sbUUID: 3.2 +--- + +# Send All Bids vs Top Price +{: .no_toc } + +* TOC +{: toc } + + +Prebid provides two options for the number of bids that will be sent to the ad server: + +Send all bids to the ad server that are received from the header bidding demand partners. This is the default behavior in Prebid. +Send only the top bid from among all the demand partner responses. + +{: .alert.alert-info :} +There is also a third option if you’re using deals. See [Deals in Prebid](/adops/deals.html) for more information. + + +Here’s a brief comparison chart showing the primary differences between these approaches. + +{: .table .table-bordered .table-striped } +| | Send All Bids (Default) | Send Top Price Bid | +| | ----------------------- | ------------------ | +| Number of bids sent to the ad server | Sends all bids that are received before the timeout period has expired. | Sends one bid per ad request. Only the bid with the top price for each request is sent. | +| Reporting | Gives your ad server the information to generate detailed reports on bids received from individual demand partners whether they are top bidders or not. | Your ad server can report only on bids it receives, so you won’t have visibility from within your ad server into bids from demand partners that were not top bidders. | +| Line Items | Typically requires a large number of line items to capture individual bidder information. | You can set up line items that are independent of the bidder, resulting in far fewer line items. | +| Key Value Pairs | Separate keys need to be defined for every bidder. | Only one set of keys needs to be defined. | +| Data considerations | The amount of information that is being sent to the ad server can become very large. You may need to place limits on the number of bids or key values that are sent. | You’re unlikely to run into any data issues when you’re sending information from only one bid. | + +## Send All Bids + +“Send all bids to the ad server” does exactly what it sounds like: every bid that comes in from demand partners before the specified timeout period will be sent to the ad server. (There are some limits, which we’ll talk about in a moment.) **This is the default behavior in Prebid.** + +### Reporting + +You might be wondering why you’d want to send more than the top bid. After all, if a bid wasn’t the top bid from the header bidding process, how could it possibly be the top bid after reaching the ad server? + +Realistically, it can’t. The main reason for sending all bids to the ad server is for reporting and optimization. With all bids, your ad server has the information it needs to provide you with reports that can tell you who bid on your inventory and what the bid price was. This helps you to: + +- Evaluate the bid rate of your demand partners +- Ensure contractual obligations with your demand partners are being met +- Adjust your Prebid settings based on who is bidding and for how much +- Evaluate the effectiveness of your current Prebid setup + +### Line Items + +When you send all bids, you’ll want to create a set of line items for each of your bidders. Each line item within a set (or a Google Ad Manager order) will be targeted towards a different price bucket. (See [Price Granularity](/adops/price-granularity.html) for more information.) While this is an ideal scenario for reporting, it can create difficulties in setting up line items. + +For example, suppose you have the following line item setup: + +- 200 prices +- 10 bidders + +This would require you to create 2000 line items (200 x 10). If, on the other hand, you didn’t need to separate out your line items by bidder, you would reduce this number dramatically to 200 line items (200 x 1). + +{: .alert.alert-info :} +The Send All Bids option also sends the top bid, so a hybrid scenario is possible where you need to create only one set of line items, but you’ll use all other variables passed in for reporting. + +In addition, some ad servers limit the number of line items you can create. Check with your ad server to ensure you won’t be exceeding this number. + +### Key Value Pairs + +{: .alert.alert-info :} +For an overview of key value targeting, see [Key Values](/adops/key-values.html). + +When you send all bids, you’ll need to have a set of keys defined for each bidder. This requires the creation of a lot of keys. For example, one bid could include five or more key value pairs. If you have ten bidders, this would require creation of at least 50 unique keys. + +{: .alert.alert-info :} +Because the number of key value pairs sent to the ad server can be very large, Prebid provides a number of ways to control this. See [Prebid.js Controls](/features/adServerKvps.html#controls) for engineering information on how to modify the amount of data being sent to the ad server. + +One thing to keep in mind is the length of your key values. When you create separate line items for each bidder, the keys you target will include the bidder name. For example, if you’re creating line items for BidderA, your key-value pairs will look something like this: + +hb_adid_BidderA=123456 +hb_pb_BidderA=2.10 +hb_size_BidderA=300x250 + +Some ad servers have limits on key name length. In Google Ad Manager (GAM) the maximum length is 20 characters. GAM will truncate any key name longer than 20 characters. For example: + +- One of your bidders is named BidderWithLongNameABC +- Prebid passes the creative size for this bidder in the key hb_size_BidderWithLongNameABC +- GAM truncates this name to hb_size_BidderWithLo + +When you enter the key values into the line item, you must use the truncated name: + +hb_size_BidderWithLo=300x250 + +If you forget about or are unaware of your ad server’s truncation and include the full name, the line item targeting will not match. + +{: .alert.alert-success :} +**Tip**: Prebid documentation lists the GAM truncated versions of ad server keys on each bidder parameter page. See [AndBeyondMedia](https://docs.prebid.org/dev-docs/bidders/andBeyondMedia.html) for an example. + + + +### Data Considerations + +Imagine you’re sending all bids to the ad server and you have the following scenario: + +- 15 bidders +- 7 key value pairs (KVPs) per bidder +- 25 characters per KVP + +You now have an ad request query string that is 2,625 characters long. There are many options for limiting the amount of data that’s sent on the query string. See [Configure Targeting Controls](/dev-docs/publisher-api-reference/setConfig.html#setConfig-targetingControls) for engineering options on reducing the amount of data being sent to the ad server. + + + + +## Send Top Price Bid + +“Send top price bid” is the simpler of the two options. With this approach, the only bid sent to the ad server with each ad request is the bid with the highest price. If multiple bidders respond with the same price, the bid from among those bidders that was received first is sent to the ad server. Here are some things to consider when deciding whether to go with this option. + +### Reporting + +The ad server can report only on the information it receives. So if you send only one bid from the header bidding process, the ad server can include only that one bid in your reports. Send top bid is a good option if: + +- you’re interested in reporting only on overall Prebid fill rates and top bid prices. +- you want to prioritize simplicity over detailed analysis of your header bidding results +- you don’t have any contractual obligations with demand partners that require more detailed reporting + +### Line Items + +If you’re sending only one bid with each ad request, there’s no need to create separate line items for each bidder. You can create one line for each price and creative size. For example: + +- 200 prices +- 1 bidder + +In this example you need to create only 200 line items (200 x 1). + + +### Key Value Pairs + +When you send only the top price bid to the ad server, you need to create only one generic set of keys. This means you’ll typically need to create five to ten keys to include in your line item targeting. + +Because the key names are the same no matter which bidder’s bid is sent to the ad server, key names will not include the name of the bidder. For example, the bid price will be sent in hb_pb rather than hb_pb_BidderName. This means you’re unlikely to have to worry about ad server limits on name lengths. See [Key Values](/adops/key-values.html) for details on setting key values in the ad server. + +### Data Considerations + +Send top bid sends the least amount of data possible to the ad server, and therefore has the least impact on client latency. + +## Next Step + +[Line Item Creation](/adops/line-item-creation.html) + +## Further Reader + +- [Planning Guide](/adops/adops-planning-guide.html) +- [Key Values for Ad Ops](/adops/key-values.html) +- [Prebid Universal Creative](/overview/prebid-universal-creative.html) +- [Deals in Prebid](/adops/deals.html) diff --git a/assets/images/ad-ops/planning/ad-ops-planning.png b/assets/images/ad-ops/planning/ad-ops-planning.png new file mode 100644 index 0000000000..38093ef397 Binary files /dev/null and b/assets/images/ad-ops/planning/ad-ops-planning.png differ diff --git a/assets/images/ad-ops/planning/pg-line-items-required.png b/assets/images/ad-ops/planning/pg-line-items-required.png new file mode 100644 index 0000000000..a94216005b Binary files /dev/null and b/assets/images/ad-ops/planning/pg-line-items-required.png differ diff --git a/dev-docs/bidders.md b/dev-docs/bidders.md index 4fc02d3ee4..a52a8bee0c 100644 --- a/dev-docs/bidders.md +++ b/dev-docs/bidders.md @@ -15,7 +15,7 @@ For each bidder listed below, you'll find the following information: {: .table .table-bordered .table-striped } | **Features** | A table of features supported by the adapter. | -| **"Send All Bids" Ad Server Keys** | Used for sending all bids to the ad server, as described in [Send All Bids to the Ad Server]({{site.baseurl}}/adops/send-all-bids-adops.html) | +| **"Send All Bids" Ad Server Keys** | Used for sending all bids to the ad server, as described in [Send All Bids vs Send Top Price]({{site.baseurl}}/adops/send-all-vs-top-price.html) | | **Bid Params** | Ad request parameters required by a given bidder, such as the tag ID, site ID, or query string parameters | You can also download the full CSV data file. diff --git a/dev-docs/pbs-bidders.md b/dev-docs/pbs-bidders.md index 5bf34c26ce..ca45b46a19 100644 --- a/dev-docs/pbs-bidders.md +++ b/dev-docs/pbs-bidders.md @@ -15,7 +15,7 @@ For each bidder listed below, you'll find the following information: {: .table .table-bordered .table-striped } | **Features** | A table of features supported by the adapter. | -| **"Send All Bids" Ad Server Keys** | Used for sending all bids to the ad server, as described in [Send All Bids to the Ad Server](/adops/send-all-bids-adops.html) | +| **"Send All Bids" Ad Server Keys** | Used for sending all bids to the ad server, as described in [Send All Bids vs Send Top Price](/adops/send-all-vs-top-price.html) | | **Bid Params** | Ad request parameters required by a given bidder, such as the tag ID, site ID, or query string parameters | You can also download the full CSV data file. diff --git a/overview/optimal-header-bidding-setup.md b/overview/optimal-header-bidding-setup.md index 64993e94f0..37732aaff1 100644 --- a/overview/optimal-header-bidding-setup.md +++ b/overview/optimal-header-bidding-setup.md @@ -1,6 +1,6 @@ --- layout: page_v2 -title: Optimal Header Bidding Setup +title: Analyze Header Bidding Setup description: What is the optimal header bidding setup and some common problems. pid: 10 @@ -13,7 +13,7 @@ sidebarType: 3 -# Optimal Header Bidding Setup +# Analyze Header Bidding Setup ### What's a good header bidding auction: @@ -141,9 +141,3 @@ Add the Plugin [Headerbid Expert](https://chrome.google.com/webstore/detail/head headerbid-expert-logo - - - - - -