Setting up Analytics for Accessibility

The first step is to pick an analytics provider to integrate with. The following options are available

If you are using a consent framework to conditionally enable your analytics, follow the instructions below and afterwards follow the guidance in this doc about integrating with your consent framework.

Setting Up With Google Analytics 4

The 2 main steps for getting setup will be

  1. Adding the Analytics for Accessibility code snippet to all pages using Google Analytics 4
  2. Configuring the code snippet on specific pages to emit additional information

Confirm Google Analytics 4 Setup

But first, we need to confirm Google Analytics 4 itself is setup.

On any of the pages where it should be active, confirm a code snippet similar to the following one is present somewhere in the HTML (likely in the head element)

<script async="" src="https://www.googletagmanager.com/gtag/js?id=G-AAAAAAAAAA"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
  
    gtag('js', new Date());
  
    gtag('config', 'G-AAAAAAAAAA');
  </script>

If you can’t find it, you’ll need to first setup and install Google Analytics 4.

If it is present, continue on.

Restrictions on Custom Event Names

At several points in this setup you’ll be asked to choose custom event names, so take a moment to familiarize yourself with what names are allowed.

These restrictions come from combining Google Analytics’ restrictions on custom event names with how custom event names are specially used by the Analytics for Accessibility code (specifically how they get incorporated into parameters).

Add in the Analytics for Accessibility Code Snippet for Google Analytics 4

On every page with the Google Analytics 4 code snippet, you’ll need to add the Analytics for Accessibility code snippet just beneath it as follows

  1. Go to the latest release’s page at https://github.com/Grunet/a11y-analytics/releases/latest
  2. Download the ga-analytics.min.js file, and copy its contents to your clipboard
  3. In a text editor, create a script tag as follows, replacing snippetContents with what’s on your clipboard
<script type="module">snippetContents</script>

  1. In the site’s source code, add the new script tag just beneath the Google Analytics 4’s script tags.

    It should end up looking something like this

    <script async="" src="https://www.googletagmanager.com/gtag/js?id=G-AAAAAAAAAA"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
  
    gtag('js', new Date());
  
    gtag('config', 'G-AAAAAAAAAA');
  </script>
  <script type="module">(...the Analytics for Accessibility snippet's contents...)</script>

With that in place, the following will now automatically happen

Add in “Accessibility Page Load” Custom Events

If the event you want to record and annotate with accessibility data is a page load (i.e. corresponds to no other user action), you’ll need to add an extra piece of code to enable this as follows

  1. On each page you want to record the events, add the following script tag right before the Analytics for Accessibility script tag you added previously
<script type="module">
    globalThis.a11y_analytics_config = {
      providers: {
        ga: {
          callbacks: {
            onSyncItemsResolved() {
              gtag('event', 'syncItems page-name');
            },
            onUsesKeyboardResolved() {
              gtag('event', 'usesKeyboard page-name');
            },
            onUsesPinchZoomResolved() {
              gtag('event', 'usesPinchZoom page-name');
            },
          }
        }
      }
    }
  </script>

You should end up with something like this

<script async="" src="https://www.googletagmanager.com/gtag/js?id=G-AAAAAAAAAA"></script>
  <script>
    window.dataLayer = window.dataLayer || [];
    function gtag(){dataLayer.push(arguments);}
  
    gtag('js', new Date());
  
    gtag('config', 'G-AAAAAAAAAA');
  </script>
  <script type="module">
    globalThis.a11y_analytics_config = {
      ga: {
        callbacks: {
          onSyncItemsResolved() {
            gtag('event', 'syncItems page-name');
          },
          onUsesKeyboardResolved() {
            gtag('event', 'usesKeyboard page-name');
          },
          onUsesPinchZoomResolved() {
            gtag('event', 'usesPinchZoom page-name');
          },
        }
      }
    }
  </script>
  <script type="module">(...the Analytics for Accessibility snippet...)</script>

  1. For each page, rename page-name to a globally unique identifier for the page (e.g. landing-page).

    Note that this is part of 3 custom event names (’syncItems page-name’, ‘usesKeyboard page-name’, and ‘usesPinchZoom page-name’) so the above restrictions on custom event names apply.

With that in place, the following will now automatically happen

Viewing Data in the Google Analytics Console

Now that data should be getting reported to Google Analytics, the next step is to view the data.

But before that, we need to know what data to expect there to be.

All Possible Parameters and Values to Analyze

The key data are the parameters of the custom events.

Their names take the following preprocessed form

accessibilityAttributeAbbreviation__customEventName

With 2 additional transformations

For example if the inputs were as follows

then the parameter would be named as follows

prm__syncItems_landing_page

customEventName will always be the name of a custom event.

accessibilityAttributeAbbreviation will take on one of the following possibilities

fc
(short for forced-colors)
ic
(short for inverted-colors)
pcs
(short for prefers-color-scheme)
pc
(short for prefers-contrast)
prm
(short for prefers-reduced-motion)
fs
(short for font-size)
uk
(short for uses-keyboard)
upz
(short for uses-pinch-zoom)

These parameters can then take on different values, depending on the accessibilityAttributeAbbreviation. All of the possibilities are covered below

fc
(short for forced-colors)
Possible Values:
  • active
  • none
ic
(short for inverted-colors)
Possible Values:
  • none
  • inverted
pcs
(short for prefers-color-scheme)
Possible Values:
  • dark
  • light
pc
(short for prefers-contrast)
Possible Values:
  • custom
  • less
  • more
  • no-preference
prm
(short for prefers-reduced-motion)
Possible Values:
  • no-preference
  • reduce
fs
(short for font-size)
Possible Values:
  • A string such as "24px" where 24 can be an arbitrary number
uk
(short for uses-keyboard)
Possible Values:
  • true
upz
(short for uses-pinch-zoom)
Possible Values:
  • true

Viewing Annotated Custom Event Data or “Accessibility Page Load” Custom Event Data in the Google Analytics Console

Follow these steps for each custom event and accessibility attribute you’re interested in

  1. Pick a custom event name and an accessibility attribute of interest
  2. Determine the parameter name they correspond to (see above section)
  3. Create a custom dimension based on the parameter name
  4. Wait 24 to 48 hours for Google Analytics to populate the custom dimension with data
  5. In the Google Analytics console, navigate to Reports, then Engagement, then Events
  6. In the table, follow the link with your custom event's name
  7. In the view, find the dashboard widget with your custom dimension's name in it
The widget should show counts of your custom event parameter grouped by its possible values (or a subset of them).

Setting Up With Plausible

TODO