isabella232 / analytics-standards

WIP: Team standards for implementing website and API analytics.

This project memorializes the standards that 18F sets for itself for implementing various forms of analytics— namely website but also API. Every project that has a digital presence will integrate appropriate analytics to better learn what our users need and want. This follows well-established best practices and equips the team to better deliver great product.

Access to analytics data should be widely available to teammates, partners, and the public. There are countless use cases where a fellow 18F team member can benefit from easy access to a project's website analytics and very few reasons to limit that access. We are better able to serve our agency partners when they have ready access to robust analytics for their project.

18F team standards for analytics

Webpages should integrate both the 18F Google Analytics (GA) as well as the Digital Analytics Program (DAP).

Every 18F team member should be given read/collaborate access to the 18F GA account in the first two weeks on the job. At the same time, they should be informed of the process for gaining access to the DAP and GSA's GA account.

Once analytics has been set up, it's recommended to share read/collaborate access with the agency partners working on a project with you. Even if they do not express interest, it's better to enable them so there's no excuse for the conversation.

Separately, 18F projects that build APIs should integrate the api.data.gov service to track how developers use their web service.

18F snippet standards for website analytics

18F account snippet

The purpose of the 18F tracker snippet is to simplify/centralize analytics tracking and provide everyone within the organization access to all 18F projects' data. Additionally, the snippet contains a few modifications to meet specific privacy and security standards.

Customizations

• Anonymize IP
• Force SSL
• Upgrade the protocol-relative URL to an HTTPS URL when making the initial connection to www.google-analytics.com.

UA code

Message us on the #g-analytics slack channel, and the Analytics Guild will give you a UA code linked to an account, which all 18F members can access.

JavaScript code snippet

To add the 18F snippet:

• Copy the code below
• Replace the <<UA-CODE>> with the ua-code that you got from the Analytics Guild
• Place it immediately before the closing </head> tag

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', '<<UA-CODE>>', 'auto');
  ga('set', 'anonymizeIp', true);
  ga('set', 'forceSSL', true);
  ga('send', 'pageview');
</script>

Digital Analytics Program snippet

For more information about DAP, visit their site and their GitHub repository.

The Digital Analytics Program provides secure, central hosting for its JavaScript snippet.

To add the DAP snippet:

• Copy the code below
• Replace <<agency>> and <<subagency>> with the appropriate agency and subagency codes as in the examples below
• Place it immediately before the closing </head> tag

<script id="_fed_an_ua_tag" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=<<agency>>&subagency=<<subagency>>"></script>

Example with one subagency:

<script id="_fed_an_ua_tag" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=GSA&subagency=TTS"></script>

Example with two subagencies:

<script id="_fed_an_ua_tag" src="https://dap.digitalgov.gov/Universal-Federated-Analytics-Min.js?agency=GSA&subagency=18F,TTS"></script>

18F team standards for API analytics

Where website analytics measures visitor traffic on a website, API analytics measure how developers use a web service. 18F manages a light but powerful tool to accomplish this task: api.data.gov.

Each 18F project that builds an API should ensure it's tracking how the API is being used. The easiest means to do this is by integrating the api.data.gov service.

This ensures that system owners and stakeholders can monitor how the web service is being used. It also provides further functionality. Api.data.gov additionally provides the ability to offer API keys, set different rate limits, and to block abusive users. By integrating api.data.gov, the project not only gains its direct benefits but also gains the benefits of 18F further dogfooding its own work.

To learn how to integrate api.data.gov into your project's API, ask in the #wg-api channel in Slack or email [email protected]. Integration is fast and easy, but, for everyone's convenience, it's better to begin this conversation during the planning and pre-production stages.