diff --git a/_data/sidebar.yml b/_data/sidebar.yml index 5a3c2a4968..c4f7947464 100644 --- a/_data/sidebar.yml +++ b/_data/sidebar.yml @@ -506,6 +506,14 @@ sectionTitle: subgroup: 8 +- sbSecId: 1 + title: Timeouts + link: /features/timeouts.html + isHeader: 0 + isSectionHeader: 0 + sectionTitle: + subgroup: 8 + #--------------Prebid Mobile--------------| diff --git a/assets/images/dev-docs/prebid-timeouts.png b/assets/images/dev-docs/prebid-timeouts.png new file mode 100644 index 0000000000..543a4ce5b0 Binary files /dev/null and b/assets/images/dev-docs/prebid-timeouts.png differ diff --git a/dev-docs/faq.md b/dev-docs/faq.md index 17c4ed7e1f..0767e28a96 100644 --- a/dev-docs/faq.md +++ b/dev-docs/faq.md @@ -25,12 +25,12 @@ Nope. The only approval process is a code review. There are separate instruction As for [membership](https://prebid.org/membership/) in Prebid.org, that's entirely optional -- we'd be happy to have you join and participate in the various committees, but it's not necessary for contributing code as a community member. -## When starting out, what should my timeouts be? +## What should my timeouts be? Below is a set of recommended best practice starting points for your timeout settings: - 1,000 milliseconds or less for the internal auction timeout -- 3,000 milliseconds or less for the prebid tag's overall failsafe timeout +- 3,000 milliseconds or less for the Prebid tag's overall failsafe timeout The former setting is used to track the auction once it started; if it expires, we will use whichever bidders have responded and select the winner(s) accordingly. @@ -38,6 +38,8 @@ The latter setting is used when for some reason Prebid did not load (or there's For examples of setting up these timeouts, please refer to the [Basic Example]({{site.baseurl}}/dev-docs/examples/basic-example.html) page. +See the [Prebid Timeouts Reference](/features/timeouts.html) for more information about timeouts in general. + ## How many header bidders should I have? Every publisher is different. In order to answer this question you'll need to run some tests, gather data, and decide what works for you based on your performance and monetization needs. diff --git a/dev-docs/publisher-api-reference.md b/dev-docs/publisher-api-reference.md index 0aa1a7796f..f8d324d3e0 100644 --- a/dev-docs/publisher-api-reference.md +++ b/dev-docs/publisher-api-reference.md @@ -1801,6 +1801,10 @@ a price granularity override. If it doesn't find 'video-outstream' defined, it w #### Server to Server +{: .alert.alert-info :} +Use of this config option requires the `prebidServerBidAdapter` module. + + Prebid.js can be configured to connect to one or more [Prebid Servers](/prebid-server/overview/prebid-server-overview.html) for one or more bidders. Example config: diff --git a/features/timeouts.md b/features/timeouts.md new file mode 100644 index 0000000000..9b1c013f9e --- /dev/null +++ b/features/timeouts.md @@ -0,0 +1,61 @@ +--- +layout: page_v2 +title: Prebid Ad Slot +description: The Prebid Ad Slot +sidebarType: 1 +--- + +# Prebid Timeouts + +Header bidding needs some time to collect bids. Publishers update their +pages to delay the ad server call for just long enough to get bids, but +not so long as to reduce overall revenue. This delay is controlled by +a number of timeouts and adjustments. + +The following diagram summarizes the timeouts in Prebid.js and Prebid Server. + +![Timeout](/assets/images/dev-docs/prebid-timeouts.png){:class="pb-xlg-img"} + +1. **Failsafe Timeout** - This is a timeout entirely outside of Prebid.js. It's a +JavaScript setTimeout() that publishers should consider establishing +after the Prebid.js code is loaded. It's a safety net that invokes the ad +server callback in case something goes wrong. In all regular scenarios, +Prebid.js will have already invoked the callback before this timeout is reached. This value should be much larger than the auction timeout. +2. **Auction Timeout** - This value defines the amount of time the page has to coordinate the +header bidding activities. Determining this value is a delicate balance: too short, and header bidding won't have enough time to take place; too long, and revenue +may go down due to delaying the ad server call to the point where users have left +the page. Publishers must determine the value that works for them, considering +a balance of factors: average user time on page, direct sellthrough, value of different ad channels, and average user network delay. +3. **Timout Buffer** - The JavaScript timer environment is not perfectly accurate +because competing JavaScript on the page can delay the header bidding auction +or the recognition that auction results have returned. By default, Prebid.js adds a 400ms buffer to the Auction Timeout to account for the noisy environment. Publishers can +change this default value with the [`timeoutBuffer`](/dev-docs/publisher-api-reference.html#setConfig-timeoutBuffer) configuration. +4. **Prebid Server s2sConfig Timeout** - In order to make sure that Prebid Server +bids can get back to the client in time for the ad server call, publishers +should consider setting [s2sConfig.timeout](/dev-docs/publisher-api-reference.html#setConfig-Server-to-Server) to a value lower than the Auction Timeout. How much lower depends on average user network delay, but should probably be within the range of 50%-75% of the Auction Timeout. This value is sent in the Prebid Server OpenRTB as `tmax`. +5. **Timeout Adjustment** - In order to minimize the chance of missing the client-side +ad server call, Prebid Server shaves off a safety buffer and responds to the client a little before the `tmax` value time is up. The Prebid Server host company sets two +configurable values (`auction.timeout-adjustment-ms` and `auction.cache.expected-request-time-ms`), which can be expected to shave 30-100ms off of `tmax`. For example, if tmax=1000 and the Prebid Server host company has 40ms of safety margin configured, +bidders will actually timeout at 960ms. + +### Prebid SDK Timeouts + +Apps using the Prebid SDK can set the Prebid Server `tmax` value with the `setTimeoutMillis()` function. + +This value will override the default that's set in the top level stored request. + +There is no "Timeout Buffer" in the SDK scenario, but Prebid Server will shave +off the Timeout Adjustment. + +### AMP Timeouts + +AMP pages may pass a timeout attribute on the query string. This value will override the default that's set in the stored request. + +There is no "Timeout Buffer" in the AMP scenario, but Prebid Server will shave +off the Timeout Adjustment. + +## Related Resources + +- [Prebid.js timeoutBuffer](/dev-docs/publisher-api-reference.html#setConfig-timeoutBuffer) +- [FAQ: What should I set my timeouts to?](/dev-docs/faq.html#what-should-my-timeouts-be) +- [Prebid.js s2sConfig](/dev-docs/publisher-api-reference.html#setConfig-Server-to-Server)