PBS adapter: add tmaxmax

[jefftmahoney]

Type of change

• Feature

Description of change

Update the logic in ortbConverter.js so that a tmaxmax property will now be available for s2s requests. The value of tmaxmax will be either something specified by the publisher (in setConfig() example below) or, failing that, will fall back to the value of requestBidsTimeout.

Sample setup that a publisher would do to invoke this new logic

pbjs.setConfig({
   ortb2: {
      ext: {
         tmaxmax: 888
      }
   }
});

Other information

The work of this PR addresses this issue

[dgirardi]

my reading of the issue:

This is great, but we have a module that would like to know the actual client-side timeout -- the timeout passed to pbjs.requestBids.

The ortbConverter library should check for the existence of ext.tmaxmax and if not there, set it to the timeout value passed to requestBids()

is that this should be a new field, request.ext.tmaxmax, which by default should be the client timeout, optionally overridable with ortb2.ext.tmaxmax

which I think in code translates to

Suggested change

	request.tmax = s2sBidRequest.s2sConfig.ortb2?.ext?.tmaxmax || s2sBidRequest.s2sConfig.timeout;
	request.tmax = s2sBidRequest.s2sConfig.timeout;
	request.ext.tmaxmax = request.ext.tmaxmax ?? proxyBidderRequest.timeout

[jefftmahoney]

Hmmm ... yes, I think I agree with you @dgirardi.

Belated question: do we think that tmaxmax is something that a SSP endpoint (the place a bid request will get POST-ed to) needs to worry about? Or is this just to help the server-side make a smart decision about tmax? I'm assuming since tmaxmax is not part of oRTB the answer is "no", but thought I'd ask.

[dgirardi]

My understanding is that this is of interest to prebid server specifically because it has a separate timeout configuration that doesn't necessarily match the client timeout. Client adapters typically already have tmax set to the client timeout, and if not they can choose to do as they wish, so I don't think it makes sense to generalize it.

[jefftmahoney]

@dgirardi I'm having trouble writing a test to verify that this works.

Where would ortbConverter.js look to find out if a publisher had made this call:

pbjs.setConfig({
   ortb2: {
      ext: {
         tmaxmax: 888
      }
   }
});

Would it be in proxyBidderRequest? That object is undefined right now in the test I'm running, but if that is where a publisher-specified tmaxmax value would go I could mock one up.

[dgirardi]

roughly, ortb2 comes in as s2sBidRequest.ortb2Fragments.global here:

Prebid.js/modules/prebidServerBidAdapter/index.js

Line 454 in e074512

baseAdapter.callBids = function(s2sBidRequest, bidRequests, addBidResponse, done, ajax) {

passed down here:

Prebid.js/modules/prebidServerBidAdapter/ortbConverter.js

Line 262 in e074512

export function buildPBSRequest(s2sBidRequest, bidderRequests, adUnits, requestedBidders, eidPermissions) {

and finally here:

Prebid.js/modules/prebidServerBidAdapter/ortbConverter.js

Line 172 in e074512

mergeDeep(ortbRequest, context.s2sBidRequest.ortb2Fragments?.global);

which is how, in the code at the top of this thread, it ends up filling request.ext.tmaxmax after you run buildRequest.

"roughly" because there's more than one way to configure ortb2 - and the PBS adapter is peculiar in that it also has to deal with bidder-specific configuration separately from global configuration (hence the .global)

in practice for testing that means manipulating ortb2Fragments.global in the first argument to callBids - here's an example:

Prebid.js/test/spec/modules/prebidServerBidAdapter_spec.js

Lines 2614 to 2621 in e074512

	const ortb2Fragments = {
	global: {site: commonSite, user: commonUser, badv, bcat},
	bidder: Object.fromEntries(allowedBidders.map(bidder => [bidder, {site, user, bcat, badv}]))
	};
	// adapter.callBids({ ...REQUEST, s2sConfig: cfg }, BID_REQUESTS, addBidResponse, done, ajax);
	adapter.callBids(addFpdEnrichmentsToS2SRequest({...s2sBidRequest, ortb2Fragments}, bidRequests, cfg), bidRequests, addBidResponse, done, ajax);

[jefftmahoney]

This is great - thank you so much! I'll try some of this out later this afternoon and let you know.

[jefftmahoney]

Addressed with commit b3b3ca4

[dgirardi]

After testing this I realized there's a few more steps to take. proxyBidderRequest.timeout here is undefined as it's filtered out here. However, it turns out that timeout is not the one we want:

Prebid.js/src/adapterManager.js

Line 315 in 8620ae4

timeout: s2sConfig.timeout,

my suggestion is to add requestBidsTimeout here:

Prebid.js/src/adapterManager.js

Line 423 in 8620ae4

let s2sBidRequest = {'ad_units': adUnitsS2SCopy, s2sConfig, ortb2Fragments};

and then pick it up from here (should be available under context.s2sBidRequest)

[jefftmahoney]

Cool. I've made the suggested changes - or what I understand the suggested changes to be - with 4bb1b47. Happy to answer any questions or follow up as needed!

[jefftmahoney]

@dgirardi actually, I just tried running my test where I just do this

// request.ext.tmaxmax = request.ext.tmaxmax || context.s2sBidRequest.requestBidsTimeout; --> commenting out temporarily to see what happens if request.ext.tmaxmax is not available for assignment

request.ext.tmaxmax = context.s2sBidRequest.requestBidsTimeout;  

And my test (line 791 of prebidServerBidAdapter_spec.js) fails because the actual value is undefined. Which I guess means requestBidsTimeout is undefined.

I think this means that I need to do additional test-data setup to mimic requestBidsTimeout being available in a real-world scenario.

I'll dig more into this and let you know if further logic changes are required in ortbConverter.js, adapterManager.js or elsewhere.

[dgirardi]

I think this means that I need to do additional test-data setup to mimic requestBidsTimeout being available in a real-world scenario.

Only if you add a test case that covers the fallback - which I won't object to. Currently it should pass as it only checks that the input tmaxmax has precedence.

[jefftmahoney]

Cool. I can verify that it does pass in its current iteration. I'll try adding a fallback test too in a little bit.

[jefftmahoney]

OK, fallback test added.