Frequently Asked Questions

Check out our answers to frequently asked developer questions.

Google Tag Manager

Google Tag Manager (GTM) is the tag management system the Platform uses to configure and execute Google Analytics (GA) tags on VA.gov websites. This provides the Platform Analytics & Insights team more ways to control and define what is sent to Google Analytics and when it should happen. 

With very few exceptions (namely HTML email tracking), you should never directly interface with Google Analytics. All pageviews and events should get inserted by manipulating the page's dataLayer to trigger tags in GTM.

GTM is version controlled and lets us test new implementations in separate workspaces and revert published changes if necessary. We can even provide a special debug URL that allows you to test these changes before they are published. The same GTM container is used for production and non-production websites, but is configured to send data to different Google Analytics properties depending on the page's hostname.

Google Analytics

Google Analytics (GA) is the primary web analytics tool used by the Platform team to track interactions on VA websites. We currently use the version Universal Analytics, and we are planning on running GA4 in parallel in the near future. Keep in mind that at least 10% of user interactions will be blocked from GA by ad blockers, browser privacy settings, and other filters. If you need accurate and complete transaction numbers, use a backend logging system (more information on platform data sources here).

Pageviews

A pageview is one of the core metrics measured by Google Analytics. Within GTM, we have a basic pageview tag that sends data to Google Analytics properties when a page loads.

If a user visits the homepage, goes to www.va.gov/health-care/, and then back to the homepage, Google Analytics will record the activity as:

Site Visitor Action

GA Data Collected

Veteran visits homepage

1 pageview

Veteran visits www.va.gov/health-care/

1 pageview

Veteran returns to homepage

Records a 2nd pageview for the homepage

Instrumentation

For normal pageview tracking that happens on page load, engineers will not need to implement any further tracking since GTM will handle the pageview automatically.

Additionally, much of VA.gov consists of react-based single page apps that do not always reload the page between screens. For this, we have configured GTM to track changes to the browser's history state as pageviews as well. If we did not, then these apps would only report the initial page landing. These "virtual pageviews" are tracked automatically.

Events

We also send custom events into GA to track interactions like downloads, successful or failed form submissions, button clicks, menu usage, etc. Event tracking is more customized than pageview tracking and relies on defining a dataLayer event.

Events consist of:

  • Category: Over-arching bucket categorization such as Interactions, Search, or Errors

  • Action: Descriptive event text or a delimited string of values

  • Label: Event you pass into the dataLayer

Filtering reports by the Label is the most common way to filter events in dashboards and reports.

During the Discovery phase, your team should have defined key performance indicators and other metrics that you would like to track. In the build phase, we will work with you to define any additional requirements for event tracking. The good news is that we have already defined an event structure for most requested interactions and provide automatic tracking for many design system components right out of the box.

Data Dictionary

To explore the Google Analytics event structure, visit our Data Dictionary.

Instrumentation

Our goal is to avoid custom and one-off event tagging as much as possible. While much of our current tagging is specific to a product or application, we are transitioning to a more generic tagging system. This will allow developers and product owners to use these events in new applications with minimal input from the Platform Analytics & Insights team.

The following workflow should help you implement event tracking with the least amount of effort and technical debt:

  1. Use design system components. We have baked analytics into many components in the design system. There are many other reasons you should be using these components (such as accessibility and design consistency), but it is also the easiest way to implement tracking of interactions. Many components track interactions automatically (though they can be disabled) while some (namely form components with PII / PHI concerns) simply require the addition of an enableAnalaytics parameter to the component. This pattern gives us a single point of update for future tagging changes like the addition of GA4.

  2. Use VA.gov components. If you are using a component native to VA.gov, that would be the next best option for centralized tracking.

  3. Use the "forms system" tracking. The tracking of form interactions - particularly successful application submissions - is an important metric. Instead of implementing your own form events, use the submission helper functions in the form-system application.

  4. Use "global" tracking. For some things that aren't proper components (like buttons), we have implemented "global" tracking by attaching JavaScript events to elements via CSS selectors. This tends to only work for certain applications, but is still preferred to application scoped tracking.

  5. As a last resort or for one-off events, create application scoped events. It may be necessary to implement your events manually in your application. For these situations, it is best to centralize all event code in one location. This will help reduce overall technical debt and make future tagging updates easier to implement.

If you are manually pushing events into the dataLayer, be sure to use the recordEvent helper function. This wrapper for dataLayer.push will help ensure the global object is instantiated correctly.