Analytics: the basics

Important: this documentation is not applicable to your currently selected format email!

Start here to learn the basics about AMP analytics.

Use amp-pixel or amp-analytics?

AMP provides two components to meet your analytics and measurement needs: amp-pixel and amp-analytics. Both options send analytics data to a defined endpoint.

If you are looking for behavior like a simple tracking pixel, the amp-pixel component provides basic page view tracking; page view data gets sent to a defined URL. Some integrations with a vendor may call for this component, in which case they will specify the exact URL endpoint.

For most analytics solutions, use amp-analytics. Page view tracking works in amp-analytics too. But you can also track user engagement with any type of page content, including clicks on links and buttons.

See Deep Dive into AMP Analytics.

As part of integrating with the AMP platform, providers have offered pre-defined amp-analytics configurations so that it's easy to capture data and push to their tracking tools. Access vendor documentation from the Analytics Vendors list.

You can use both amp-pixel and amp-analytics in your pages: amp-pixel for simple page view tracking, and amp-analytics for everything else. You can also add multiples of each tag. If you're working with multiple analytics providers, you will need one tag per solution. Keep in mind that simpler AMP pages are better for users, so if you don’t need the extra tags, don’t use them.

Create a simple analytics configuration

Learn how to create a simple amp-pixel and amp-analytics configuration.

Simple `amp-pixel` configuration

To create a simple amp-pixel configuration, insert something like the following into the body of your AMP page:

<amp-pixel src="https://foo.com/pixel?RANDOM"></amp-pixel>

In this example, the page view data gets sent to the defined URL, along with a random number. The RANDOM variable is one of many substitution variables in the AMP platform. Learn more about Variable substitution here.

The amp-pixel component is built-in, so you won't need an inclusion declaration like you do for AMP's extended components, including amp-analytics. But you should place the amp-pixel tag as close as possible to the start of your <body>. The tracking pixel will only fire when the tag comes into view itself. If amp-pixel is positioned near the bottom of the page, it may not fire.

Simple `amp-analytics` configuration

To create a simple amp-analytics configuration, you must first include this custom-element declaration in the <head> of the AMP document (see also Component inclusion declaration):

<script async custom-element="amp-analytics" src="https://cdn.ampproject.org/v0/amp-analytics-0.1.js"></script>

The following example is similar to the amp-pixel example. Everytime a page is visible, the trigger event fires, and sends the pageview data to a defined URL along with a random ID:

<amp-analytics>
<script type="application/json">
  {
    "requests": {
      "pageview": "https://foo.com/pixel?RANDOM"
    },
    "triggers": {
      "trackPageview": {
        "on": "visible",
        "request": "pageview"
      }
    }
  }
</script>
</amp-analytics>

In the above example, we have defined a request called pageview to be https://foo.com/pixel?RANDOM. As discussed earlier, RANDOM is substituted by a random number, so the request will actually end up looking like https://foo.com/pixel?0.23479283687235653498734.

When the page becomes visible (as specified by the use of the trigger keyword visible), an event triggers and the pageview request is sent. The triggers attribute determines when the pageview request fires. Learn more about requests and triggers.

Variable substitution

Both the amp-pixel and amp-analytics components allow all standard URL variable substitutions (see AMP HTML Variable Substitutions). In the following example, the page view request is sent to the URL, along with the current AMP document’s canonical URL, its title, and a client ID:

<amp-pixel src="https://example.com/analytics?url=${canonicalUrl}&title=${title}&clientId=${clientId(site-user-id)}"></amp-pixel>

Due to its simplicity, the amp-pixel tag can only include variables defined by the platform or that the AMP runtime can parse from the AMP page. In the above example, the platform populates the values for both canonicalURL and clientId(site-user-id). The amp-analytics tag can include the same variables as amp-pixel, as well as uniquely defined variables inside the tag configuration.

Use the format ${varName} in a request string for a page or platform-defined variable. The amp-analytics tag will replace the template with its actual value at the time of construction of the analytics request (see also Variables supported in amp-analytics.

In the following amp-analytics example, the page view request is sent to the URL, with additional data extracted from variable substitutions, some provided by the platform, some defined inline, within the amp-analytics configuration:

<amp-analytics>
  <script type="application/json">
    {
      "requests": {
        "pageview":"https://example.com/analytics?url=${canonicalUrl}&title=${title}&acct=${account}&clientId=${clientId(site-user-id)}"
      },
      "vars": {
        "account":"ABC123"
      },
      "triggers": {
        "someEvent": {
          "on": "visible",
          "request": "pageview",
          "vars": {
            "title": "My homepage"
          }
        }
      }
    }
  </script>
</amp-analytics>

In the above example, the variables, account and title are defined in the amp-analytics configuration. The canonicalUrl and clientId variables aren't defined in the configuration, so their values get substituted by the platform.

IMPORTANT – Variable substitution is flexible; you can have the same variables defined in different locations, and the AMP runtime will parse the values in this order of precedence (see Variable substitution ordering).

User identification

Websites use cookies to store information specific to a user in the browser. Cookies can be used to tell that a user has visited a site before. In AMP, pages can be served from either a publisher's website or a cache (like the Google AMP Cache). The publisher's website and the cache are likely to have different domains. For security reasons, browsers can (and often will) limit access to another domain’s cookies (see also Tracking users across origins).

By default, AMP will manage the provision of a client ID whether the page is accessed from the publisher's original website or through a cache. The AMP-generated client ID has a value of "amp-" followed by a random base64 encoded string and remains the same for the user if that same user visits again.

AMP manages reading and writing of the client ID in all cases. This is particularly notable in the case when a page is served via a cache or otherwise shown outside the viewing context of the publisher's original site. In this circumstance, access to the publisher site's cookies is unavailable.

When an AMP page is served from a publisher's site, the client ID framework that AMP uses can be told about a fallback cookie to look for and use. In this case, the cid-scope-cookie-fallback-name argument of the clientId variable is interpreted as a cookie name. The formatting may appear as either CLIENT_ID(cid-scope-cookie-fallback-name) or ${clientId(cid-scope-cookie-fallback-name)}.

For example:

<amp-pixel src="https://foo.com/pixel?cid=CLIENT_ID(site-user-id-cookie-fallback-name)"></amp-pixel>

If AMP finds that this cookie is set, then the client ID substitution will return the cookie's value. If the AMP finds that this cookie is not set, then AMP will generate a value of the form amp- followed by a random base64 encoded string.

Learn more about client ID substitution, including how to add an optional user notification ID, in Variables supported in AMP analytics.

Continue to learn about analytics with Deep Dive into AMP Analytics and Use Cases.