From c493f2dde6c2ffe7279d6ccb6160542fa611b775 Mon Sep 17 00:00:00 2001 From: Harshad Mane Date: Tue, 26 Jan 2021 08:51:17 -0800 Subject: [PATCH 1/7] API fix --- dev-docs/modules/instreamTracking.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/instreamTracking.md b/dev-docs/modules/instreamTracking.md index ebace0a08d..07ef0f29fd 100644 --- a/dev-docs/modules/instreamTracking.md +++ b/dev-docs/modules/instreamTracking.md @@ -20,7 +20,7 @@ sidebarType : 1 Instream tracking module allows Analytics Adapters and Bid Adapters to track `BID_WON` events for Instream video bids. {: .alert.alert-warning :} -This module uses `window.getEntriesByType('resource')` to check the presence of Video Cache URL. +This module uses `window.performance.getEntriesByType('resource')` to check the presence of Video Cache URL. ## Configuration From 1c10f70dd3b5dd5f71466b474284973e7e88334c Mon Sep 17 00:00:00 2001 From: Harshad Mane Date: Tue, 26 Jan 2021 09:13:29 -0800 Subject: [PATCH 2/7] bidViewability module documentation --- dev-docs/modules/bidViewable.md | 58 +++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 dev-docs/modules/bidViewable.md diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md new file mode 100644 index 0000000000..2730c4d71e --- /dev/null +++ b/dev-docs/modules/bidViewable.md @@ -0,0 +1,58 @@ +--- +layout: page_v2 +page_type: module +title: Module - Bid Viewable Event +description: Triggers BID_VIEWABLE event when a rendered PBJS-Bid is viewable according to [Active View criteria](https://support.google.com/admanager/answer/4524488) +module_code : bidViewable +display_name : Bid Viewable Event +enable_download : true +sidebarType : 1 +--- + +# Bid Viewable Event +{:.no_toc} + +* TOC +{:toc} + +## Overview +- This module, when included, will trigger a BID_VIEWABLE event which can be consumed by Bidders and Analytics adapters +- GPT API is used to find when a bid is viewable, https://developers.google.com/publisher-tag/reference#googletag.events.impressionviewableevent . This event is fired when an impression becomes viewable, according to the Active View criteria. +Refer: https://support.google.com/admanager/answer/4524488 +- The module does not work with adserver other than GAM with GPT integration +- Logic used to find a matching pbjs-bid for a GPT slot is ` (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` this logic can be changed by using param ` customMatchFunction ` +- When a rendered PBJS bid is viewable the module will trigger BID_VIEWABLE event, which can be consumed by bidders and analytics adapters +- For the viewable bid if ` bid.vurls [type array] ` param is and module config ` firePixels: true ` is set then the URLs mentioned in bid.vurls will be executed. Please note that GDPR and USP related parameters will be added to the given URLs, here we have assumed that URLs will always have `?` symbol included. +{: .alert.alert-warning :} +- The module works with Banner, Outsteam and Native creatives +- Doesn't seems to work with Instream Video, https://docs.prebid.org/dev-docs/examples/instream-banner-mix.html as GPT's impressionViewable event is not triggered for instream-video-creative + +## Configuration + +{: .table .table-bordered .table-striped } +| Field | Scope | Type | Description | +|----------+---------+--------+---------------------------------------------------------------------------------------| +| `bidViewability` | Optional | Object | Configuration object for instream tracking | +| `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. We have assumed that URLs will always have `?` symbol included. Default: `false` | +| `bidViewability.customMatchFunction` | Optional | function(bid, slot) | when passed this function will be used to `find` the matching winning bid for the GPT slot. Default value is ` (bid, slot) => (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` | +As both params are optional, you do not need to set config if you do not want to set value for any param + +## Example of setting module config +{% highlight js %} + pbjs.setConfig({ + bidViewability: { + firePixels: true, + customMatchFunction: function(bid, slot){ + console.log('using custom match function....'); + return bid.adUnitCode === slot.getAdUnitPath(); + } + } + }); +{% endhighlight %} + +## Example of consuming BID_VIEWABLE event +{% highlight js %} + pbjs.onEvent('bidViewable', function(bid){ + console.log('got bid details in bidViewable event', bid); + }); +{% endhighlight %} \ No newline at end of file From 1fae6a8cb6d4c96fb4c3d0d415713cae2dffa4de Mon Sep 17 00:00:00 2001 From: bretg Date: Thu, 28 Jan 2021 14:48:59 -0500 Subject: [PATCH 3/7] wordsmithing --- dev-docs/modules/bidViewable.md | 28 +++++++++++++++++----------- 1 file changed, 17 insertions(+), 11 deletions(-) diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index 2730c4d71e..3c3648adbe 100644 --- a/dev-docs/modules/bidViewable.md +++ b/dev-docs/modules/bidViewable.md @@ -16,16 +16,21 @@ sidebarType : 1 {:toc} ## Overview -- This module, when included, will trigger a BID_VIEWABLE event which can be consumed by Bidders and Analytics adapters -- GPT API is used to find when a bid is viewable, https://developers.google.com/publisher-tag/reference#googletag.events.impressionviewableevent . This event is fired when an impression becomes viewable, according to the Active View criteria. -Refer: https://support.google.com/admanager/answer/4524488 -- The module does not work with adserver other than GAM with GPT integration -- Logic used to find a matching pbjs-bid for a GPT slot is ` (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` this logic can be changed by using param ` customMatchFunction ` -- When a rendered PBJS bid is viewable the module will trigger BID_VIEWABLE event, which can be consumed by bidders and analytics adapters -- For the viewable bid if ` bid.vurls [type array] ` param is and module config ` firePixels: true ` is set then the URLs mentioned in bid.vurls will be executed. Please note that GDPR and USP related parameters will be added to the given URLs, here we have assumed that URLs will always have `?` symbol included. -{: .alert.alert-warning :} + +This optional module will trigger a BID_VIEWABLE event which can be consumed by Bidders and Analytics adapters. + +Notes: +- The module does not work with adservers other than GAM and only with GPT integration. +- The GPT API is used to find when a bid is viewable, See https://developers.google.com/publisher-tag/reference#googletag.events.impressionviewableevent . +- This event is fired when an impression becomes viewable, according to Active View criteria. See: https://support.google.com/admanager/answer/4524488 +- Logic used to find a matching Prebid.js bid for a GPT slot is ` (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` this logic can be changed by using param ` customMatchFunction ` +- When a rendered PBJS bid is viewable the module will trigger BID_VIEWABLE event, which can be consumed by the winning bidder and analytics adapters - The module works with Banner, Outsteam and Native creatives -- Doesn't seems to work with Instream Video, https://docs.prebid.org/dev-docs/examples/instream-banner-mix.html as GPT's impressionViewable event is not triggered for instream-video-creative + +Instead of listening for events, bidders may supply a ` bid.vurls ` array and this module may fire those pixels when the viewability signal is received. Publishers can control this with module config ` firePixels: true `. Please note that GDPR and USP related parameters will be added to the given URLs, here we have assumed that URLs will always have `?` symbol included. + +{: .alert.alert-warning :} +This feature doesn't seem to work with [Instream Video](/dev-docs/examples/instream-banner-mix.html), as GPT's impressionViewable event is not triggered for instream-video-creative ## Configuration @@ -35,7 +40,8 @@ Refer: https://support.google.com/admanager/answer/4524488 | `bidViewability` | Optional | Object | Configuration object for instream tracking | | `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. We have assumed that URLs will always have `?` symbol included. Default: `false` | | `bidViewability.customMatchFunction` | Optional | function(bid, slot) | when passed this function will be used to `find` the matching winning bid for the GPT slot. Default value is ` (bid, slot) => (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` | -As both params are optional, you do not need to set config if you do not want to set value for any param + +As both params are optional, publishers do not need to set any config at all... the existence of this module in the Prebid.js package enables the functionality. ## Example of setting module config {% highlight js %} @@ -55,4 +61,4 @@ As both params are optional, you do not need to set config if you do not want to pbjs.onEvent('bidViewable', function(bid){ console.log('got bid details in bidViewable event', bid); }); -{% endhighlight %} \ No newline at end of file +{% endhighlight %} From b596f5ea8fb17ea3acafb4b7f92388316554e435 Mon Sep 17 00:00:00 2001 From: bretg Date: Thu, 28 Jan 2021 14:50:09 -0500 Subject: [PATCH 4/7] adding link --- dev-docs/modules/bidViewable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index 3c3648adbe..c8783a27d2 100644 --- a/dev-docs/modules/bidViewable.md +++ b/dev-docs/modules/bidViewable.md @@ -22,7 +22,7 @@ This optional module will trigger a BID_VIEWABLE event which can be consumed by Notes: - The module does not work with adservers other than GAM and only with GPT integration. - The GPT API is used to find when a bid is viewable, See https://developers.google.com/publisher-tag/reference#googletag.events.impressionviewableevent . -- This event is fired when an impression becomes viewable, according to Active View criteria. See: https://support.google.com/admanager/answer/4524488 +- This event is fired when an impression becomes viewable, according to [Active View criteria](https://support.google.com/admanager/answer/4524488). - Logic used to find a matching Prebid.js bid for a GPT slot is ` (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` this logic can be changed by using param ` customMatchFunction ` - When a rendered PBJS bid is viewable the module will trigger BID_VIEWABLE event, which can be consumed by the winning bidder and analytics adapters - The module works with Banner, Outsteam and Native creatives From f849111fd4a97564ebac358b7d4803e275499002 Mon Sep 17 00:00:00 2001 From: Harshad Mane Date: Thu, 28 Jan 2021 16:53:32 -0800 Subject: [PATCH 5/7] update for onBidViewable --- dev-docs/modules/bidViewable.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index c8783a27d2..652a956e3f 100644 --- a/dev-docs/modules/bidViewable.md +++ b/dev-docs/modules/bidViewable.md @@ -17,7 +17,8 @@ sidebarType : 1 ## Overview -This optional module will trigger a BID_VIEWABLE event which can be consumed by Bidders and Analytics adapters. +This optional module will trigger a BID_VIEWABLE event which can be consumed by Analytics adapters, bidders will need to implement `onBidViewable` method to capture this event + Notes: - The module does not work with adservers other than GAM and only with GPT integration. From a2a03574380cc0604422e42fecbcd85bae5180ef Mon Sep 17 00:00:00 2001 From: Harshad Mane Date: Wed, 3 Feb 2021 13:42:33 -0800 Subject: [PATCH 6/7] now we add ? in URL if not present --- dev-docs/modules/bidViewable.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index 652a956e3f..995a200397 100644 --- a/dev-docs/modules/bidViewable.md +++ b/dev-docs/modules/bidViewable.md @@ -28,7 +28,7 @@ Notes: - When a rendered PBJS bid is viewable the module will trigger BID_VIEWABLE event, which can be consumed by the winning bidder and analytics adapters - The module works with Banner, Outsteam and Native creatives -Instead of listening for events, bidders may supply a ` bid.vurls ` array and this module may fire those pixels when the viewability signal is received. Publishers can control this with module config ` firePixels: true `. Please note that GDPR and USP related parameters will be added to the given URLs, here we have assumed that URLs will always have `?` symbol included. +Instead of listening for events, bidders may supply a ` bid.vurls ` array and this module may fire those pixels when the viewability signal is received. Publishers can control this with module config ` firePixels: true `. Please note that GDPR and USP related parameters will be added to the given URLs. {: .alert.alert-warning :} This feature doesn't seem to work with [Instream Video](/dev-docs/examples/instream-banner-mix.html), as GPT's impressionViewable event is not triggered for instream-video-creative From 63995a3ac687da1deb29bedec39b47273fbed5bd Mon Sep 17 00:00:00 2001 From: Harshad Mane Date: Wed, 3 Feb 2021 15:16:05 -0800 Subject: [PATCH 7/7] change in params, added enabled param --- dev-docs/modules/bidViewable.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/dev-docs/modules/bidViewable.md b/dev-docs/modules/bidViewable.md index 995a200397..f31a04e550 100644 --- a/dev-docs/modules/bidViewable.md +++ b/dev-docs/modules/bidViewable.md @@ -38,16 +38,16 @@ This feature doesn't seem to work with [Instream Video](/dev-docs/examples/instr {: .table .table-bordered .table-striped } | Field | Scope | Type | Description | |----------+---------+--------+---------------------------------------------------------------------------------------| -| `bidViewability` | Optional | Object | Configuration object for instream tracking | -| `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. We have assumed that URLs will always have `?` symbol included. Default: `false` | +| `bidViewability` | Required | Object | Configuration object for instream tracking | +| `bidViewability.enabled` | Required | Boolean | when set to true, the module will emit BID_VIEWABLE when applicable. Default: `false` | +| `bidViewability.firePixels` | Optional | Boolean | when set to true, will fire the urls mentioned in `bid.vurls` which should be array of URLs. Default: `false` | | `bidViewability.customMatchFunction` | Optional | function(bid, slot) | when passed this function will be used to `find` the matching winning bid for the GPT slot. Default value is ` (bid, slot) => (slot.getAdUnitPath() === bid.adUnitCode || slot.getSlotElementId() === bid.adUnitCode) ` | -As both params are optional, publishers do not need to set any config at all... the existence of this module in the Prebid.js package enables the functionality. - ## Example of setting module config {% highlight js %} pbjs.setConfig({ bidViewability: { + enabled: true, firePixels: true, customMatchFunction: function(bid, slot){ console.log('using custom match function....');