From d7e810f6757e3cb39dddbb1403e57226eea2844e Mon Sep 17 00:00:00 2001 From: bretg Date: Fri, 9 Apr 2021 15:43:52 -0400 Subject: [PATCH] pbAdSlot: updating case and location --- dev-docs/adunit-reference.md | 2 +- features/firstPartyData.md | 2 +- features/pbAdSlot.md | 41 ++++++++++--------- .../pbm-api/android/pbm-adunit-android.md | 2 +- prebid-mobile/pbm-api/ios/pbm-adunit-ios.md | 4 +- 5 files changed, 27 insertions(+), 24 deletions(-) diff --git a/dev-docs/adunit-reference.md b/dev-docs/adunit-reference.md index 58c09d22ca..7614d9b78f 100644 --- a/dev-docs/adunit-reference.md +++ b/dev-docs/adunit-reference.md @@ -534,7 +534,7 @@ pbjs.addAdUnits({ ortb2Imp: { ext: { data: { - pbAdSlot: "homepage-top-rect", + pbadslot: "homepage-top-rect", adUnitSpecificContextAttribute: "123" } } diff --git a/features/firstPartyData.md b/features/firstPartyData.md index 7543f8f5d9..bcd682039b 100644 --- a/features/firstPartyData.md +++ b/features/firstPartyData.md @@ -122,7 +122,7 @@ pbjs.addAdUnits({ ortb2Imp: { ext: { data: { - pbAdSlot: "homepage-top-rect", + pbadslot: "homepage-top-rect", adUnitSpecificAttribute: "123" } } diff --git a/features/pbAdSlot.md b/features/pbAdSlot.md index 8b72ebb6a7..a0eaafe115 100644 --- a/features/pbAdSlot.md +++ b/features/pbAdSlot.md @@ -23,29 +23,32 @@ The Prebid Ad Slot was introduced with Prebid.js 3.x. 2. In order to be able to display the right ad in the right hole, the Prebid AdUnit therefore sets the 'code' to the div ID instead of the slotname. 3. The div ID in this case is a random number, not very useful for reporting. 4. Therefore, to get a stable ID that's useful from a business perspective to identify a hole-in-the-page, the publisher -decides to add another identifier... the Prebid Ad Slot, or pbAdSlot. -5. The publisher adds a function to the page that annotates each Prebid AdUnit in the auction with the `pbAdSlot`. -6. Participating bid adapters read the `pbAdSlot` and can target deals to them. -7. Participating analytics adapters read the `pbAdSlot` for more granular reporting. +decides to add another identifier... the Prebid Ad Slot. +5. The publisher adds a function to the page that annotates each Prebid AdUnit in the auction with the `pbadslot`. +6. Participating bid adapters read the `pbadslot` and can target deals to them. +7. Participating analytics adapters read the `pbadslot` for more granular reporting. Example page function: {% highlight js %} -// Use adunit.fpd.context.pbAdSlot if it exists. Otherwise, if the +// Use adunit.ortb2Imp.ext.data.pbadslot if it exists. Otherwise, if the // the adunit.code is a div ID, then look for a data-adslotid attribute, then look a matching slot in GPT // Otherwise, just use the AdUnit.code var setPbAdSlot = function setPbAdSlot(adUnits) { - // set pbAdSlot for all ad units + // set pbadslot for all ad units adUnits.forEach(function (adUnit) { - if (!adUnit.fpd) { - adUnit.fpd = {} + if (!adUnit.ortb2Imp) { + adUnit.ortb2Imp = {} } - if (!adUnit.fpd.context) { - adUnit.fpd.context = {}; + if (!adUnit.ortb2Imp.ext) { + adUnit.ortb2Imp.ext = {}; + } + if (!adUnit.ortb2Imp.ext.data) { + adUnit.ortb2Imp.ext.data = {}; } - // use existing pbAdSlot if it is already set - if (adUnit.fpd.context.pbAdSlot) { + // use existing pbadslot if it is already set + if (adUnit.ortb2Imp.ext.data.pbadslot) { return; } @@ -54,7 +57,7 @@ var setPbAdSlot = function setPbAdSlot(adUnits) { if (adUnitCodeDiv) { // try to retrieve a data element from the div called data-adslotid. if (adUnitCodeDiv.dataset.adslotid) { - adUnit.fpd.context.pbAdSlot = adUnitCodeDiv.dataset.adslotid; + adUnit.ortb2Imp.ext.data.pbadslot = adUnitCodeDiv.dataset.adslotid; return; } // Else if AdUnit.code matched a div and it's a banner mediaType and googletag is present @@ -65,13 +68,13 @@ var setPbAdSlot = function setPbAdSlot(adUnits) { return (gptSlot.getSlotElementId() === adUnitCodeDiv.id); }); if (linkedSlot) { - adUnit.fpd.context.pbAdSlot = linkedSlot.getAdUnitPath(); + adUnit.ortbImp.ext.data.pbadaslot = linkedSlot.getAdUnitPath(); return; } } } // Else, just use the AdUnit.code, assuming that it's an ad unit slot - adUnit.fpd.context.pbAdSlot = adUnit.code; + adUnit.ortb2Imp.ext.data.pbadslot = adUnit.code; }); }; @@ -82,7 +85,7 @@ pbjs.onEvent('beforeRequestBids', setPbAdSlot); ## How It Works The Prebid Ad Slot is just a convention -- it's a form of adunit-specific first party data -stored under `adunit.fpd.context.pbAdSlot`. +stored under `adunit.ortb2Imp.ext.data.pbadslot`. It can be utilized by any code ready to look for it. It's intended to be specified via Prebid.js in one of two ways: @@ -90,17 +93,17 @@ It's intended to be specified via Prebid.js in one of two ways: 1. Either directly on the AdUnit itself 2. Or defined during the run of a function before the auction -The function could determine the pbAdSlot in any way that produces a stable value useful for targeting and reporting. +The function could determine the pbadslot in any way that produces a stable value useful for targeting and reporting. Some scenarios that could be supported: - parse a substring of the ad server's slot name - use a custom div data element ID, else the AdUnit.code -- use the AdUnit.fpd.context.pbAdSlot as a default rather than primary +- use the AdUnit.ortb2Imp.ext.data.pbadslot as a default rather than primary - support a different ad server ## Prebid Server -The OpenRTB location for the Prebid Ad Slot is `imp[].ext.context.data.pbadslot`: +The OpenRTB location for the Prebid Ad Slot is `imp[].ext.data.pbadslot`: - The Prebid SDK will place the value there. - AMP Stored Requests should place the value there if desired. diff --git a/prebid-mobile/pbm-api/android/pbm-adunit-android.md b/prebid-mobile/pbm-api/android/pbm-adunit-android.md index 5bdddecf88..121b7e7761 100755 --- a/prebid-mobile/pbm-api/android/pbm-adunit-android.md +++ b/prebid-mobile/pbm-api/android/pbm-adunit-android.md @@ -37,7 +37,7 @@ The `AdUnit` object is an abstract object that cannot be instantiated. Use the [ PB Ad Slot is an identifier tied to the placement the ad will be delivered in. The use case for PB Ad Slot is to pass to exchange an ID they can use to tie to reporting systems or use for data science driven model building to match with impressions sourced from alternate integrations. A common ID to pass is the ad server slot name. -`adUnit.pbAdSlot = "/1111111/homepage/med-rect-2"` +`adUnit.ortb2Imp.ext.data.pbadslot = "/1111111/homepage/med-rect-2"` --- diff --git a/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md b/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md index 91c656bb60..3c688d4fb5 100755 --- a/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md +++ b/prebid-mobile/pbm-api/ios/pbm-adunit-ios.md @@ -42,7 +42,7 @@ Create a new Banner Ad Unit or Interstitial Ad Unit with a Prebid Server configu PB Ad Slot is an identifier tied to the placement the ad will be delivered in. The use case for PB Ad Slot is to pass to exchange an ID they can use to tie to reporting systems or use for data science driven model building to match with impressions sourced from alternate integrations. A common ID to pass is the ad server slot name. -`adUnit.pbAdSlot = "/1111111/homepage/med-rect-2"` +`adUnit.ortb2Imp.ext.data.pbadslot = "/1111111/homepage/med-rect-2"` --- @@ -259,7 +259,7 @@ func clearContextData() func loadDFPBanner(bannerUnit : AdUnit){ let bannerUnit = BannerAdUnit(configId: "6ace8c7d-88c0-4623-8117-75bc3f0a2e45", size: CGSize(width: 300, height: 250)) - bannerUnit.pbAdSlot = "/1111111/homepage/med-rect-2"` + bannerUnit.ortb2Imp.ext.data.pbadslot = "/1111111/homepage/med-rect-2"` let dfpBanner = DFPBannerView(adSize: kGADAdSizeMediumRectangle) dfpBanner.adUnitID = "/19968336/PriceCheck_300x250"