From 88a9c36ee124368a295efbea915810f9cdce06e7 Mon Sep 17 00:00:00 2001 From: vasujain00 Date: Thu, 12 Mar 2026 13:10:10 +0530 Subject: [PATCH] Add minimum cache TTL for targeted bids in setConfig documentation Enhanced the documentation for the `setConfig` method to include details on the `minWinningBidCacheTTL` setting. This addition clarifies how to manage bid caching for targeted bids, addressing potential issues with ad rendering delays and memory trade-offs. Included code examples and considerations for publishers regarding bid expiration and memory usage. --- dev-docs/publisher-api-reference/setConfig.md | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/dev-docs/publisher-api-reference/setConfig.md b/dev-docs/publisher-api-reference/setConfig.md index 801b453c6b..c27d0a7748 100644 --- a/dev-docs/publisher-api-reference/setConfig.md +++ b/dev-docs/publisher-api-reference/setConfig.md @@ -346,6 +346,43 @@ When set, bids are only kept in memory for the duration of their actual TTL life Put another way, this setting doesn't define each bid's TTL, but rather controls how long it's kept around in memory for analytics purposes. +### Minimum cache TTL for targeted bids + + + +When using `minBidCacheTTL` to limit how long bids stay in memory, bids that have already been sent to the ad server (targeting set) can expire before the ad is rendered. This often happens with GPT lazy load or other delayed render: the ad is requested and targeting is set, but the slot only renders when the user scrolls. If the bid is dropped from cache before render, you may see "cannot find ad" (or similar) errors. + +Use **`minWinningBidCacheTTL`** (sometimes discussed as **`minTargetedBidCacheTTL`**) to give targeted bids a longer (or unlimited) cache time than other bids: + +```javascript +pbjs.setConfig({ + minBidCacheTTL: 30, // drop non-winning bids after 30s + minWinningBidCacheTTL: Infinity // keep targeted bids until page unload (lazy-load / long-delay render) +}); +``` + +* When set, it overrides `minBidCacheTTL` only for bids that have had **targeting set** (e.g. sent to GPT via `setTargetingForGPTAsync` / `setTargetingForGPT`). +* When unset, all bids use `minBidCacheTTL` (current behavior). +* Use a number (seconds) for a longer but finite TTL, or `Infinity` to keep targeted bids for the life of the page. + +#### Publisher choices when using bid cache TTL +{: .no_toc} + +If you use `minBidCacheTTL` (with or without `minWinningBidCacheTTL`), you are making a tradeoff between memory and ad availability. Be explicit about what should happen when: + +1. A bid expires after targeting but before render + * Rely on `minWinningBidCacheTTL` so targeted bids stay in cache until render, or + * Accept that the slot may show no ad / blank, or + * Run a new auction when the slot is about to render (e.g. in a lazy-load callback). + +2. Bids are dropped for memory saving + * Decide whether you prefer lower memory (shorter TTL) or fewer "missing ad" cases (longer TTL or `minWinningBidCacheTTL`). + +#### SSP / revenue note +{: .no_toc} + +Bids have a TTL from the bidder/SSP. If an ad is rendered **after** that TTL, the SSP may treat the bid as expired and not attribute revenue. Keeping bids in Prebid’s cache longer (e.g. with `minWinningBidCacheTTL`) does not change the SSP’s own TTL. Use this setting when the delay is on your side (e.g. lazy load), not to extend the SSP’s idea of when the bid is valid. + ### Event history TTL