Update Web Analytics documentation. (#230)

admin-manual/maintenance/web-analytics.rst

@@ -39,8 +39,9 @@ Logfile analysis tools
 
 These types of tools require access to the log files generated by the web server.
 
-* AWStats: http://awstats.sourceforge.net/
-* Webalizer: http://www.webalizer.org/
+* AWStats: https://awstats.sourceforge.net/
+* Webalizer: https://www.webalizer.net/
+* GoAccess: https://goaccess.io/
 
 .. _page-tagging-tools:
 
@@ -49,17 +50,17 @@ Page tagging tools
 
 The tools found under this section require a system administrator or developer
 to insert a JavaScript code snippet into the relevant page in AtoM where you'd
-like to gather analytic data. Probably the best known open source solution is
-`Piwiki <http://piwik.org/>`_.
+like to gather analytic data. The best known open source solutions are probably
+`Matomo <https://matomo.org>`_ and `Open Web Analytics <https://openwebanalytics.com/>`_.
 
 You should be able to configure any solution in AtoM by editing the
-corresponding 
+corresponding
 `PHP templates <https://github.com/artefactual/atom/tree/HEAD/apps/qubit/templates>`_.
 
 AtoM also includes built-in integration with `Google Analytics`_, described
-further below. By studying the way that the tracking snippets are incorporated 
+further below. By studying the way that the tracking snippets are incorporated
 into the PHP templates linked above, you should be able to make modifications
-as needed based on your chosen solution to implement something similar.  
+as needed based on your chosen solution to implement something similar.
 
 **Jump to:**
 
@@ -75,7 +76,7 @@ Google Analytics
 
 `Google Analytics`_ is a web analytics service offered by Google that tracks and
 reports website traffic and activity, such as session duration, pages viewed
-per session, bounce rates of individuals using the site, and more. 
+per session, bounce rates of individuals using the site, and more.
 
 You can configure `Google Analytics`_ in AtoM by adding your tracking
 ID to the ``config/app.yml`` configuration file:
@@ -85,7 +86,7 @@ ID to the ``config/app.yml`` configuration file:
      google_analytics_api_key: G-XXXXXXXXXX
 
 Replace ``G-XXXXXXXXXX`` with your tracking ID. Once you are done, remember to
-:ref:`clear the cache <maintenance-clear-cache>` and 
+:ref:`clear the cache <maintenance-clear-cache>` and
 :ref:`restart PHP-FPM <troubleshooting-restart-php-fpm>`.
 
 .. SEEALSO::
@@ -110,73 +111,47 @@ form of name).
 * Repository pages use the repository's *authorized form of name* value
 
 .. SEEALSO::
-   
+
    * :ref:`archival-institutions`
    * :ref:`link-archival-institution`
    * :ref:`link-repo-actor`
 
