Analytics APIs for AMP

Objective

Define a vendor-neutral method for adding analytics to an AMP document.

Overview

A new tag, <amp-analytics>, defines which events to measure and how the measured data is sent to an analytics vendor.

This tag provides built-in support for most widely used analytics services. For example, the following tag will send measurement requests to XYZ when the document is loaded, and when any element matching the .page_button selector is clicked.

<amp-analytics type="XYZ">
{
  "vars": {
    "account": "123456"
  },
  "triggers": [ {
    "on": "load",
    "request": "predefined-request-type1"
  }, {
    "on": "click",
    "selector": ".page_button",
    "request": "predefined-request-type2",
    "vars": {
      "foo": "Button Click",
      "bar": "Navigation",
    }
  }]
}
</amp-analytics>

Alternatively, this tag can be used to send the analytics data to a custom endpoint, request format and transport.

In both these tags, a simple templating mechanism is provided to replace {{identifier}} tokens with properties extracted from either (in descending precedence) the DOM event target element, the event configuration object, the amp-analytics configuration object, or platform provided built-in properties (for example canonical_url or referrer). This system allows declarative access to document properties.

Details

A publisher can configure the <amp-analytics> tag and use the JSON config to listen for various events and filter on elements using css selectors. There should ideally be only one tag per analytics vendor.

Analytics Tag

Each analytics vendor's configuration lives in an amp-analytics tag. The configuration that goes with the tag can be either inline or defined through an external JSON resource.

<!-- Predefined vendor -->
<amp-analytics type="google-analytics">
  // JSON Config
</amp-analytics>

<!-- Custom Vendor -->
<amp-analytics>
  // JSON config
</amp-analytics>

<!-- Custom Vendor with linked config -->
<amp-analytics config="https://analytics.com/config.json">
</amp-analytics>

type: An optional string that identifies certain pre-defined analytics services. If none is specified, the JSON config should contain the host and request values to send the analytics data to.

config: This is a URL to a JSON resource that defines the config to be used with this analytics tag. Details on the format of the config are below. This method allows the publishers to self-host the config or manage the configurations through third parties like Tag managers etc and makes the analytics on a page dynamically configurable. The transport for the URL specified here should always be https.

JSON Config

The details about how the hits for a particular vendor are fired can be specified in the JSON config. This config follows the same format for various types of analytics tags above.

<amp-analytics>
{
  // The domain:port to send the analytics data to.
  "host": "my-analytics.com:8080",

  // A map of templates to be used elsewhere in the config. The key is used to identify the template
  // and the value is a string that will be expanded into a full request before it is sent over
  // wire. Some variables defined in {{}} are platform provided others are user defined. The naming
  // convention for variables is /[a-z0-9_]+/.
  "requests": {
    "type_1": "log?d={{domain}}&p={{path}}&c={{client_id}}&dd={{domain}}&a={{account}}&s={{section}}&t={{title}}&x={{scroll_x}}&y={{scroll_y}}&sh={{screen_height}}&sw={{screen_width}}&r={{referrer}}",
    "type_2": "log?d={{domain}}&p={{path}}&c={{client_id}}&a={{account_id}}&r={{referrer}}&t={{title}}",

   // This request starts off with another request(type_2) and extends it to add additional parameters(cd1, cd3).
   "type_3": "{{type_2}}&cd1={{value1}}"
  }

  // These are the user defined variables that will be used while creating the request.[1]
  "vars": { "account": "UA-123456-1", "section": "foobar"}

  // An array of triggers that define various items of interest for analytics.
  "triggers": [{

      // This is triggered when document becomes visible and sends a hit of format "type_2".
      "on": "visible",
      "request": "type_2"
    }, {

      // This is triggered when the element #foo is tapped. The request type "type_1" is used to
      // generate the request. Vars specified take precedence over those built into platform or defined above[1].
      "on": "tap",
      "request": "type_1",
      "selector": "#foo"
      "vars": {
        "section": "Something"
        "title": "New Title"
      }
    }, {

      // This example shows how a request that was extended from another request can be used to send analytics hits.
      "on": "visible",
      "request": "type_3",
      "vars": { "value1": "foo" }
    }]}
</amp-analytics>

host: This field describes the host to which the analytics data is sent. The scheme is always https.

requests: This object defines templates that specify the request payload to be sent to an analytics host. Requests can use variables that are defined by the platform or by the publisher elsewhere in the config. If a variable can't be resolved, an empty string is used for the value.

vars: The JSON config can contain any number of named properties. These properties are used to fill in the request templates. Values of variables that are filled in from templates will be document encoded before insertion into the URL.

