Where does the GPID come from ?

[patmmccann]

Type of issue

The TradeDesk is encouraging publishers to provide "Global Placement ID" (GPID) data that's sometimes more granular than the GAM AdSlot. For instance, if a publisher's GAM AdSlots are all the same on a given page, TTD wants them to append that value with the div-id to make the values unique.

This desire for uniqueness is the reason that the Prebid AdSlot was created. The GPT Pre-Auction module supports publishers who want to pass the GAM AdSlot, and allows them to customize the PB AdSlot by defining a function.

So a given page might have these values:

• ortb2Imp.ext.data.adserver.name:"gam"
• ortb2Imp.ext.data.adserver.adslot:"/1111/homepage"
• ortb2Imp.ext.data.pbadslot:"/1111/homepage/div-1"

The issue at hand is which of these values should a bid adapter read? Adapters are inconsistent:

• Index reads 'ortb2Imp.ext.data.adserver.adslot'
• Appnexus reads 'ortb2Imp.ext.data.pbadslot'
• Others (grid/magnite/sovrn) look at both, preferring GAM AdSlot over PB AdSlot.

We need to discuss A) standardizing, B) giving the publisher some control, C) whether this issue may affect modules like Price Floors, Viewability, and other RTD modules.

There is also a docs repo issue prebid/prebid.github.io#2928 tracking a proposal on GPID docs

[bwoolcott]

Good summary, thanks @patmmccann The reason that these disparate ways exist in bid modules today is that the rollout of GPID came in phases (two so far) and in phase one all of the publishers in question had descriptive GAM AdSlots (unique per slots on page,) so there was no request to have div-id be part of the GPID.

So this inconsistency came from the fact that between 4/1/21 (the start of phase 1) and 8/1/21 (the start of phase 2,) that implementing in the way Index did (Index reads ortb2Imp.ext.data.adserver.adslot) was perfectly fine as only GAM ad slot was being requested as GPID (no mention of div-id.) So Index and other SSPs did the engineering work to parse from ortb2Imp.ext.data.adserver.adslot as the GPT pre auction module made this a very reliable place for GAM AdSlot to exist, and was a good place to get GPID from. So the requirements with div-id being added now are different and create some extra work.

Now that appending div-id is being requested, and as you called out ortb2Imp.ext.data.pbadslot allows for creation of a custom function, that's likely the more reliable place to parse GPID from. In cases where a pub is using the GPT Pre Auction module and doesn't need to add div-id then pbadslot will just be equal to adserver.adslot so it works in that case. And in cases where a pub does need to append div-id they can do so with a custom function and pbadslot is still the right field to parse.

So if we're talking about standardizing as a recommendation in docs etc. then suggesting using ortb2Imp.ext.data.pbadslot as the GPID is probably the safest bet? Separately; maybe we can update the GPT pre auction module to just make pbadslot always GAM+Div-id (like w/o a custom function, but still allowing it to be overwritten w/ a custom function?)

[simontrasler]

Whatever the logic, I recommend creating a field called gpid for the adapters to consume, so no interpretation is required in the adapters themselves.

[allanjun]

Some publishers may generate a divid dynamically, so the divid data would be acting like a transactionid. I believe GPID aims to have a unique, global and stable placement identifier?

If we create a new field called gpid, I think it would make sense to allow publishers to configure whether this will use ortb2Imp.ext.data.adserver.adslot (default?) or ortb2Imp.ext.data.pbadslot

eg: for a publisher having two 300x250 placements, one ATF and other BTF:

Case	adserver.adslot	pbadslot	gpid choice
Case 1: One GAM adslot = 1 placement , stable div ids	/1234/300x250-ATF, /1234/300x250-BTF	/1234/300x250-ATF/div-1, /1234/300x250-BTF/div2	adserver.adslot and pbadslot have same cardinality
Case 2: One GAM adslot = 1 ad format, stable div ids	/1234/300x250, /1234/300x250	/1234/300x250/div-1, /1234/300x250/div2	pbadslot makes more sense here
Case 3: One GAM adslot = 1 placement , dynamic div ids	/1234/300x250-ATF, /1234/300x250-BTF	/1234/300x250-ATF/div-73xnkj3, /1234/300x250-BTF/div-njj81jnkd	adserver.adslot makes more sense, pbadslot is unique per ad request
Case 4: One GAM adslot = 1 ad format, dynamic div ids	/1234/300x250, /1234/300x250	/1234/300x250/div-73xnkj3, /1234/300x250/div-njj81jnkd	I'd rather rely on adserver.adslot but we lose ATF/BTF information

[bretg]

