- add viewability.md

modules/viewability.md

@@ -0,0 +1,67 @@
+# Overview
+
+Module Name: Viewability
+
+Purpose: Track when a given HTML element becomes viewable
+
+Maintainer: atrajkovic@magnite.com
+
+# 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), '*');
+```