Variable values are defined in various places. In increasing order of precedence:

• Built-in values: AMP platform provides these values. All built-in values are defined below.
• Config level values: The JSON config provides these values. They are defined int the top level vars object and are shared between all the triggers.
• Trigger level values: Optionally defined in the vars element of each trigger object. These only apply to the trigger under which they are defined.

triggers: This field defines an array of events that are measured by the analytics vendor. Each value in the array is an object with key-value pairs defined below.

on: This value defines the DOM event that is used as the trigger for the entry. Valid values for this field are:

• tap: When one of the elements in the selector list is tapped
• click: when one of the elements in selector list is clicked
• visible: When the document is made visible
• hidden: When the document is made invisible
• timer: Based on a timer which is defined through a timer-spec.

request: Name of the request template to use for analytics requests.

selector: This is a comma separated list of selectors that will be listened to for the DOM event. This field accepts one or more comma separated list of CSS selectors that the the native browser will accept through document.querySelectorAll().

Built-in Variables

Page

• domain: AMP document's domain
• path: AMP document's path
• canonical_url: The canonical URL for the AMP document
• title: AMP document's title
• page_authors: Authors if specified in the page's schema
• page_section: Section details specified in the page's schema

User metadata

• client_id: An id associated with the user (persistent). This id will be generated by the runtime and the spec will be published soon
• client_timezone: Timezone read from the browser

Browsing data

• referrer: Referrer to page, if any. The analytics vendor has to determine if the traffic is considered as organic/referrer/direct
• timestamp: The timestamp of when the hit is generated.

Browser data

• screen_width, screen_height: Dimensions of the screen.

Scroll depth

• scroll_x, scroll_y: Current scroll depth as offset from top of page, pixels
• max_scroll_x, max_scroll_y: Maximum scroll depth attained as offset from top of page, pixels
• page_height: Current height of page, pixels

AMP data

• is_proxied: A flag indicating that beacons are coming from an AMP page
• runtime_id: Platform descriptor: A descriptor of which domain/app the AMP file is being viewed from

Timing

• page_load_time: Page load time (ms)

Misc

• random: A random string generated for each hit.
• developer_mode: true/false indicating whether the developer mode was turned on.
• hit_count: Total number of hits sent to the analytics vendor.

Examples

Note that the named examples below are just meant to show how things could be implemented. They are not really implemented yet.

Custom URL

<amp-analytics>
{
  "host": "my-analytics.com:8080",
  "requests": {
    "base_hit": "/collect?v=1&_v=a0&aip=true&_s={{hit_count}}&dl={{domain}}&dt={{title}}&sr={{screen_width}}x{{screen_height}}&ht={{timestamp}}&jid=&cid={{client_identifier}}&tid={{account}}"
    "pageview": "/r/{{base_hit}}&t=pageview&_r=1"
    "event": "{{base_hit}}&t=event&ec={{event_category}}&ea={{event_action}}&el={{event_label}}&ev={{event_value}}"

  "vars": {
    "account_id": "123456",
  }
  "triggers": {[{
    "selectors": ".measured",
    "on": "CLICK",
    "vars": {
      "event_category": "All",
      "event_label": "outbound links",
      "event_action": "click"
    },
    "request": "event"
  }, {
    "on": "LOAD",
    "request": "pageview"
  }]}
}
</amp-analytics>

Built-in tag for Google Analytics

<amp-analytics type="google-analytics">
{
  "vars": { "account_id": "UA-123456-7" }
  "triggers": {[{
    "selectors": "a .outbound",
    "on": "CLICK",
    "vars": {
      "event_category": "All",
      "event_label": "outbound links",
      "event_action": "click"
    },
    "request": "event"
  }, {
    "on": "LOAD",
    "request": "pageview"
  }]}
}
</amp-analytics>

Built-in tag for chartbeat

<amp-analytics type="chartbeat">
{
  "vars": {
    "account_id": "123456",
    "section": "Politics"
  }
  "triggers": {[{
    "on": "TIMER"
    "timer-spec": { "interval": 15, "max-count": 10 }
    "request": "default"
  }]}
}
</amp-analytics>

Remote config

<!-- The config url specifies everything that needs to be measured. -->
<amp-analytics
  config="my-config.com/pub=123456"></amp-analytics>

Known Issues

• No Built in variables for
  • Performance metrics.
  • Heuristics for active engaged time are TBD. Maybe use an open-source implementation?
  • Element viewability data
    • Based on IAB viewability standard
    • Exact built in vars, how to expose it is tbd.
  • Ecommerce data
• on semantics for first-visible, long-view and other events.
• Element level overrides for variables

Edits: Removed external link.