Set up Google AMP Client ID API

Google’s AMP Client ID API is a service that allows you to uniquely identify and analyze a user’s experience across AMP and non-AMP content. It is available for anyone to use and is supported by optional tagging changes to your Google Analytics configuration.

In this article:

About the AMP Client ID API

Google’s AMP Client ID API lets you uniquely identify users who engage with your content on AMP and non-AMP pages. If you opt-in, Google Analytics uses the AMP Client ID to determine that multiple site events belong to the same user when those users visit AMP pages via a Google viewer. Associating events and users provides features like user counts and session-based metrics.

Use the API to retrieve user IDs associated with AMP-page activity and consolidate those with your own representations of those same users on your non-AMP pages. The consolidated information provides a more accurate picture of user journeys and use of your service.

The API automatically sets the ID and expiration of the ID for each publisher. End users can opt out for individual publishers.

How the AMP Client ID API affects your data

As users who are uniquely identified across AMP and non-AMP pages return to your site, user- and session-related metrics more accurately reflect their behavior. For example, metrics like Session Duration, Bounce Rate, and Pages per Session will change positively to reflect a more accurate representation of behavior across AMP experiences.

In addition, as these users return to your AMP pages, their IDs will be reset. This will happen once for every user who comes to your AMP pages after opting into this solution. At that time they will be represented as a new user. Depending on the frequency with which users visit your site(s), this could cause a noticeable, temporary fluctuation in your New Users metric and related reporting.

Limitations

When AMP pages are published on a different origin from other non-AMP pages you want to use with the Client ID API, the origin of the AMP page and the origin of the non-AMP pages must follow specific rules in order for the Client ID API to work:

  • The schemes and ports must always match.
  • The host components of both the AMP origin and the canonical origin must be equal to ignoring all m., amp., and www. component prefixes in either host.

Examples of AMP-origin and non-AMP-origin pairings that will work:

  • https://www.example.com (AMP and non-AMP pages on the same origin)
  • https://amp.example.com  and  https://www.example.com
  • https://amp.example.com  and  https://www.example.com
  • https://m.example.com  and  https://www.example.com
  • https://amp.www.example.com  and  https://example.com
  • https://amp.example.com  and  https://m.www.example.com

Examples of AMP-origin and non-AMP-origin pairings that will not work:

  • https://www.example.com  and  http://www.example.com (non-matching scheme)
  • https://www.example.com  and  https://www.example.com:8000 (non-matching port)
  • https://amp.example.com  and  https://amp.google.com (uses google.com instead of example.com, so these are treated as dissimilar)
  • https://amp.example.com  and  https://mobile.example.com (uses mobile, so these are treated as dissimilar instead of m., which would cause them to be treated as similar)
  • https://web.amp.example.com  and  https://web.m.example.com (in this case the amp. and m. components that differ are not a prefix of the host)

Setup

By opting into usage of this service by way of encoding the prerequisite tagging changes shown below, you agree that you have read and acknowledge the Google AMP Client ID API Policy, and have implemented any requirements therein of this service in conjunction with any Google Analytics property with which it is used.

You opt into this service by making two code changes, one in your AMP page configuration file, and another in your Google Analytics javascript file.

Please also note that launching AMP pages is much the same as launching any other website, and that you should be mindful of subdomain usage and referral exclusion where needed and appropriate.

Opt in on your AMP pages

Include the following code in the <head> of all your AMP pages:

<meta name="amp-google-client-id-api" content="googleanalytics">

Opt in on your non-AMP pages

If you use Google Tag Manager

The following steps should be completed for your existing published container(s).

If you're using a Google Analytics Settings variable, you can make one change to update all associated tags:

  1. In Google Tag Manager, open the relevant container, then click Variables.
  2. Open the Google Analytics Settings variable you want to edit, then click the Variable Configuration card.
  3. Navigate to More Settings > Fields to Set.
  4. Click + ADD FIELD.
  5. Set the Field Name to useAmpClientId, and set Value to true.
  6. Save the new variable configuration.
  7. Repeat the previous steps for all relevant Google Analytics Settings variables (if you are using more than one variable in your container).
  8. Publish the container.

To make changes to individual tags if you are not using a Google Analytics Settings variable:

  1. In Google Tag Manager, open the relevant container, then click Tags.
  2. Click the tag you want to edit, then click the Tag Configuration card.
  3. Navigate to More Settings > Fields to Set.
  4. Click + ADD FIELD.
  5. Set the Field Name to useAmpClientId, and set Value to true.
  6. Save the new tag configuration.
  7. Repeat the previous steps for all relevant Google Analytics tags.
  8. Publish the container.

If you use analytics.js

Include the following in your Analytics tracking code:

ga('create', 'UA-XXXXX-Y', 'auto', {'useAmpClientId': true});

Use referral exclusion

We advise that you add the single referral exclusion with the following domain: cdn.ampproject.org. This will prevent all cached AMP subdomains served by Google from breaking sessions incorrectly. However, it's also an approach that does not allow for different treatments across subdomains. If you have a reason to treat one AMP subdomain differently than another, then you should enter the cached versions of any existing subdomains used in referral exclusion for your website (for example: your-subdomain.cdn.ampproject.org) so you can maintain specific referral exclusions across AMP and non-AMP sites. You can enter these exclusions in Analytics ADMIN along with all of your other referral exclusions. Learn more

Was this article helpful?
How can we improve it?