Generic bid adapter for PBS using stored requests, including adapter for Relevant Digital

[samuel-palmer-relevant-digital]

Type of change

• Feature
• New bidder adapter

Description of change

The purpose of this change is to support "SSPs" that are in fact Prebid Server instances configured using stored requests. The use-case is that we have network customers (and ourselves) that would like to let publishers add their demand via a prebid-adapter. The actual bidders are then configured server-side using stored requests in Prebid Server.

Instead of creating a normal bid adapter - this solution adds one s2sConfig object per bidder, as there might be multiple bidders for the same adapter using aliasing. By adding hook-functions in prebidServerBidAdapter the adapter-code will modify the BidRequest + BidReponse to/from Prebid Server to add a stored-request-id from param.adUnitCode and adjust the response so that it will appear as the result from a single bidder, instead of the actual different bidders used by PBS. It will also use a hook to delay and modify the /cookie_sync call to PBS in order to include the bidders actually used once getting the BidResponse from PBS. The implementation of the cookie-sync hook is using a promise along with a sync-hook, which might seem a bit convoluted. But we found very strange/buggy behavior when using async hooks. (I can provide a simple test-case of that if needed).

The actual code is added in modules/prebidServerBidAdapter/storedRequestBidAdapterBase.js (feel free to suggest an alternative location for this file).

There are then 2 minimal adapters added using that implementation:

• storedRequestBidAdapter.js - Default adapter that can be used by anyone by using bidder: 'pbsGenericBidder'.
• relevantDigitalBidAdapter.js - Adapter with minor customisations for users of our Relevant Yield platform.

{
 bidder: 'pbsGenericBidder',
 params: {
    adUnitCode: '123456',
    pbsHost: 'prebid-server.example.com',
    accountId: 'myAccount-123',
  }
}

The pbsHost and (optional) accountId parameters can also, preferably, be set via pbjs.setConfig().

Motivation

This use-case can "sort of" already be achieved by setting params.ortb2Imp.ext.prebid.storedrequest.id in the bids, make sure that bidder is one that in fact will participate in the auction on the ad unit - and then manually add a suitable s2sConfig with allowUnknownBidderCodes: true. However, this might appear cumbersome for site-owners and cookie-syncing with the actual bidders will not be done.

The other option would be to create an adapter using the ORTB Conversion library. But in this case we'll miss out on a lot of things (user-ids, bid-floors, cookie-syncing, etc) handled by the prebidServerBidAdapter. We would then need to copy-paste functionality and struggle to stay up to date with the S2S-adapter, resulting in further unnecessary pull requests.

Therefore we instead suggest this solution. It might for sure be possible to implement this differently, but we've tried to make a solution that changes as little as possible in the existing code.

Other information

There is also a fix in prebidServerBidAdapter.js where the wrong variable-name (option vs options) was used which prevented normalization of of endpoint and cookie_sync URLs when s2sConfig is turned into an array. This was necessary to include in this pull requests, as otherwise the normal Prebid Server integration, if any, would risk breaking.

PR for the documentation repository will arrive shortly.

[dgirardi]

Eh, unfortunately I see these when it's already too late, but I want to note -

The other option would be to create an adapter using the ORTB Conversion library. But in this case we'll miss out on a lot of things (user-ids, bid-floors, cookie-syncing, etc) handled by the prebidServerBidAdapter. We would then need to copy-paste functionality and struggle to stay up to date with the S2S-adapter, resulting in further unnecessary pull requests.

this is not true; the library is built precisely to give you a replica of the PBS protocol in a couple of lines. Everything that the PBS adapter does with requests and responses is in the library, including userid and bid floors and the lot. User syncs are the exception (because they are not part of the request/response cycle), but that would not be hard to extract.

[dgirardi]

This may also overlap with #9470 - which is also attempting to allow multiple stored impressions from multiple different PBS instances. (although I have not looked closely as how the "generic" adapter here differs from "true" PBS). some docs are here.

[samuel-palmer-relevant-digital]

Eh, unfortunately I see these when it's already too late, but I want to note -

The other option would be to create an adapter using the ORTB Conversion library. But in this case we'll miss out on a lot of things (user-ids, bid-floors, cookie-syncing, etc) handled by the prebidServerBidAdapter. We would then need to copy-paste functionality and struggle to stay up to date with the S2S-adapter, resulting in further unnecessary pull requests.

this is not true; the library is built precisely to give you a replica of the PBS protocol in a couple of lines. Everything that the PBS adapter does with requests and responses is in the library, including userid and bid floors and the lot. User syncs are the exception (because they are not part of the request/response cycle), but that would not be hard to extract.

Aha, thanks for the input. Do you mean modules/prebidServerBidAdapter/ortbConverter.js or just the library in libraries/ortbConverter/converter.js'? It was my impression that the first one was needed to add a bunch of fields like bidfloor, schain, eids etc, so that if we would just use the converter library itself it would be pretty much copy-paste needed to "match" the prebidServerBidAdapter-code in order to be able to construct the same request.

[dgirardi]

the code that is specific to the PBS adapter deals with the "merging" and "unmerging" of multiple bid requests (or responses), which is the peculiarity of PBS relative to all the other adapters. I think this is not useful for your use case (but I may be wrong - I haven't looked too hard yet).

For example, normally an impression has one associated bidRequest and therefore one bidRequest.getFloor, which the ORTB conversion knows how to put in imp.bidfloor; but in the case of PBS, we can have any number of requests (and floors) for a single imp.bidfloor, so there's extra logic to aggregate them. Most of the PBS-specific code deals with items like this.

There's also other "sensitive" PBS-only code that has access to more information than a normal adapter does, like bidder-specific configuration for all bidders; this may be a problem for you here - if it's not PBS, it probably should not have access to that info, which may be a reason to avoid this approach (@bretg / @patmmccann ?)

[samuel-palmer-relevant-digital]

Thanks for the info. Will do some testing and if the conversion library can handle everything except of cookie-syncing I'll close this PR and we'll be back with another PR for a more "normal" adapter.

[samuel-palmer-relevant-digital]

Closing this one, will be implemented as a normal adapter instead.