Transition PAAPI parameters to updated IAB conventions

[bretg]

The formal Protected Audience ORTB extensions have been merged to https://github.com/InteractiveAdvertisingBureau/openrtb/blob/main/extensions/community_extensions/Protected%20Audience%20Support.md

Request

The request side is fairly straightforward.

Instead of imp.ext.ae with values 0 and 1, the new location is imp.ext.igs.ae that can have these values:

0 = Interest Group auction not supported
1 = on-device-orchestrated Interest Group auction
3 = server-orchestrated Interest Group auction

The proposal is to have PBS-core check if imp.ext.igs.ae doesn't exist but imp.ext.ae does, then map imp.ext.ae:0 to imp.ext.igs.ae:0 and imp.ext.ae:1 to imp.ext.igs.ae:1. Do not map any other values -- i.e. if imp.ext.igs.ae:3, pass it through, but do not map from imp.ext.ae.

Response

Given the lack of a standard, Prebid came up with our own syntax for where to put auctionconfigs: ext.prebid.fledge. There's now a formal location, which is

• ext.igi.igs.config: this is the seller 'auctionconfig' that is currently being used in the trial.
• ext.igi.igb.{pbs,ps}: this is a new thing, but it's possible that buyers have direct Prebid Server adapters and can submit this object.

Original Prebid response extension:

{
  ext: {
    prebid: {
      fledge: {
        auctionconfigs: [{
          impid: "123",
          bidder: "bidderA",     // adapterB was called with alias bidderA
          adapter: "bidderB",
          config: { ... }
       },{
          impid: "123",
          bidder: "bidderC",
          adapter: "bidderC",
          config: { ... }
       }]
     }
  }
}

New ORTB format

The new response design is more complex than the original - adapter from buyers may respond with an igb object, while adapters from sellers may respond with igs objects. In both cases, Prebid.js still wants to know which bidder submitted the value, so we need to extend the IAB's structure.

  "ext": {
    "igi":[{
      "impid": "1",
      "igb":[{   	 
        "origin": "https://paapi.dsp.com",
        "pbs": "{\"key\": \"value\"}"
      }],
      "ext": {
          bidder: "bidderA",     // adapterB was called with alias bidderA
          adapter: "bidderB"
      }
     },{
      "igs":[{
        "impid": "1",
        "config": {
          ... auctionConfig ...
        },
        "ext": {
          bidder: "bidderA",     // adapterB was called with alias bidderA
          adapter: "bidderB"
        }
      }]
    }]
  }

Open Items:

• how should bid adapters return these values?
• how should PBS-core aggregate them
• should there be a transition period where PBS-core sends both locations?
• should there be a request flag that indicates where the response is expected?

[bretg]

Discussed in committee

how should bid adapters return these ext.igi values?

e.g. PBS-Go specifically names fledge auctionconfig as something a bid adapter returns.

This can be decided in the regular flow of design and implementation by the PBS-Go and PBS-Java teams.

how should PBS-core aggregate them

Use the request-defined output format as part of the normalization algorithm.

e.g. If "original" output format, then igb responses are ignored.

@bretg to take a stab at fleshing this out.

should there be a transition period where PBS-core sends both locations?

No.

should there be a request flag that indicates where the response is expected?

Yes, there should be a request flag that defines the output format. ext.prebid.SOMETHING.paaformat: {"original", "iab"}. (default to "original")

[bretg]

Configuring the output format

Currently PBS places results only on ext.prebid.fledge.auctionconfigs, and this will continue to be the default for the foreseeable future. However, some future version of Prebid.js will be able to read PAA bids from the new official IAB-ratified location.

An example of the original Prebid output format

{
  ext: {
    prebid: {
      fledge: {
        auctionconfigs: [{
          impid: "123",
          bidder: "bidderA",     // adapterB was called with alias bidderA
          adapter: "bidderB",
          config: { ... }
       },{
          impid: "123",
          bidder: "bidderC",
          adapter: "bidderC",
          config: { ... }
       }]
     }
  }
}

Request Level Configuration

That future version of Prebid.js should be able to set a request flag to let Prebid Server know that it's ready to receive the new format:

ext.prebid.paaformat: "original" or "iab"

The default value of this is still under discussion.

Account Configuration

It's not clear that account-level config makes that much sense in the medium term, but perhaps in the long term it may make sense.

    auction:
        paaformat: "iab"

Generating the output

Bid adapters will be providing a mix of old and new formats, so we need to define how to map between the representations.

Creating IAB output format

When a bidder supplies the original fledge auctionconfig:

1. Add a new igs object instance to the ext.igi.igs array
2. Set the impid appropriately
3. config is the bidder-supplied fledge auctionconfig
4. add ext.igi.igs.ext.bidder and ext.igi.igs.ext.adapter

e.g.

  "ext": {
    "igi":[{
      "igs":[{
        "impid": "x",
        "config": {
          ... Bidder-supplied fledge auctionconfig ...
        },
        "ext": {
          bidder: "bidderAA",     // bidderA was called with alias bidderAA
          adapter: "bidderA"
        }
      }]
    }]
  }

When a bidder supplies the new IAB format

1. Loop through the bidder's igi array
2. If there's no impid, then drop any igb objects from this entry. If any were dropped, mmit a warning in debug mode, log at N% sampling, and emit an alert.general metric.
3. Loop through the igs array
   1. If there's no impid and config, then drop this entry. Emit a warning in debug mode, log at N% sampling, and emit an alert.general metric.
   2. Add ext.bidder and ext.adapter to the igs entry
   3. Add the igs entry to the global response entry
4. Loop through the igb array
   1. Add ext.bidder and ext.adapter to the igb entry
   2. Add the igb entry to the global response entry

Creating old output format

When a bidder supplies the original ext.prebid.fledge.auctionconfigs in the response, merge as it happens today.

When a bidder supplies an IAB ext.igi array

1. Loop through the igi array
2. Ignore any igb objects. The old format doesn't support buyer auctionconfig. (?)
3. Loop through igs array
   1. If there's no impid and config, then drop this entry. Emit a warning in debug mode, log at N% sampling, and emit an alert.general metric.
   2. Copy impid in the igi object to ext.prebid.fledge.auctionconfigs[].impid
      3, Add the config object to ext.prebid.fledge.auctionconfigs[].config.
   3. Copy the bidder and adapter codes to the ext.prebid.fledge.auctionconfigs[] object

The bidder code is the seat as defined in #3363.

[bretg]

For PBS-java, there are only 6 bid adapters providing auctioninfo. The engineers have proposed to just go ahead and convert those 6 to return igi.igs right from the adapter, eliminating the need to do a conversion from old-to-new in PBS-core.

• We will alert the 6 adapter owners to the change
• For a transition period, PBS-core will still look for auctioninfo and return it in case there are private adapters out there

@bsardo , @justadreamer , @SyntaxNode - thoughts?