Deals in Protected Audience

Implementing deals, also known as Private Marketplace (PMP), in a Protected Audience auction

Overview

Deals, also referred to as Private Marketplace (PMP), offer curated access or preferred pricing for buyers on a subset of inventory. To facilitate programmatic deals, seat IDs and deal IDs are used:

  • A seat ID originates from the buyer, and is an identifier that represents the buyer's customer. A seat ID may have billing implications, for example, if a seat has a discount with a given seller.
  • A deal ID originates from either the buyer or the seller, and is an identifier that represents an agreement between a buyer and a seller. A deal ID may have properties such as a cost/price, volume commitment, audience information, exclusivity, and more.

Protected Audience facilitates deals by using reporting IDs which allows seat and deal IDs to become available for auction bidding, scoring, and reporting. The reporting IDs provide a mechanism for ad tech companies to receive these deal and seat IDs in post-auction Protected Audience reporting to transact deals and organize billing efforts. We expect that buyers, sellers, agencies and advertisers may have bespoke strategies to interpret and understand the deal and seat IDs that they receive.

Walkthrough

The steps to facilitate deals in a Protected Audience auction is as follows:

  1. The buyer registers the deal and seat IDs in the interest group config before the auction runs
    • Deal and seat IDs can be set in the selectable reporting IDs field (selectableBuyerAndSellerReportingIds).
    • If the seat ID is the same for all deals, then that seat ID can be set in buyerAndSellerReportingId, and the deal IDs can be set in the selectable reporting IDs field (selectableBuyerAndSellerReportingIds).
  2. During bid generation, the deal and seat IDs become available. The buyer selects a deal ID from selectableBuyerAndSellerReportingIds. The buyer generates a bid that includes a deal ID associated with that bid by returning a selectedBuyerAndSellerReportingId. A bid may only win the auction if the returned deal ID is k-anonymous alongside other reporting IDs and select properties of the interest group.
  3. During ad scoring, the selected deal and seat IDs become available to the seller.
  4. The deal and seat IDs become available in the seller's reporting functions.
  5. The deal and seat IDs become available in the buyer's reporting functions.

1. Deal and seat IDs registration

The buyer registers the deal and seat IDs in the interest group config before the auction runs. The deal and seat IDs are set in selectableBuyerAndSellerReportingIds as an array of strings. If the seat ID is the same for all deals, and they don't need to be repeated, the seat ID can be added in the buyerAndSellerReportingId field which accepts a string:

const interestGroupConfig = {
  owner: 'https://buyer.example',
  name: 'example-ig',
  ad: [
    {
      renderURL: 'https://buyer.example/ad.html',
      selectableBuyerAndSellerReportingIds: ['deal123', 'deal456', 'deal789'], // Deal IDs
      buyerAndSellerReportingId: 'seat123', // Seat ID

      // Though it is not used to facilitate deals, the buyer
      // reporting ID can be defined with other reporting IDs
      buyerAndReportingId: 'brid123'
    },
  ],
};

navigator.joinAdInterestGroup(interestGroupConfig);

If the seat ID is different for the deals, the following setup can be used:

const interestGroupConfig = {
  owner: 'https://buyer.example',
  name: 'example-ig',
  ad: [
    {
      renderURL: 'https://buyer.example/ad.html',
      selectableBuyerAndSellerReportingIds: [
        'deal123seat123',
        'deal456seat456',
        'deal789seat456'
      ], // Deal and Seat IDs
    },
  ],
};

navigator.joinAdInterestGroup(interestGroupConfig);

2. Deal and seat IDs for buyers during bid generation

During bid generation, the buyer decides if they want to bid on a deal ID. In generateBid(), the buyer can select a deal ID from selectableBuyerAndSellerReportingIds, and return the value as selectedBuyerAndSellerReportingId. The bid is rejected if the selected deal ID is not in the selectableBuyerAndSellerReportingIds array.

function generateBid(interestGroup, ...) {
  const [{
    buyerAndSellerReportingId, // 'seat123'
    selectableBuyerAndSellerReportingIds // ['deal123', 'deal456', 'deal789']
    buyerAndReportingId // 'brid123' - Not used for deals, but the value is available
  }] = interestGroup.ads;

  // ...

  return {
    bid: 1,
    render: 'https://buyer.example/ad.html',
    selectedBuyerAndSellerReportingId: 'deal456', // Buyer selects a deal ID
  };
}

A bid with a returned value for selectedbuyerAndSellerReportingId may only win the auction if the value of selectedbuyerAndSellerReportingId is jointly k-anonymous along with buyerAndSellerReportingId (if present), buyerReportingId (if present) the interest group owner, bidding script URL, render URL, and ad size (ad size is excluded from this check until at least Q1 2025).

Even if selectablebuyerAndSellerReportingIds is defined in the interest group config, it's still valid for generateBid() to return a bid that doesn't include a selectedbuyerAndSellerReportingId; in this case, the reporting IDs provided to the reporting functions if this bid wins will follow the non-selectable reporting ID behavior.

In cases where generateBid() is rerun because the initial invocation didn't produced any bids with ads that passed the k-anonymity checks, then selectableBuyerAndSellerReportingIds that don't pass the k-anonymity check won't be present in the interest group on the re-run.

3. Deal and seat IDs for sellers during ad scoring

The selected deal ID, along with a seat ID if present, are made accessible to scoreAd(). The seller provides the desirability score of the winning bid with consideration of the deal ID and any special terms. If the seller does not think the buyer-chosen deal ID applies, then the seller rejects the bid by giving it a zero or negative desirability score.

function scoreAd(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingIds, // 'deal456'
  } = browserSignals;

  // ...
}

4. Deal and seat IDs for sellers reporting

Recall that a bid may only win the auction if selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (if present), and buyerReportingId (if present) are k-anonymous with the interest group owner, bidding script URL, render URL, and ad size (ad size is excluded from this check until at least Q1 2025). As such, reporting ID values that include a selectedBuyerAndSellerReportingId will be always available inside reportResult(). Note that even though buyerReportingId is checked for k-anonymity, the value is only available to the buyer reporting function, and not the seller reporting function here.

function reportResult(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingIds // 'deal456'
  } = browserSignals;

  // ...
}

5. Deal and seat IDs for buyer reporting

The same concept from sellers reporting applies to buyers reporting. Recall that a bid may only win the auction if selectedBuyerAndSellerReportingId, buyerAndSellerReportingId (if present), and buyerReportingId (if present) are k-anonymous with the interest group owner, bidding script URL, render URL, and ad size (ad size is excluded from this check until at least Q1 2025). As such, reporting ID values that include a selectedBuyerAndSellerReportingId will always be available inside reportWin().

function reportWin(..., browserSignals, ...) {
  const {
    buyerAndSellerReportingId, // 'seat123'
    selectedBuyerAndSellerReportingId // 'deal456'
    buyerAndReportingId // 'brid123' - Not used for deals, but the value is available
  } = browserSignals;
}

Engage and share feedback