Agreed that random div IDs are sometimes used @allanjun , but for the record PB AdSlot is not defined using div. Rather, PB AdSlot is defined by a function that can be whatever the publisher defines. The example in https://docs.prebid.org/features/pbAdSlot.html suggests publishers with random IDs could add a "data-adslotid" element. e.g. <div id="49849-abc-6573" data-adslotid="some stable identifier">

[nllerandi3lift]

If we create a new field called gpid, I think it would make sense to allow publishers to configure whether this will use ortb2Imp.ext.data.adserver.adslot (default?) or ortb2Imp.ext.data.pbadslot

This would make sense because pubs have already put in the work to set custom values/GPIDs at ortb2Imp.ext.data.pbadslot. We should just keep in mind that since early August, publishers requiring a more custom GPID due to non-unique adslots have been specifically working to use pbadslot for the GPID because that direction came from Trade Desk. So any work they've already done to customize a GPID at ortb2Imp.ext.data.pbadslot either via the GPT Pre-Auction Module's customPbAdSlot function or just manually shouldn't be undermined. IE., if a new gpid field is created it should not affect the work already performed by pubs to set the value at ortb2Imp.ext.data.pbadslot.

[simontrasler]

Makes sense. The important point is to separate pbadslot the value (which may get repurposed as the GPID) from pbadslot the field.

[bretg]

Here's a straw proposal.

We make an update the GPT Pre-Auction module to possibly write AdUnit.ortb2Imp.ext.gpid:

1. if AdUnit.ortb2Imp.ext.gpid already exists, don't do anything. Assume the publisher or another module has provided the value.
2. Otherwise, if a customPbAdSlot function was defined by the publisher and the result is not empty, then copy the value to AdUnit.ortb2Imp.ext.gpid
3. Otherwise, if a value was found for GAM AdSlot, copy that to AdUnit.ortb2Imp.ext.gpid

Bid adapters would then be instructed to prefer AdUnit.ortb2Imp.ext.gpid.

[nllerandi3lift]

Looks good to me. pbadslot would still exist (whether it received the default GAM AdSlot or the result of customPbAdslot) and gpid would essentially be a duplicate.

[simontrasler]

I may have erred in assuming Prebid is in a position to decide the GPID. Is it guaranteed that when Prebid is present, it is the only demand source? AFAIK, that is a pre-requisite to Prebid doing anything other than passing a value along.

Update: it is not guaranteed. Therefore anything in Prebid should be considered temporary, and IMO avoided.

[bretg]

Is it guaranteed that when Prebid is present, it is the only demand source?

The same piece of inventory could wind up calling a DSP from both Prebid and OB. But it's doubtful that OB will ever support a more granular "AdSlot" -- they'll probably just tell the pub to refactor their page.

So the question becomes - what breaks if GPID is div-annotated on one path (Prebid) and vanilla on another (OB)?

[simontrasler]

Clear, thanks @bretg.

what breaks if GPID is div-annotated on one path (Prebid) and vanilla on another (OB)?

Unfortunately AFAIK, the GPID concept. :-p So I don't understand what TTD is asking for.

[JudSpencer]

The design is that there is a consistent identifier from all sources. Getting OB to pass along the identifier is going to be required to make the effort successful universally.

[bretg]

Thanks, @JudSpencer, but it opens the question -- what would you like pubs and Prebid to do while the GAM side of this works itself out?

Because it will take some time, I propose Prebid and the SSPs implement the proposal above:

1. the GPT Pre-Auction module will explicitly create imp.ext.gpid using PB AdSlot over GAM Ad Slot
2. bid adapters can start reading this value if they don't already
3. publishers add the custom PB AdSlot function.

It's the timing of #3 that's in question. This could happen immediately or wait until GAM-OB catches up. The answer hinges on the tradeoff in value for the more detailed info vs the downside of discrepancy between the Prebid and OB paths.

[bretg]

After a number of discussions, it's now uncertain whether Prebid should support imp.ext.gpid.

It appears to us that TradeDesk has conflicting requirements here:

1. consistency between Prebid, TAM, and OB
2. more granular ad units

Getting better granularity is pretty easy from a Prebid perspective, but consistency is beyond our control. If TradeDesk prioritizes consistency, then Prebid would recommend that adapters focus on GAM adslot and use PB adslot only for special tasks. We would not add imp.ext.gpid support in the system.

[JudSpencer]

Sorry that I didn't see your previous message on the topic.

We don't have conflicting asks here. The issue is that there hasn't been commitment from Google to build support for what we're asking for yet. That doesn't mean that it's not the right thing for PreBid to do.

