Overview of the Header Bidding Library by Yandex

Overview of the Header Bidding Library by Yandex

Header Bidding (HB) is a technology that allows publishers to maximize revenue by conducting competitive auctions between SSPs and DSPs in real-time. "Yandex" has created its own closed implementation of Header Bidding (header-bidding.js) with internal mechanisms that are not publicly disclosed. The system is deeply integrated with AdFox and other Yandex services while also supporting work with external SSPs.

This analysis is based on publicly available code from the Yandex Header Bidding library, which is loaded into users' browsers and accessible for study via developer tools. All information is obtained exclusively from open sources and does not contain any confidential or internal data from Yandex.

I am not a professional developer, so this material should not be considered a guide for action or technical documentation. The description of the library's mechanisms is based on observations and analysis of available code — inaccuracies may occur. The author is not responsible for any errors or actions taken based on this information.

The material turned out to be extensive, but I plan to explore this topic even further in future publications.

Architecture

"Yandex" has implemented the HB library as a modular system with the following components:

  • Auction Configurator YaHeaderBiddingSettings — responsible for storing ad unit settings, SSPs, and timeouts.
  • Competitive Bidding Mechanism callBids — manages requests to SSPs and processes their responses.
  • SSP Adapters — specialized modules for interacting with various advertising platforms (SSPs).
  • Bid Processing Mechanism resolveBids — accumulates bids, determines the winner, and passes data to the ad unit.
  • Logging and Debugging Subsystem — ensures error tracking and problem diagnosis.
  • Cookie Matching — ensures synchronization of user identifiers across platforms.
Advertising Judgment Day

Configuration

The Header Bidding script is initialized via the global object YaHeaderBiddingSettings, which contains the following key settings:

  • Ad Units — description of ad slots and their associated SSPs.
  • Bidders Map — mapping table of adapters and their configurations.
  • Timeouts — execution time limits for requests.
  • Callbacks — mechanisms for processing results.

Bid Collection

The callBids() function is a key component of the auction mechanism. It manages requests to SSPs and bid processing, performing the following steps:

  1. Sends HTTP requests to all SSPs.
  2. Uses fetchBids() to retrieve responses (CPM, creative, identifier, and metadata from each SSP).
  3. Gathers all bids into an array using getBidsReceived() and getLastBidsReceived().

Winner Selection

The collected data is then sent to the server-side AdFox component (managed by the managerForAdfox object), which keeps Yandex’s bids hidden. Essentially, managerForAdfox acts as a "black box" — AdFox receives all the information through it and can influence the winner selection based on its internal criteria. Once processed, AdFox sends the auction winner information back to the client.

Ad Rendering

  1. If AdFox wins → the bid is sent back to AdFox, where the ad is loaded via its scripts.
  2. If an external SSP wins → the ad is inserted into the container using iframe or JavaScript.
Black Market of Identifiers

Cookie Matching

The Cookie Matching mechanism in Yandex's Header Bidding identifies users for precise ad targeting. Cookie Matching occurs before the auction starts: when the page loads, the browser sends a request to https://matchid.adfox.yandex.ru/getcookie, where AdFox checks for a unique identifier (e.g., yandexuid, cryptouid). These identifiers are then passed to SSPs to enhance CPM and ad personalization.

Integration with Other Yandex Services

The Header Bidding library integrates with Yandex's services into a unified advertising ecosystem:

  • AdFox — the central component of the system, managing auctions, aggregating bids, and distributing traffic among SSPs.
  • Yandex.Metrica — collects user data and evaluates ad impression effectiveness through request parameters and Cookie Matching.
  • Yandex.Direct — there seems to be interaction with this service in the code, but its purpose is unclear.
  • Yandex.Crypta — analyzes audience data to optimize targeting and ad personalization. The exact details of this integration are unclear, but the presence of cryptouid suggests a direct link.
  • Yandex ID and Cookie Matching — synchronizes user identifiers across Yandex’s advertising systems to enhance cross-platform targeting.

SSP Platforms Mentioned in the Library Code (as of February 2025, in alphabetical order):

You can check the market share of these adapters in Russia on HBTracker Battleboard.

The Immortal Algorithm

Conclusion

On the client-side, Yandex's Header Bidding library provides a transparent auction where the winner is determined solely based on the highest CPM without bid manipulations or SSP preferences. The client-side code does not contain mechanisms for artificially lowering bids or substituting the winner. However, the final bid processing occurs on the server side via integration with AdFox, where additional adjustments may be made that are not reflected in the client-side code.

More materials: