ContextQMD
Back to Amphtml

Integrate your analytics tools in AMP HTML

extensions/amp-analytics/integrating-analytics.md

latest5.4 KB
Original Source

Integrate your analytics tools in AMP HTML

Overview

If you operate a software-as-a-service tool for publishers to better understand their traffic and visitors, you may want to integrate your service into amp-analytics. This will enable your customers to view traffic patterns for their AMP HTML pages.

Before you begin

Before you can add your analytics service to AMP HTML runtime, you may need to:

  • Identify the kinds of variables and requests you'll need in an AMP HTML document for your analytics service.
  • Identify the triggers that result in analytics requests being sent from a page that would be relevant for your service.
  • Consider if and how you will track users across first-party and third-party AMP contexts.
  • Determine how your analytics dashboard handles AMP traffic.
  • Identify any missing functionality in amp-analytics, and file requests for needed features.
  • AMP Analytics sends its variables to a preconfigured endpoint. If you do not already have an existing endpoint, review this sample for an overview on how to build one.
    • For all transport types except iframe, variables are sent as query string parameters in a HTTPS request.
    • For the iframe transport type, an iframe is created and variables are sent to it via window.postMessage. In this case, the message need not be a URL. This option is available only to MRC-accredited vendors.
  • Consider how integration with amp-analytics may impact any policies (particularly your privacy policy) or agreements you may have.

Adding your configuration to the AMP HTML runtime

  1. Create an Intent-To-Implement issue stating that you'll be adding your analytics service's configuration to AMP HTML's runtime. Be sure to include cc @ampproject/wg-components in your description.
  2. Develop a patch that implements the following:
    1. A new configuration json file ${vendorName}.json in the vendors folder including any options above and beyond the default, such as:
      1. "vars": {} for additional default variables.
      2. "requests": {} for requests that your service will use.
      3. "optout": if needed. We currently don't have a great opt-out system, so please reach out to help us design one that works well for you.
      4. "warningMessage": if needed. Displays warning information from the vendor (such as deprecation or migration) in the console.
    2. If you are using iframe transport, also add a new line to ANALYTICS_IFRAME_TRANSPORT_CONFIG in iframe-transport-vendors.js containing "*vendor-name*": "*url*"
    3. An example in the examples/analytics-vendors.amp.html. reference.
    4. A test in the extensions/amp-analytics/0.1/test/vendor-requests.json file.
    5. Add your analytics service to the supported vendors list in the extensions/amp-analytics/0.1/analytics-vendors-list.md file. Include the type, description, and link to your usage documentation.
  3. Test the new example you put in examples/analytics-vendors.amp.html to ensure the hits from the example are working as expected. For example, the data needed is being collected and displayed in your analytics dashboard.
  4. Submit a Pull Request with this patch, referencing the Intent-To-Implement issue.
  5. Update your service's usage documentation and inform your customers.
  6. It's highly recommended to maintain an integration test outside AMP repo.

Tag Managers

Tag management services have two options for integrating with AMP Analytics:

  • Endpoint approach: Acting as the an additional endpoint for amp-analytics, and conducting marketing management in the backend.
  • Config approach: Conducting tag management via a dynamically generated JSON config file unique to each publisher.

The endpoint approach is the same as the standard approach detailed in the previous section. The config approach consists of creating a unique configuration for amp-analytics that is specific to each publisher and includes all of their compatible analytics packages. A publisher would include the configuration using a syntax similar to this:

html
<amp-analytics
  config="https://my-awesome-tag-manager.example.com/user-id.json"
></amp-analytics>

To take this approach, review the documentation for publishers' integration with AMP Analytics.

Further Resources