PAAPI: parallel contextual and IG auctions

[dgirardi]

Type of change

• Feature

Description of change

Adapters can provide a spec.buildPAAPIConfigs(validBidRequests, bidderRequest) to be included in PAAPI auctions that can be started in parallel to contextual auctions.

If PAAPI is enabled, and an adapter provides buildPAAPIConfigs, it is invoked just before buildRequests, and takes the same arguments. It should return an array of PAAPI configuration objects with the same format as in interpretResponse ({bidId, config?, igb?}).

Everything returned by buildPAAPIConfigs is treated in the same way as if it was returned by interpretResponse - except for signals that can be provided asynchronously (cfr. ASYNC_SIGNALS), which are replaced by promises. When the (contextual) auction ends, the promises are resolved.

If during the auction the adapter's interpretResponse returned matching configurations (same bidId, and a config with the same seller, or an igb with the same origin), the promises resolve to their contents. Otherwise, they resolve to the values provided by buildPAAPIConfigs, or an empty object if no value was provided.

Promisified auction configs are available from getPAAPIConfig immediately after requestBids. If the paapi.parallel config flag is set, PAAPI submodules are also triggered at the same time (instead of when the auction ends). Currently this is only relevant with topLevelPAAPI, where it has the effect of starting PAAPI auctions at the time of requestBids. The same could be done for GAM/paapiForGpt as soon as we have a method to trigger its PAAPI auctions separately from targeting/slot refreshes.

Other information

Closes #11730

[github-actions]

Tread carefully! This PR adds 2 linter errors (possibly disabled through directives):

• modules/paapi.js (+2 errors)

[github-actions]

Tread carefully! This PR adds 1 linter error (possibly disabled through directives):

• modules/paapi.js (+1 error)

[patmmccann]

cc: @wsusrasp would love to consider your adapter as an early candidate for parallel support

[dgirardi]

@zapo this "freezes" part of the auction configs into the adapter, meaning that updates would need a code change to be deployed, to enable parallel (faster) IG auctions. I got the values by looking at what your endpoint returns - but I don't know if they're universal (and I don't know if your endpoint respects the ae flag like I do here).

auctionSignals is still picked up from the endpoint through interpretResponse (as would a few other signals that I don't see populated in your case), but everything in here must be provided synchronously.

[zapo]

@dgirardi Looks good, yes they are universal for now. The endpoint does respect ae but only when set at top level (initial proposal) imp.ext.ae, I need to fix it to also look for imp.ext.igs.ae.

[mkendall07]

Is there any consideration to have the PAAPI configs be dynamically configured, possibly from storing into localstorage from a previous auction result. I'm thinking about origins specifically but could be other things we might want to be dynamic. As a SSP the buyer origin is not a hardcoded value as we have multiple buyers depending on context.

[dgirardi]

Is there any consideration to have the PAAPI configs be dynamically configured, possibly from storing into localstorage from a previous auction result.

The interface should be general enough to allow this from an adapter. If it becomes a common pattern we can consider extracting it to a shared library - right now I don't know how that would look like (I expect SSP will still want to get in the first auction, which requires hardcoded buyers).

As a SSP the buyer origin is not a hardcoded value as we have multiple buyers depending on context.

Yes, and IMO this will quickly devolve into every prebid bundle containing every buyer that exists - but alas we decided that's what we want.

[jefftmahoney]

@dgirardi If an adapter chooses not to implement buildPAAPIConfigs(), and instead just has hydrated auction config objects coming back with interpretResponse() (for situations where PAAPI is enabled), do they face bad effects? (Aside from missing out on action from publishers who want parallel auctions)? Or will this be required of every adapter, regardless of whether any of their pubs set the parallel flag to true?

[dgirardi]

@jefftmahoney if a pub sets parallel: true, adapters that do not provide buildPAAPIConfigs will likely be excluded from IG auctions. Technically auction configs are still made available as normal, and a pub could still use them, but (assuming GPT gives us some way to start the paapi auctions early) the default behavior will see them coming too late.

[jefftmahoney]

@jefftmahoney if a pub sets parallel: true, adapters that do not provide buildPAAPIConfigs will likely be excluded from IG auctions. Technically auction configs are still made available as normal, and a pub could still use them, but (assuming GPT gives us some way to start the paapi auctions early) the default behavior will see them coming too late.

That makes sense. And if a publisher does not use the flag but still runs PAAPI auctions, existing setups would still work?

[JulieLorin]

I am not sure I have all the knowledge to fully review this PR but it looks good to me

[mkendall07]

@jefftmahoney if a pub sets parallel: true, adapters that do not provide buildPAAPIConfigs will likely be excluded from IG auctions. Technically auction configs are still made available as normal, and a pub could still use them, but (assuming GPT gives us some way to start the paapi auctions early) the default behavior will see them coming too late.

I'm concerned about this part effectively not being backwards compatible for bidders. Basically it excludes you from the PAAPI auction if you do not provide buildPAAPIConfigs. Is there a way to make it backwards compatible so all PAAPI configs are made available to top level auction?

[patmmccann]

I cannot see a way to make paapi configs that don't have some way of determining interest group buyers available to the parallel paapi auction, bidders will have several choices in how to do this, with hard coded values, publisher configuration, endpoint responses feeling like a natural ordering of priority from low to high. I don't see that as a compatibility issue so much as a new feature for bidders to support, and bidders may need to make certain choices about how to participate

[dgirardi]

Basically it excludes you from the PAAPI auction if you do not provide buildPAAPIConfigs.

Only if the pub enables parallel auctions (parallel: true). If they don't, adapters can use either method with almost* no difference, so I don't think it's a breaking change. But if they do, then yes they'd be excluded - I don't know of any way to avoid this without changes to the API (which have been refused already).

* buildPAAPIConfigs makes configs available from getPAAPIConfig immediately; interpretResponse at end of auction. Our existing guides/implementations only call it after the auction ends, so it should have no impact.