diff --git a/admin-manual/maintenance/images/analytics-create-account-measure.png b/admin-manual/maintenance/images/analytics-create-account-measure.png deleted file mode 100644 index 000f35fb..00000000 Binary files a/admin-manual/maintenance/images/analytics-create-account-measure.png and /dev/null differ diff --git a/admin-manual/maintenance/images/analytics-create-account-property.png b/admin-manual/maintenance/images/analytics-create-account-property.png deleted file mode 100644 index b7eef110..00000000 Binary files a/admin-manual/maintenance/images/analytics-create-account-property.png and /dev/null differ diff --git a/admin-manual/maintenance/images/analytics-create-account.png b/admin-manual/maintenance/images/analytics-create-account.png deleted file mode 100644 index a2a9582f..00000000 Binary files a/admin-manual/maintenance/images/analytics-create-account.png and /dev/null differ diff --git a/admin-manual/maintenance/images/analytics-property-tracking-code.png b/admin-manual/maintenance/images/analytics-property-tracking-code.png index 31d6626e..c7faffbd 100644 Binary files a/admin-manual/maintenance/images/analytics-property-tracking-code.png and b/admin-manual/maintenance/images/analytics-property-tracking-code.png differ diff --git a/admin-manual/maintenance/images/google-analytics-custom-dimension.png b/admin-manual/maintenance/images/google-analytics-custom-dimension.png deleted file mode 100644 index 7ba756f2..00000000 Binary files a/admin-manual/maintenance/images/google-analytics-custom-dimension.png and /dev/null differ diff --git a/admin-manual/maintenance/images/google-analytics-pages-and-screens.png b/admin-manual/maintenance/images/google-analytics-pages-and-screens.png new file mode 100644 index 00000000..10afb072 Binary files /dev/null and b/admin-manual/maintenance/images/google-analytics-pages-and-screens.png differ diff --git a/admin-manual/maintenance/web-analytics.rst b/admin-manual/maintenance/web-analytics.rst index 2ed638e8..2c75719a 100644 --- a/admin-manual/maintenance/web-analytics.rst +++ b/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 `_. +like to gather analytic data. The best known open source solutions are probably +`Matomo `_ and `Open Web Analytics `_. You should be able to configure any solution in AtoM by editing the -corresponding +corresponding `PHP 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 ` and +:ref:`clear the cache ` and :ref:`restart PHP-FPM `. .. SEEALSO:: @@ -110,32 +111,19 @@ 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 ` and -:ref:`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 ++++++++++++++++++++++++++++++++++++++++++++++++++++ @@ -143,40 +131,27 @@ 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 ` @@ -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 `__, to configure your containers and tags. @@ -220,34 +194,19 @@ Let's begin! .. _tag-manager-web-property-config: -Google Analytics web property setup +Google Analytics tracking ID 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 `, 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 `, 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 ` 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 ` 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 `. .. 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,7 +450,7 @@ 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.* @@ -513,7 +458,7 @@ and description for the version changes and click the "Publish" button. :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.* @@ -521,7 +466,7 @@ the **Realtime > Events** report: :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 ` .. _`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 \ No newline at end of file