-Follow the instructions provided in Google's Analytics Help pages to
-`Set up custom dimension`_. When you reach step 6, *Select the scope*, choose
-**Hit** as the scope and set it to *active*. Once you have completed all the
-steps, the custom dimension will be displayed in a table. The index number is
-displayed in the column **Index**.
-
-In the ``config/app.yml`` configuration file, set the newly-created dimension
-index number below the API key and make sure that the setting is uncommented.
-
-.. code-block:: yaml
-
-     google_analytics_api_key: G-XXXXXXXXXX
-     google_analytics_institutions_dimension_index: 1
-
-Once you are done, remember to
-:ref:`clear the cache <maintenance-clear-cache>` and 
-:ref:`restart PHP-FPM <troubleshooting-restart-php-fpm>`.
-
-.. SEEALSO::
-
-   * :ref:`customization-config-files`
+Follow the instructions provided in Google's Analytics Help pages to `Create an
+event scoped custom dimension`_. When you reach step 5, *Event parameter*, choose
+**page_title**. Once you have completed all the steps, the custom dimension will
+be displayed in a table. Next, you want to navigate to your AtoM site and access
+all of the repositories you would like to track. This step is required so that we
+can use the repository's page_title as a variable for filtering for our dimension.
+Note that these variables can take up to 24 hours to appear in GA4, and the
+following instructions will require access to these variables.
 
 Viewing Google Analytics institutional pageview data
 ++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 There are several ways to visualize analytics data in the Google Analytics
 dashboard. You can view institution names in the page views table:
 
-#. In the Google Analytics dashboard left sidebar, select **Behaviour**.
-#. Under **Site Content**, select **All pages**.
-#. In the main body of the page, below the graph showing page hits, open the
-   **Secondary dimension** dropdown and select **Custom Dimensions**, then your
-   dimension.
-#. A new column should appear in the table below, with the name of the custom
-   dimension as the column header. Clicking on the column header will sort the
-   table alphabetically by institution.
-#. You can export this data by clicking the **Export** button in the top right.
-
-   .. image:: images/google-analytics-custom-dimension.*
+#. In the Google Analytics dashboard left sidebar, select **Reports**.
+#. Under **Life cycle**, select **Engagement** and **Pages and screens**.
+#. On the right hand corner, select **Customize report**, then **Dimensions**.
+   Add the new dimension to list, and click **Apply**.
+#. Next, in the Customize report page, click **Add filter**. Select your custom
+   dimension and set the **Match Type** to **exactly matches**, and select all
+   repositories you would like to track in the populated list. Note that variables
+   are made available on GA4 by accessing them in your AtoM site and can take up
+   to 24 hours to populate in GA4.
+#. Click **Apply** and **Save** to save your changes. Notice the new filter under
+   the *Pages and screens* title and can select your event in the dropdown below
+   the table graphs.
+
+   .. image:: images/google-analytics-pages-and-screens.*
       :align: center
       :width: 90%
       :alt: The Google Analytics page behaviour screen, with the secondary dimension highlighted
 
-It is also possible to create a custom report that displays the total number of
-pageviews for each institution:
-
-#. In the Google Analytics dashboard left sidebar, select **Customization**,
-   followed by **Custom Reports**.
-#. Select **New custom report**.
-#. Give the report a title and following parameters:
-
-   * Name: The default name is fine; if you want to add more tabs to the resulting
-     output, you can change it to a more specific name.
-   * Type: Select **Flat Table**
-   * Dimensions: Click on **+ add dimension** and select Page (under Behaviour);
-     repeat and select Institution (under Custom Dimension)
-   * Metrics: Click on **+ add metric** and select Pageviews (under Users)
-
-#. Click Save. The report will be displayed and can be exported by clicking the
-   **Export** button in the top right.
-#. You can save this report for future review by clicking on the **Save** button
-   in the top right.
+#. You can export this data by clicking the **Share this report** button on the
+   top right corner. Select **Download File** and select whether you'd prefer a
+   **Download PDF** or **Download CSV**.
 
 :ref:`Back to top <maintenance-web-analytics>`
 
@@ -194,17 +169,16 @@ directly.
 
 These can be used in AtoM to collect end-user analytics in a more granular way
 than Google Analytics allows on its own - for example, seeing how often a
-:term:`finding aid` is downloaded, or how often a :term:`clipboard` is saved. 
+:term:`finding aid` is downloaded, or how often a :term:`clipboard` is saved.
 
-The following section will walk you through set-up and configuration of 
+The following section will walk you through set-up and configuration of
 Tag Manager for use in AtoM, and we'll use tracking finding aid downloads as
-an example implementation. 
+an example implementation.
 
 **Requirements**
 
-You'll need to have a `Google Analytics`_ account, and your tracking ID, 
-configured with a `web property`_, to be able to visualize Tag Manager reports. 
-You'll also need to set up a 
+You'll need to have a `Google Analytics`_ account, and your tracking ID configured
+to be able to visualize Tag Manager reports. You'll also need to set up a
 `Google Tag Manager account <https://support.google.com/tagmanager/answer/6103696?hl=en&ref_topic=3441530>`__, to configure your
 containers and tags.
 
@@ -223,31 +197,16 @@ Let's begin!
 Google Analytics web property setup
 +++++++++++++++++++++++++++++++++++
 
