Generic Viewability

Overview

This module will trigger a viewability pixel when a given HTML element becomes viewable according to custom viewability criteria.

Notes:

  • Does not depend on publishers using GAM ad server (does not use GPT’s ImpressionViewableEvent).
  • Enables custom viewability criteria (timeInView and inViewThreshold).
  • Aims to provide (and in some ways extend) functionality of https://github.com/InteractiveAdvertisingBureau/openvv-html , but keeping the size to the bare minimun (openvv-html is ~26kb in size).
  • Enables publishers to track viewability through callbacks or img/js pixels.
  • Enables buy side to track viewability by posting a message from within the creative iframe (including the postMessage call in the ad markup), thus avoiding custom viewability scripts.

This module does not work on IE (uses IntersectionObserver).

Configuration

Module does not need any configuration, as long as you include it in your PBJS bundle. Viewability module has only two functions startMeasurement and stopMeasurement which can be used to enable more complex viewability measurements. Since it allows tracking from within creative (possibly inside a safe frame) this module registers a message listener, for messages with a format that is described bellow.

startMeasurement This function has 4 parameters when called directly with pbjs.viewability.startMeasurement():

  • vid: unique viewability identifier, used to reference particular tracker which can later be used to stop the measurement. It allows for multiple trackers, with different criteria to be registered for a given HTML element, independently. vid is not autogenerated by startMeasurement(), it needs to be provided by caller so that it doesn’t have to be posted back to the source iframe (in case viewability is started from within the creative).
  • element: reference to an HTML element that needs to be tracked.
  • tracker: ViewabilityTracker is an object type with two properties, method (‘img’ ‘js’ ‘callback’) and value which can be an URL string for ‘img’ and ‘js’ trackers, or a function for ‘callback’ tracker. Example: { method: 'img', value: 'http://my.tracker/123' }
  • criteria: ViewabilityCriteria is an object type with two properties, inViewThreshold which is a number (0, 1.0] representing a percentage of viewable element we’re aiming at, and timeInView which is a number of milliseconds that a given element needs to be in view continuously, above a threshold. Example: { inViewThreshold: 0.5, timeInView: 1000 }

When a tracker needs to be started, without direct access to pbjs, postMessage mechanism can be used to invoke startMeasurement, with a following payload: vid, tracker and criteria as described above, but also with message: 'Prebid Viewability' and action: 'startMeasurement'. Optionally payload can provide elementId, if available at that time (for ad servers where name of the iframe is known, or adservers that render outside an iframe). If elementId is not provided, viewability module will try to find the iframe that corresponds to the message source.

stopMeasurement: This function has only 1 parementer when called directly with pbjs.viewability.stopMeasurement():

  • vid: unique viewability identifier, referencing an already started viewability tracker.

When a tracker needs to be stopped, without direct access to pbjs, postMessage mechanism can be used here as well, to invoke stopMeasurement, providing payload with vid, message: 'Prebid Viewability' and action: 'stopMeasurement.

Example of starting a viewability measurement, when you have direct access to pbjs

    pbjs.viewability.startMeasurement(
        'ae0f9', 
        document.getElementById('test_div'),
        { method: 'img', value: 'http://my.tracker/123' },
        { inViewThreshold: 0.5, timeInView: 1000 }
    );

Example of starting a viewability measurement from within a rendered creative

	let viewabilityRecord = {
      vid: 'ae0f9',
      tracker: { method: 'img', value: 'http://my.tracker/123'},
      criteria: { inViewThreshold: 0.5, timeInView: 1000 },
      message: 'Prebid Viewability',
      action: 'startMeasurement'
    }

    window.parent.postMessage(JSON.stringify(viewabilityRecord), '*');

Example of stopping the viewability measurement, when you have direct access to pbjs

    pbjs.viewability.stopMeasurement('ae0f9');

Example of stopping the viewability measurement from within a rendered creative

	let viewabilityRecord = {
      vid: 'ae0f9',
      message: 'Prebid Viewability',
      action: 'stopMeasurement'
    }

    window.parent.postMessage(JSON.stringify(viewabilityRecord), '*');