Define scroll and refresh auction strategy for server-side ad templates

[prk-Jr]

Context

The current POST /auction endpoint is stateless and has no slot-template awareness or GPT lifecycle integration. It can technically serve scroll/refresh requests (full consent pipeline runs, EC ID generated per-call), but:

• Caller must construct adUnits explicitly — no template expansion from creative-opportunities.toml
• No session threading — each call is independent
• No GPT slotRenderEnded or refresh event coordination

Per the server-side ad templates design spec §4.6, slim-Prebid owns scroll and refresh client-side for Phase 1. slim-Prebid runs post-window.load, handles GPT refresh events, and runs client-side auctions for slots that have already rendered their initial TS-served impression.

Decisions needed

• Phase 1 (current): Confirm slim-Prebid as the scroll/refresh owner. Document that /auction is not the intended path for these events.
• Phase 2 (future): Define whether a server-side refresh API makes sense — e.g. a slot-template-aware POST /auction/refresh?slotIds=atf_sidebar_ad that expands from creative-opportunities.toml and returns updated bids without requiring the caller to know bidder params.
• SPA navigation: Pure client-side SPAs (pushState routing) do not trigger TS page-level auctions. Document this gap and confirm slim-Prebid handles the SPA refresh case.

Action

• Add a comment to auction/endpoints.rs clarifying that /auction is for initial-render and programmatic use, not scroll/refresh
• Document the slim-Prebid handoff contract in the tsjs GPT integration
• Track Phase 2 server-side refresh API as a follow-up (do not design now)

Parent: #677

---

Resolution

Phase 1 confirmed: slim-Prebid owns scroll and refresh client-side. Server-side has no scroll/refresh mechanism.

Current behavior by scenario:

• SPA navigation (pushState/popstate): browser calls GET /__ts/page-bids?path=/new-route → server runs fresh build_auction_request for the new path → returns bids as JSON → slim-Prebid injects them. Scoped to navigation events only, not scroll.
• Scroll (lazy-load): no server-side mechanism. Slim-Prebid fires new auctions on scroll events client-side via Prebid.js requestBids. If slim-Prebid is not on the page (pure server-side mode), scroll ads do not auto-refresh.
• Hard refresh: browser issues a fresh page load → full server-side auction runs from scratch as a normal publisher request — no special handling needed.
• POST /auction/refresh: deferred — not implemented. Required before pure server-side deployments (no slim-Prebid) can support lazy-load scroll ads.

Key constraint for pure server-side mode: without slim-Prebid, scroll-triggered lazy-load auctions are blocked on POST /auction/refresh being implemented first.