-1. If you haven't already, log in to https://analytics.google.com with a Google 
-   account and click the "Create Account" button.
+1. If you haven't already, log in to https://analytics.google.com with a Google
+   account and click the "Start collecting data" button.
 
-.. image:: images/analytics-create-account.*
-   :align: center
-   :width: 90%
-   :alt: Creating an account in Google Analytics
-
-2. In the "What do you want to measure?" section, select **Web**.
-
-.. image:: images/analytics-create-account-measure.*
-   :align: center
-   :width: 90%
-   :alt: Selecting Web while creating a Google Analytics account
+2. Select **Web** as you platform.
 
-3. Fill out the Property setup section and click the "Create" button. 
+3. Fill out Website URL with your AtoM URL and click **Create**.
 
-.. image:: images/analytics-create-account-property.*
-   :align: center
-   :width: 90%
-   :alt: Configuring the Property section while creating an account in Google Analytics
-
-4. Accept the service agreement that pops up. You'll be redirected to the 
-   Tracking Code section of your new web property. Copy down the Tracking ID 
-   shown on this screen - you'll need this to set up your Google Tag Manager 
+4. Accept the service agreement that pops up. You'll be redirected to the
+   Tracking Code section of your new web property. Copy down the Tracking ID
+   shown on this screen - you'll need this to set up your Google Tag Manager
    variables.
 
 .. image:: images/analytics-property-tracking-code.*
@@ -260,7 +219,7 @@ Google Analytics web property setup
 Google Tag Manager container set up
 +++++++++++++++++++++++++++++++++++
 
-1. Log in to https://tagmanager.google.com/ with a Google account and click the 
+1. Log in to https://tagmanager.google.com/ with a Google account and click the
    "Create Account" button.
 
    .. image:: images/gtm-create-account.*
@@ -289,43 +248,29 @@ Google Tag Manager container set up
    .. image:: images/gtm-dashboard-container-id.*
       :align: center
       :width: 90%
-      :alt: Google Tag Manager dashboard, with the container ID highlighted in 
+      :alt: Google Tag Manager dashboard, with the container ID highlighted in
             the top right corner
 
-   You'll need to copy this ID into AtoM's ``config/app.yml`` configuration 
-   file. An example: 
-
-   .. code-block:: yaml
-
-      google_tag_manager_container_id: GTM-AC4M1L4
-
-.. TIP:: 
-
-   For more information on working with AtoM's configuration files, see: 
-
-   * :ref:`customization-config-files`
+.. NOTE::
+   As of GA4, the GTM ID is no longer required within the AtoM codebase and is
+   configured to GA4 within GTM.
 
-   Don't forget to clear the application cache and restart PHP-FPM after
-   modifying this file! See: 
+   See: `Configure GA4 in GTM`_
 
-   * :ref:`maintenance-clear-cache`
-   * :ref:`troubleshooting-restart-php-fpm`
 
-4. Once the tracking code is in place and PHP-FPM has been restarted, the
-   tracking code snippets will be included in every page and you can start
-   setting up tags to track events in your pages and getting reports in
-   Google Analytics.
+4. Once GTM and GA4 are configured, you can start setting up tags to track events
+   in your pages and getting reports in Google Analytics.
 
 .. _tag-manager-variables:
 
 Tag Manager Variables
 +++++++++++++++++++++
 
-In the following example we're going to track Click events (buttons, links, 
+In the following example we're going to track Click events (buttons, links,
 etc). First we need to enable the built-in "Clicks" variables, and make a few
-other configuration changes. 
+other configuration changes.
 
-1. Click "Variables" in the left sidebar and then the "Configure" button in the 
+1. Click "Variables" in the left sidebar and then the "Configure" button in the
    Built-in Variables section.
 
 .. image:: images/gtm-variables.*
@@ -340,12 +285,12 @@ other configuration changes.
    :width: 90%
    :alt: Google Tag Manager Variables configuration page
 
-3. We can also create a variable to store the Tracking ID of the 
-   `Google Analytics`_ web property we set up in the section 
-   :ref:`above <tag-manager-web-property-config>`, so we can reuse it in 
-   multiple tags. 
+3. We can also create a variable to store the Tracking ID of the
+   `Google Analytics`_ web property we set up in the section
+   :ref:`above <tag-manager-web-property-config>`, so we can reuse it in
+   multiple tags.
 