The goal of the effort is to understand across exchanges, apples-to-apples what is transacting where and how traffic is different in different places. That means that we have to have support in several different places. We have prioritized consistency, but consistency requires cooperation from other parties that we don't have control over. Getting growing support from the prebid community of publishers will help to prioritize the ask elsewhere.

[bretg]

@JudSpencer - it sounds like you're requesting for Prebid to move forward with the 'granular-GPID' proposal even if the side effect is inconsistency for an extended period. Some of us are skeptical about OB making this change anytime soon, so you may be stuck with apples-and-oranges.

[JudSpencer]

I understand the skepticism. Sometimes it takes a lot of momentum for Google to interrupt their product plans and fit in industry initiatives. e.g., it took over a year for support of Sellers.json and closer to two years to get their current, minimum level of SupplyChain data populated. The industry, IMO, needs to move forward on transparency initiatives though.

[bretg]

@JudSpencer - we would like for you to say "yes - TradeDesk wants Prebid to build the GPID feature and publishers should use it even if the GAM changes might be a long time coming." Please confirm. Thanks.

[JudSpencer]

Yes - TradeDesk wants Prebid to build the GPID feature and publishers should use it even if the GAM changes might be a long time coming.

[bretg]

@JudSpencer - there's been further conversation about the syntax here. We propose that instead of combing GAM ad slot and div with a slash, that we recommend the delimiter be something else: either carat (^) or semi-colon (;)

For the record, GAM docs say "Only letters, numbers, underscores, hyphens, periods, asterisks, exclamations, left angle brackets, colons, forward slashes and parentheses are allowed." in ad unit codes. Ampersand, tilda, and pound-sign are URL chars. So that leaves us with at, comma, semi-colon, dollar-sign, percent, and carat. Looking for community input on the delimiter.

Here's the revised proposal.

We make an update the GPT Pre-Auction module to possibly write AdUnit.ortb2Imp.ext.gpid:

• if AdUnit.ortb2Imp.ext.gpid already exists, don't do anything. Assume the publisher or another module has provided the value.
• Otherwise, if a customPbAdSlot function was defined by the publisher and the result is not empty, then copy the value to AdUnit.ortb2Imp.ext.gpid
  • Prebid recommends that in most cases the GAM adslot should be combined with the div-id with a semi-colon delimiter.
  • If the publisher uses a random div-id, however, some other value should be chosen.
• Otherwise, if a value was found for GAM AdSlot, copy that to AdUnit.ortb2Imp.ext.gpid
• Bid adapters are instructed to prefer AdUnit.ortb2Imp.ext.gpid.

[JudSpencer]

Reading your comment, I'm not sure what "Only letters, numbers, underscores, hyphens, periods, asterisks, exclamations, left angle brackets, colons, forward slashes and parentheses are allowed." has to do with the delimiter between the ad unit code and the DivId? Is it not OK to just check to see if the last character of the ad unit code is a forward slash and if it isn't to insert a forward slash between the ad unit code and the DivId?

[JudSpencer]

The rest of the logic looks right.

[bretg]

Is it not OK to just check to see if the last character of the ad unit code is a forward slash and if it isn't to insert a forward slash between the ad unit code and the DivId?

No, we don't think using a forward slash is a good idea because not all GPIDs have div-id appended. Some publishers have adunits that are unique already, so don't need to tack on div-id.

Without a special delimiter, downstream entities will not be able to tell whether the string has a div-id or not. e.g. consider these GPIDs:

1. /1111/homepage/div-1 - div ID was appended
2. /2222/homepage/left-nav - no div ID was appended, adslot is unique

How would you know whether the last field was appended or not? You shouldn't assume that all div IDs contain the string "div".

So the suggestion is that a different delimiter would allow downstream entities better insight:

1. /1111/homepage;div-1 - presence of a semi-colon indicates that div ID was appended
2. /2222/homepage/left-nav - no div ID was appended, adslot is unique

[JudSpencer]

Is the concern here that downstream systems are going to care whether a DivID is appended or not? I'm not sure that there is going to be a way for any downstream consumer to know whether a valid GPID is being generated without some sort of 2-way communication between the pub and exchange selling the inventory. I don't feel strongly about this though other than I don't want to see any consumer assume that all GPIDs will be of a certain structure/format.

[bretg]

We discussed in the Prebid Taxonomy committee today. Resolved:

