Skip to content

Commit 7a01426

Browse files
authored
Docs: add minWinningBidCacheTTL / targeted-bid cache TTL to setConfig (#6479)
* 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. * Update setConfig documentation to clarify minimum cache TTL for targeted bids Renamed `minWinningBidCacheTTL` to `minTargetedBidCacheTTL` in the documentation to accurately reflect its purpose. Updated explanations and code examples to enhance clarity on managing bid caching and the implications for ad rendering and memory usage.
1 parent 93a1b07 commit 7a01426

1 file changed

Lines changed: 37 additions & 0 deletions

File tree

dev-docs/publisher-api-reference/setConfig.md

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -346,6 +346,43 @@ When set, bids are only kept in memory for the duration of their actual TTL life
346346

347347
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.
348348

349+
### Minimum cache TTL for targeted bids
350+
351+
<a id="setConfig-minTargetedBidCacheTTL"></a>
352+
353+
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.
354+
355+
Use **`minTargetedBidCacheTTL`** to give targeted bids a longer (or unlimited) cache time than other bids:
356+
357+
```javascript
358+
pbjs.setConfig({
359+
minBidCacheTTL: 30, // drop non-targeted bids after 30s
360+
minTargetedBidCacheTTL: Infinity // keep targeted bids until page unload (lazy-load / long-delay render)
361+
});
362+
```
363+
364+
* When set, it overrides `minBidCacheTTL` only for bids that have had **targeting set** (e.g. sent to GPT via `setTargetingForGPTAsync` / `setTargetingForGPT`).
365+
* When unset, all bids use `minBidCacheTTL` (current behavior).
366+
* Use a number (seconds) for a longer but finite TTL, or `Infinity` to keep targeted bids for the life of the page.
367+
368+
#### Publisher choices when using bid cache TTL
369+
{: .no_toc}
370+
371+
If you use `minBidCacheTTL` (with or without `minTargetedBidCacheTTL`), you are making a tradeoff between memory and ad availability. Be explicit about what should happen when:
372+
373+
1. A bid expires after targeting but before render
374+
* Rely on `minTargetedBidCacheTTL` so targeted bids stay in cache until render, or
375+
* Accept that the slot may show no ad / blank, or
376+
* Run a new auction when the slot is about to render (e.g. in a lazy-load callback).
377+
378+
2. Bids are dropped for memory saving
379+
* Decide whether you prefer lower memory (shorter TTL) or fewer "missing ad" cases (longer TTL or `minTargetedBidCacheTTL`).
380+
381+
#### SSP / revenue note
382+
{: .no_toc}
383+
384+
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 may not attribute revenue. Keeping bids in Prebid's cache longer (e.g. with `minTargetedBidCacheTTL`) 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.
385+
349386
### Event history TTL
350387

351388
<a id="setConfig-eventHistoryTTL"></a>

0 commit comments

Comments
 (0)