Skip to content

Commit

Permalink
Bid Viewability module documentation (#2659)
Browse files Browse the repository at this point in the history
* API fix

* bidViewability module documentation

* wordsmithing

* adding link

* update for onBidViewable

* now we add ? in URL if not present

* change in params, added enabled param

Co-authored-by: bretg <[email protected]>
  • Loading branch information
pm-harshad-mane and bretg authored Feb 11, 2021
1 parent 595da6a commit 310463a
Showing 2 changed files with 66 additions and 1 deletion.
65 changes: 65 additions & 0 deletions dev-docs/modules/bidViewable.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
---
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 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.
- 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](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

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

## Configuration

{: .table .table-bordered .table-striped }
| Field | Scope | Type | Description |
|----------+---------+--------+---------------------------------------------------------------------------------------|
| `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) ` |

## Example of setting module config
{% highlight js %}
pbjs.setConfig({
bidViewability: {
enabled: true,
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 %}
2 changes: 1 addition & 1 deletion dev-docs/modules/instreamTracking.md
Original file line number Diff line number Diff line change
@@ -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

0 comments on commit 310463a

Please sign in to comment.