Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Bid Viewability module documentation #2659

Merged
merged 7 commits into from
Feb 11, 2021
Merged
Show file tree
Hide file tree
Changes from 3 commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
64 changes: 64 additions & 0 deletions dev-docs/modules/bidViewable.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,64 @@
---
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 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

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

{: .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, 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: {
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
Expand Up @@ -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

Expand Down