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