Pace ad delivery by frequency

Learn how an ad buyer (DSP and advertiser) running an ad campaign, can control the ad delivery pace by how often the user has seen or interacted with an ad. Controlling ad delivery by frequency improves audience experience by avoiding ad fatigue, and increases revenue by reaching more users with the same budget. This guide shows multiple approaches to working with ad frequency.

Leave an interest group

You can call navigator.leaveAdInterestGroup() to request that a user's browser leave an interest group when an ad is clicked. From inside the winning ad frame and its sub-frames, you can call leaveAdInterestGroup() as long as the origin of the frame is the same as the interest group's origin. One approach that could be taken is adding an invisible sub-frame inside the ad frame that is responsible for leaving the interest group.

Leaving the ad interest group prevents future bidding, and acts as a form of frequency capping.

Use prevWinsMs signal during bid generation

For simple frequency control, you can use the prevWinsMs field in browserSignals inside generateBid().

The prevWinMs field contains the interest group's winning ads, and the time since their previous wins in milliseconds. Note that the ad object here only contains the renderURL and metadata fields.

Use this signal to determine if the ad should be delivered. Returning a bid value of 0 will ensure that the ad won't win the auction.

You can also use a first-party cookie to store click information. When the ad is rendered, overwrite an existing interest group with the click data as user bidding signals (userBiddingSignals).

The following diagram describes the sequence:

A diagram that describes the sequence for storing click data in a first-party cookie and reading it at a later time for frequency control

  1. The user visits the advertiser's page
  2. The buyer (advertiser/DSP) initializes a click data array in the first party cookie.
  3. The buyer (advertiser/DSP) adds the user to an interest group, and sets the initial clicks array in the userBiddingSignals field.
  4. At a later time, the user visits the publisher's page.
  5. The seller (publisher/DSP) executes a Protected Audience auction, and the winning ad is rendered to the user.
  6. The user clicks on the winning ad.
  7. The user is navigated to the advertiser page.
    • The clickthrough URL contains the interest group name as a query param
  8. The buyer (advertiser/DSP) reads the existing first-party cookie
  9. The buyer (advertiser/DSP) adds the new click timestamp to the existing click data
  10. The buyer (advertiser/DSP) updates the interest group with the new click data.
  11. The buyer (advertiser/DSP) updates the first-party cookie with the new click data.

The timestamp in the click field of userBiddingSignals becomes available inside the generateBid() function when the user visits the publisher page again, and the buyer can use this data to control ad delivery.

What's next?

We want to engage in conversations with you to ensure we build an API that works for everyone.

Discuss the API

Like other Privacy Sandbox APIs, this API is documented and discussed publicly.

Experiment with the API

You can experiment and participate in conversation about the Protected Audience API.