1. We agreed that forward-slash should not be the delimiter. We like the downstream ability to know that the GPID was constructed, whether machine-read or just for human debuggers.
2. It was proposed that pound-sign (#) would be good because it's analogous to an anchor in a URL. Pound-sign was originally ruled out because it's a special character in a URL, but that doesn't make sense because forward-slash is also a special character -- the GPID will have to be URL-encoded anyhow.
3. We'll need good documentation on how publishers and adapters should coordinate on GPID.

So here's the updated example:

/1111/homepage#div-1 - presence of a pound-sign indicates that div ID was appended
/2222/homepage/left-nav - no div ID was appended, adslot is unique

[JudSpencer]

Thanks.

That's fine as a default. There shouldn't be any requirement that a pub follow these guidelines when building out their GPID taxonomy. They really can be as simple as a single word.

[patmmccann]

/1111/homepage#div-1 - presence of a semi-colon indicates that div ID was appended
@bretg is this a typo, did you mean pound sign or semi colon

[bretg]

Copy-paste-O. Fixed. Thanks.

[bretg]

Ok, we're going to move forward with making the changes to the GPT Pre-Auction module as proposed on Sept 3rd:

1. if AdUnit.ortb2Imp.ext.gpid already exists, don't do anything. Assume the publisher or another module has provided the value.
2. Otherwise, if a customPbAdSlot function was defined by the publisher and the result is not empty, then copy the value to AdUnit.ortb2Imp.ext.gpid
3. Otherwise, if a value was found for GAM AdSlot, copy that to AdUnit.ortb2Imp.ext.gpid

There will also be a documentation update needed to describe GPID, which I propose placing in the existing PBAdSlot doc, which will be renamed PBAdSlot and GPID.

[bretg]

Documentation for this feature is needed. Have a draft that I'll post soon...

[bretg]

In working through the documentation, @robertrmartinez and I realized that the current design isn't quite going to work. The customPbAdSlot function sends only adUnitCode rather than the whole AdUnit object. This means the function can't introspect the AdUnit object to get ortb2Imp.

So we propose the following:

1. Add a new parameter: customPreAuction. This is an alternate callback function to use instead of customPbAdSlot -- if both are specified, prefer customPreAuction. The only difference is that customPreAuction is sent the whole adunit rather than just the code.
2. Add a useDefaultPreAuction flag. If this is true, run a default block of code like the example function below. If false, and neither function is specified, fall back to the current default behavior.

pbjs.setConfig({
    gptPreAuction: {
	enabled: true, // enabled by default
	customPreAuction: function(adUnit, adServerAdSlot) {
                 if (typeof adUnit !== 'object') {
                    return;
                 }

		// use pbadslot if supplied
		if (adUnit.ort2bImp && adUnit.ort2bImp.ext && adUnit.ort2bImp.ext.data && adUnit.ort2bImp.ext.data.pbadslot) {
		    return adUnit.ort2bImp.ext.data.pbadslot;
		}

		// confirm that GPT is set up
		if (!(googletag && googletag.apiReady)) {
		    return;
		}
		// find all GPT slots with this name
		var gptSlots = googletag.pubads().getSlots().filter(function(gpt) {
		    return gpt.getAdUnitPath() == adServerAdSlot;
		});
		if (gptSlots.length==0) {
		    return;  // should never happen
		}
		if (gptSlots.length==1) {
		    return adServerAdSlot;
		}
		// else the adunit code must be div id. append it.
		return adServerAdSlot+"#"+adUnitCode;
	}
  });
};

To summarize the proposed behavior:

1. If customPreAuction specified, run that. Place its return value in pbAdSlot and GPID.
2. else if customPbAdSlot specified, run that. Place its return value in pbAdSlot and GPID.
3. else if useDefaultPreAuction is true, run the new default GPID logic and place the return value in both pbAdSlot and GPID
4. else run the current default logic and place the return value in both pbAdSlot and GPID

This positions pbAdSlot and GPID as synonyms. Which means in a future, we're going to want to deprecate pbAdSlot entirely and simplify this logic down to:

1. If customPreAuction specified, run that. Place its return value in GPID
2. else run the new default GPID logic and place the return value in GPID

[bretg]

The first round of GPT Pre-Auction module changes were released in 6.1. I have a first cut of docs that conform to what's released:

https://dev.prebid.org/features/pbadslot
https://dev.prebid.org/dev-docs/modules/gpt-pre-auction.html

I propose that we release these docs, then when the new customPreAuction function is available, we can simplify the docs.

[bretg]

I went ahead and merged the draft docs. The PB AdSlot docs were woefully out of date and people need the instructions for the proper GPID custom function. Am going to revisit them again once the customPreAuction function is available. In the meantime, community input is welcome.

[bretg]

Closing this issue since the PR is open and will be released with PBJS 6.5