-   To do so, click "Variables" in the left sidebar and then the "New" button in 
+   To do so, click "Variables" in the left sidebar and then the "New" button in
    the *User-Defined Variables* section.
 
 .. image:: images/gtm-variables.*
@@ -372,10 +317,10 @@ Tag Manager Triggers
 
 Triggers listen to events on specific page elements and make tags react when
 the event is detected. We're going to create a trigger to listen to click
-events on the Download button of the :term:`Finding aids <finding aid>` section 
-of the right-hand :term:`context menu` of an :term:`archival description`. Note 
-that this button is just an HTML link element styled to look like a button. 
-Let's set up a trigger for this event. 
+events on the Download button of the :term:`Finding aids <finding aid>` section
+of the right-hand :term:`context menu` of an :term:`archival description`. Note
+that this button is just an HTML link element styled to look like a button.
+Let's set up a trigger for this event.
 
 .. SEEALSO::
 
@@ -453,7 +398,7 @@ description.
    :alt: Google Tag Manager Tags configuration panel - setting the Event label
 
 4. In the Triggering section click the circled button or the pencil and choose
-   the Download button we configured in the 
+   the Download button we configured in the
    :ref:`previous section <tag-manager-triggers>`.
 
 .. image:: images/gtm-tags-choose-trigger.*
@@ -488,15 +433,15 @@ You'll see a Tag Manager pane at the bottom of your page.
    :width: 90%
    :alt: Previewing your AtoM site via Google Tag Manager
 
-If you click the :term:`finding aid` download button of an 
-:term:`archival description`, the PDF will be open in a new tab and you'll see a 
-new Click event in the Summary sidebar showing that the tag was successfully 
+If you click the :term:`finding aid` download button of an
+:term:`archival description`, the PDF will be open in a new tab and you'll see a
+new Click event in the Summary sidebar showing that the tag was successfully
 fired.
 
 .. image:: images/gtm-preview-tag-fired.*
    :align: center
    :width: 90%
-   :alt: Previewing a finding aid Click event on your AtoM site via Google 
+   :alt: Previewing a finding aid Click event on your AtoM site via Google
          Tag Manager
 
 .. _tag-manager-publish-report:
@@ -505,23 +450,23 @@ Publishing your tag and getting an Analytics event report
 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 After you check that the tag works you can publish your workspace by clicking
-the "Submit" button in the `Google Tag Manager`_ Container dashboard. Set a name 
+the "Submit" button in the `Google Tag Manager`_ Container dashboard. Set a name
 and description for the version changes and click the "Publish" button.
 
 .. image:: images/gtm-submit.*
    :align: center
    :width: 90%
    :alt: Submitting and publishing your tag in Google Tag Manager
 
-Now you can visit your web property in Google Analytics. You can either check 
+Now you can visit your web property in Google Analytics. You can either check
 the **Realtime > Events** report:
 
 .. image:: images/analytics-realtime.*
    :align: center
    :width: 90%
    :alt: The Realtime Events report in Google Analytics
 
-Or the **Behavior > Events** reports to see the dimensions you defined being 
+Or the **Behavior > Events** reports to see the dimensions you defined being
 tracked.
 
 .. image:: images/analytics-behavior.*
@@ -532,6 +477,6 @@ tracked.
 :ref:`Back to top <maintenance-web-analytics>`
 
 .. _`Google Analytics`: https://analytics.google.com/analytics/web/#/
-.. _`Set up custom dimension`: https://support.google.com/analytics/answer/2709829#set_up_custom_dimensions
+.. _`Create an event scoped custom dimension`: https://support.google.com/analytics/answer/10075209?hl=en#zippy=%2Ccreate-an-event-scoped-custom-dimension
 .. _`Google Tag Manager`: https://www.google.com/tagmanager/
-.. _`web property`: https://support.google.com/analytics/answer/1042508?hl=en
+.. _`Configure GA4 in GTM`: https://support.google.com/tagmanager/answer/9442095?hl=en