Ads
KV Waterfall
How ad pricing key-values cascade from URL to tenant to defaults.
KV Waterfall
GAM ad requests use key-values (KVs) for tiered pricing. When an ad doesn't fill at one price point, the system cycles to the next KV value.
Config hierarchy
KV fields by placement
| Placement | Category field | Tenant field | Article field |
|---|---|---|---|
| Display | displayKv1Values | displayKv1ValuesCategory | — |
| Display 2 | displayKv1Values2 | — | — |
| Interstitial | interstitialKv1Values | interstitialKv1Values | — |
| Rewarded (KV1) | rewardedKv1Values | rewardedKv1Values | — |
| Rewarded (KV2) | rewardedKv1ValuesSecondPage | rewardedKv1ValuesSecondPage | — |
| Skyscraper L/R | skyscrapperLeft/RightKv1Values | — | — |
| Sticky | stickyKv1Values | — | — |
| Collapsible | collapsibleKv1Values | collapsibleKv1Values | — |
Resolution helpers
File: lib/utils/adConfig.js
| Function | Purpose |
|---|---|
getDisplayKv1Values() | Display ad KV fallback |
getInterstitialKv1Values() | Interstitial KV fallback |
getRewardedKv1Values() | Rewarded KV1 fallback |
getRewardedKv2Values() | Rewarded KV2 fallback |
KV encoding
KV values are encoded at the service layer via lib/utils/kvEncoding.js before being passed to client components. This prevents raw pricing data from being visible in page source.
Time-specific override
Hour-based KV sets can override static values. See Time-Specific KVs.
AdSense note
AdSense provider does not use KV waterfalls. Pricing is handled by Google's auction.