The main goal of this issue is to enable element level measurement of viewability. For best performance and to keep user experience good, the APIs mentioned below only work for amp-* elements. We already do a lot of the required calculations for these elements and additional work should not affect the performance severely.

The API/configuration comes into play when the trigger is set to fire on visible. Since there is no existing configuration that applies to triggers of type visible, the new configuration should be backward-compatible.

The API allows for additional conditions, all of which have to be true, that determine whether the trigger should be fired or not.

API configuration:

Visible Percentage

These conditions keep track of the amount of element visible in vieweport at any given time. They get triggered when the percentage of element visible is between min and max (if specified). The properties that enable these conditions are named visiblePercentageMin and visiblePercentageMax. Valid values are 0-100 (both included).

Continuous Time

These conditions keep track of the amount of time (any part of) an element has been in the viewport and fire when the time is between the minimum and maximum configured time. These conditions are configured using continuousTimeMin and continuousTimeMax. The time is expressed in milliseconds.

Total Time

These conditions keep track of total time for which any part of an element is on screen and fire when the time is between minimum and maximum. These conditions are configured using totalTimeMin and totalTimeMax. The time is expressed in milliseconds.

Unload

As the name suggests, this condition is true only when the page is in the process of being unloaded. Since using onbeforeunload and onunload are considered to be harmful for caching, this condition is provided only on a best effort basis. (details on how this will be implemented are TBD. pagehide is promising; look into it.)

Additional implementation details:

All the min values should be less than the max values. If not, both the conditions will be ignored.
When any of the conditions mentioned above are not specified, certain defaults are used. For time based and percentage conditions, no maximum value results in the condition to be not evaluated.
The trigger fires only once per page. It is fired as soon as all the conditions are met.

Summary

  "visibilitySpec": {
    "selector": <element id>,
    "visiblePercentageMin": <%>,
    "visiblePercentageMax": <%>,
    "continuousTimeMin": <milliseconds>,
    "continuousTimeMax": <milliseconds>,
    "totalTimeMin": <milliseconds>,
    "totalTimeMax": <milliseconds>,
    "unload": true
  }

Examples

visiblePercentageMin: 50
continuousTimeMin: 1000

This should fire as soon as at least 50% of the ad has been on the screen continuously for 1 second.

visiblePercentageMin: 1
totalTimeMin: 1000

This will fire after at least 1% of the ad has been on the screen for a total of 1 second.

unload: true
visiblePercentageMin: 50
continuousTimeMin: 1
continuousTimeMax: 999

This will fire when an ad is at least 50% on screen for at least 1ms, but it is unloaded before it can get to 1s.

Complete tagging example

<amp-analytics>
<script type="application-json">
{
  "requests": {
    "format1": "https://myanalytics.com/id=${id}&ct=${continousTime}&vpn=${visiblePercent}",
    "format2": "https://myanalytics.com/id=${id}&unload=1&ct=${totalTime}&vpx=${vpx}"
  },
  "vars": {
    "id": "123456"
  },
  "triggers": {
    "continuousVisible": {
      "on": "visible",
      "request": "format1",
      "visibilitySpec": {
        "selector": "adsElementSelector",
        "visiblePercentageMin": 50,
        "visiblePercentageMax": 74,
        "continuousTimeMin": 1000,
        "continuousTimeMax": 2000
      }
    },
    "unload": {
      "on": "visible",
      "request": "format2"
      "visibilitySpec": {
        "selector": "adsElementSelector",
        "unload": true
      }
    }
  }
}
</script>
</amp-analytics>

Additional variables to be supported

Descriptions of the following are still pending. Names should give an indication of what they are about.

minVisiblePercentage
The minimum visible percentage over the time that this criteria was met. For example, a ping where the element was 100%, then off the page, then 100% will report this value as 0. A ping with visiblePercentageMin=50 condition undergoing the same transitions would report somewhere between 50 and 100.

maxVisiblePercentage
Same as above, except it keeps track of the max. The maximum visible percentage over the time that this criteria was met. For example, a ping where the element was 100%, then off the page, then 100% will report this value as 100. A ping with visiblePercentageMax=50 undergoing the same transitions would report somewhere between 0 and 50 since any time where the element was 100% on the page would not be counted.

totalVisibleTime
The total time that the element has met the visiblity conditions at time this ping is sent.

continuousVisibleTime
The maximum amount of continuous time this ad has met the visible criteria at the time this ping is sent. Note that a ping with a continuous-time-min=1000 and total-time-min=5000 that is visible for 1000ms, then not visible, then visible for 2000ms, then not, then visible for 1000ms, then not, then visible for 1020ms will report 2000 for this number as that is the max continuous visible time, even if it is not the current continuous visible time (1020 in this example).

firstSeenTime
Time that at least 1px of the element is on the screen for the first time since javascript load.

lastSeenTime
Time that at least 1px of the element is on the screen for the last time since javascript load.

firstVisibleTime
Time that the element met visibility conditions for the first time since javascript load.

lastVisibleTime
Time that the element met visibility conditions for the last time since javascript load.

Still pending:

/cc @cramforce @btownsend

Add element viewability triggers for amp-analytics #1297

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions