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 AMP 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.

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 your site.

After opting into the Google AMP Client ID API, users who had previously visited one of your AMP pages will have their AMP ID reset as a one-time event. At that time, they will be represented as new users. 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, 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://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 instead of m., so these are treated as dissimilar. m. 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 on your AMP pages, and one for your non-AMP pages. Note that both of these code changes are required.

Important implemention notes

  • For the Client ID API to be useful, data should be collected within the same Google Analytics property.
  • AMP pages are subject to the same treatment as non-AMP pages regarding subdomain treatment. Use referral exclusion where needed and appropriate. Take note of the section below that discusses this in more detail.

Step 1. 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">

As usual when using Google Analytics for AMP pages, make sure to add the amp-analytics element to the body of your page, with the type attribute set to googleanalytics, and define tracking configuration as needed. If you’re using Google Tag Manager, you can follow this guide to deploy AMP-compliant tags.

Step 2. Opt in on your non-AMP pages

There are many ways to implement Google Analytics, so use the instructions that match your circumstance most closely. In all cases, the goal is to ensure that the first call to the Analytics create function has the useAMPclientID parameter set to true. Check if session stitching is working correctly by referring to the Setup Verification section.

If you use analytics.js

Include the following in your Analytics tracking code:

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

If you use gtag.js

Include the following in your Analytics tracking code:

gtag('config', 'UA-XXXXX-Y', {'use_amp_client_id': true});

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 a third-party tag manager

Follow the steps specified for your tag-management system to add the parameter useAmpClientId and set it to true for the Analytics create-tracker code.

Step 3. Use referral exclusion

When Google serves AMP content to users, it uses the Google AMP Cache. You must 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.

If you serve AMP pages from multiple subdomains, then you may want to treat one AMP subdomain differently than another. In this case, enter the cached versions of any existing subdomains used in referral exclusion for your website so you can maintain specific referral exclusions across AMP and non-AMP sites. For example, if you have an existing referral exclusion for your subdomain subdomain.example.com, then add a referral exclusion for subdomain-example-com.cdn.ampproject.org. Learn more about AMP Cache URL format.

You can enter AMP-related referral exclusions in Analytics ADMIN along with all of your other referral exclusions. Learn more

Setup verification

Verify that the Google AMP Client ID API is working correctly:

  1. Open the Google Chrome browser in incognito mode. Enable mobile emulator in Chrome Dev Tools.
  2. Enter a search query on google.com that will return an AMP page for your site.
  3. Click a search result for your AMP page, which should be served via the Google AMP Cache and displayed within the Google Search AMP viewer.
  4. Find the Google Analytics network request for the AMP pageview by going to the Network tab in Chrome dev tools and filtering for the string collect.
  5. Select the network request that goes to www.google-analytics.com. On the Headers tab for the request, find the client ID by scrolling to Query String Parameters. Note the cid parameter. If the client ID starts with the amp- prefix, you have correctly opted-in your AMP pages.
  6. Click Clear to clear the network requests.
  7. To verify that you have opted-in your non-AMP pages, you need to confirm that the same cid parameter persists when navigating to a non-AMP page. To do this, click any link on your AMP page that goes to a non-AMP page served from your domain. To find the client ID, again filter for the string collect. Select any network request that goes to www.google-analytics.com. Check that the cid query-parameter value matches the value you noted from Step 5.
  8. If the cid value does not match, you can troubleshoot by running the Analytics debugger and checking if the first call to ga('create' contains the useAmpClientId: true parameter (search for Running command: ga("create" in the Chrome dev tools Console tab).
Was this article helpful?
How can we improve it?