Differences

This shows you the differences between two versions of the page.

--- configuration:usage_stats [2016/12/29 18:04] – [Google Analytics] lmgonzales
+++ configuration:usage_stats [2023/11/09 19:18] (current) – demiankatz
@@ Line 3: / Line 3: @@
 It is often extremely helpful to measure user behavior in order to evaluate strengths and weaknesses of your user interface, your indexing rules and your underlying collection.
-VuFind offers several options for collecting usage statistics.
+VuFind® offers several options for collecting usage statistics.
 ===== Google Analytics =====
-[[https://analytics.google.com/|Google Analytics]] is a very popular hosted solution for gathering site statistics. VuFind offers out-of-the-box GA support through the [GoogleAnalytics] section of [[configuration:files:config.ini|config.ini]].
+[[https://analytics.google.com/|Google Analytics]] is a very popular hosted solution for gathering site statistics. VuFind® offers out-of-the-box GA support through the [GoogleAnalytics] section of [[configuration:files:config.ini|config.ini]].
 ==== Some Tips for Using Google Analytics ====
-Google Analytics provides a variety of ways to track web traffic to gain a better understanding of how users find and use your website.  Here are a few tips for using Google Analytics with VuFind.
+Google Analytics provides a variety of ways to track web traffic to gain a better understanding of how users find and use your website.  Here are a few tips for using Google Analytics with VuFind®.
   * Use the Content Drilldown option to examine what parts of the site users are visiting.\\ On the sidebar menu, navigate to Behavior -> Site Content -> Content Drilldown. In the main pane select /vufind/ in the Page path level 1 column.\\ This will show you the number of page views of records (/Records/), searches (/Search/, /Author/ (author search)), browsing activity (/Browse/ and /Alphabrowse/), and any custom pages you have created. Unless you specify a date range (in the upper right of the main pane), Google Analytics will set the date range to the last 30 day period.
@@ Line 20: / Line 20: @@
 In addition to the above tips Google Spreadsheet now has an [[https://developers.google.com/analytics/solutions/google-analytics-spreadsheet-add-on|Add-on for Google Analytics]]. You can create custom analytics reports and then create an analytics dashboard on your website using those custom charts for your administrative users to view.
-===== Piwik =====
-[[https://piwik.org/|Piwik]] is an open source project which offers similar functionality to Google Analytics but allows the data to be collected to a locally-hosted server rather than a third-party service. For libraries with concerns about privacy and applications of user-generated data, this may be a preferred option. The [Piwik] section of [[configuration:files:config.ini|config.ini]] allows simple integration with a Piwik server.
+===== Matomo 4+ =====
-===== Built-In Statistics Collection =====
+// Available starting with VuFind® 8.0. //
-:!::!: This feature was disabled in VuFind 4.0; it is strongly recommended that you use Google Analytics or Piwik instead, as these are more robust solutions. :!::!:
+(see also legacy Piwik/Matomo 3.x support below)
-The [Statistics] section of [[configuration:files:config.ini|config.ini]] allows you to configure VuFind to collect basic record view and search data into one or more of the following places:
+[[https://matomo.org/|Matomo]] (formerly called Piwik) is an open source project which offers similar functionality to Google Analytics but allows the data to be collected to a locally-hosted server rather than a third-party service. For libraries with concerns about privacy and applications of user-generated data, this may be a preferred option. The [Matomo] section of [[configuration:files:config.ini|config.ini]] allows simple integration with a Matomo server.
-  * A MySQL database table
+Enabling tracking with [Matomo] section instead of the legacy [Piwik] section is recommended whenever possible, as it uses newer tracking code and also provides support for Custom Dimensions in Matomo. Matomo recommends using Custom Dimensions instead of Custom Variables. See https://matomo.org/docs/custom-dimensions/ for more information.
-  * A Solr index
-  * A file on disk
-Reports on this data can be generated in VuFind's administration module; some targets support more detailed reports than others (with "file on disk" offering the fewest options).
+==== Tips and Notes ====
-:!: VuFind's built-in statistics mechanism is not designed to handle large volumes of data, and its use is not recommended except for short-term, limited testing. The third-party statistics options offer much more robust functionality.
+Custom Variables and Custom Dimensions are not tracked when the content is loaded using AJAX (for example, when using AJAX tabs on the record view, or when tabs or accordion segments are loaded with the list view set to "tabs" or "accordion" in the [List] section of [[configuration:files:searches.ini|searches.ini]]). If you wish to track the custom variables in this case too, change 'lightbox' to an empty string in the matomo call in lightbox.phtml.
+[[https://github.com/vufind-org/vufind/blob/dev/themes/bootstrap3/templates/layout/lightbox.phtml|themes/bootstrap3/templates/layout/lightbox.phtml]]:
+Replace (line 3):
+<code>
+<?=$this->matomo(['context' => $this->layoutContext ?? 'lightbox'])?>
+</code>
+with:
+<code>
+<?=$this->matomo(['context' => $this->layoutContext ?? ''])?>
+</code>
+This may skew your results in unpredictable ways, so be sure to test carefully. It may be necessary to create a special custom layout template and adjust additional code if you wish to track AJAX statistics in some cases but not others.
+===== Piwik/Matomo 3.x =====
+The [Piwik] section of [[configuration:files:config.ini|config.ini]] allows integration with legacy Piwik/Matomo 3.x. However, enabling tracking with [Matomo] section as described above is recommended whenever possible.
+==== Tips and Notes ====
+Custom variables are not tracked when the content is loaded using AJAX (for example, when using AJAX tabs on the record view, or when tabs or accordion segments are loaded with the list view set to "tabs" or "accordion" in the [List] section of [[configuration:files:searches.ini|searches.ini]]). If you wish to track the custom variables in this case too, remove the "lightbox = true" entry in the lightbox.phtml in the piwik call.
+[[https://github.com/vufind-org/vufind/blob/dev/themes/bootstrap3/templates/layout/lightbox.phtml|themes/bootstrap3/templates/layout/lightbox.phtml]]:
+Replace (line 2):
+<code>
+piwik(['lightbox' => true])?>
+</code>
+with:
+<code>
+piwik()?>
+</code>
+This may skew your results in unpredictable ways, so be sure to test carefully. It may be necessary to create a special custom layout template and adjust additional code if you wish to track AJAX statistics in some cases but not others.
+===== Google Tag Manager =====
+// Available starting with VuFind® 9.0. //
+[[https://tagmanager.google.com/#/home|Google Tag Manager]] is a platform for deploying a variety of Javascript code snippets ("tags") onto a website/webapp based on specific criteria ("triggers"). It supports [[https://support.google.com/tagmanager/answer/9442095|built-in tags for Google Analytics v4]] (and earlier, deprecated versions) as well as a community-provided library of tags that [[https://tagmanager.google.com/gallery/#/owners/trackify-info/templates/GoogleTagManager-WebTemplate-Matomo|includes Matomo]].
+Configure VuFind®'s out-of-the-box support for GTM through the [GoogleTagManager] section of [[configuration:files:config.ini|config.ini]].
+==== Enhanced UI Tracking with GTM and GA4 ====
+Event Tracking in GA can be used to measure the use of particular UI features beyond page navigation.  GTM makes it possible to do this without any custom Javascript.  For example, this example GTM tag and trigger record the use of the "record navigation" / "action toolbar" buttons like "Cite this" and "Text this".
+{{:configuration:gtm_tag.png?400|Tag Configuration panel showing Tag Type is GA4 Event, Event Name is "click", Event Parameters are "section" => "action_toolbar" and "link_text" => a GTM variable "Click Text"}}
+{{:configuration:gtm_trigger.png?400|Trigger Configuration panel showing Trigger Type is "Click - All Elements" and the trigger fires on "Click Element matches CSS selector .record-nav a"}}
+===== Built-In Statistics Collection =====
+:!: Early versions of VuFind® included built-in data collection mechanisms, but these were removed in VuFind® 4.0 since external services like Google Analytics and Piwik/Matomo have much richer functionality.
 ---- struct data ----
+properties.Page Owner :
 ----