From 814473521f505bbcfe88164603a297f46850d8f1 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Thu, 5 Mar 2026 11:11:05 -0500 Subject: [PATCH 01/10] Simple link tracking --- app/views/layouts/_site_header.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/layouts/_site_header.html.erb b/app/views/layouts/_site_header.html.erb index bd152ea4..559a9e0e 100644 --- a/app/views/layouts/_site_header.html.erb +++ b/app/views/layouts/_site_header.html.erb @@ -9,7 +9,7 @@

- + MIT Libraries Homepage MIT Libraries logo From 94ed5ef607d830945909cd812098d5dc61e13123 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:28:08 -0500 Subject: [PATCH 02/10] Matomo click helper function --- app/javascript/application.js | 1 + app/javascript/matomo_tracking.js | 27 +++++++++++++++++++++++++++ config/importmap.rb | 1 + 3 files changed, 29 insertions(+) create mode 100644 app/javascript/matomo_tracking.js diff --git a/app/javascript/application.js b/app/javascript/application.js index b3e67a5a..5eef2669 100644 --- a/app/javascript/application.js +++ b/app/javascript/application.js @@ -2,6 +2,7 @@ import "@hotwired/turbo-rails" import "controllers" import "loading_spinner" +import "matomo_tracking" // Show the progress bar after 200 milliseconds, not the default 500 Turbo.config.drive.progressBarDelay = 200; \ No newline at end of file diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js new file mode 100644 index 00000000..6dff39d1 --- /dev/null +++ b/app/javascript/matomo_tracking.js @@ -0,0 +1,27 @@ +// Matomo click event tracking via data attributes. +// +// Add `data-matomo-click="Category, Action, Name"` to any element to track +// clicks as Matomo events. The Name segment is optional. +// +// Examples: +// Download +// +// +// Event delegation on `document` means this works for elements loaded +// asynchronously (Turbo frames, content-loader, etc.) without re-binding. + +document.addEventListener("click", (event) => { + const el = event.target.closest("[data-matomo-click]"); + if (!el) return; + + const raw = el.dataset.matomoClick || ""; + const parts = raw.split(",").map((s) => s.trim()).filter(Boolean); + if (parts.length < 2) return; + + const [category, action, name] = parts; + + window._paq = window._paq || []; + const payload = ["trackEvent", category, action]; + if (name) payload.push(name); + window._paq.push(payload); +}); diff --git a/config/importmap.rb b/config/importmap.rb index 672f444c..ed7572b7 100644 --- a/config/importmap.rb +++ b/config/importmap.rb @@ -2,6 +2,7 @@ pin "application", preload: true pin "loading_spinner", preload: true +pin "matomo_tracking", preload: true pin "@hotwired/turbo-rails", to: "turbo.min.js", preload: true pin "@hotwired/stimulus", to: "stimulus.min.js", preload: true pin "@hotwired/stimulus-loading", to: "stimulus-loading.js", preload: true From 83d1102af39075dbedfe1061fc63cdd88c89a96a Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:28:31 -0500 Subject: [PATCH 03/10] Removed manual tracking test --- app/views/layouts/_site_header.html.erb | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/views/layouts/_site_header.html.erb b/app/views/layouts/_site_header.html.erb index 559a9e0e..bd152ea4 100644 --- a/app/views/layouts/_site_header.html.erb +++ b/app/views/layouts/_site_header.html.erb @@ -9,7 +9,7 @@

- + MIT Libraries Homepage MIT Libraries logo From c9287ae9a738a0b5b6afc874b7c678d025a0dade Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:29:46 -0500 Subject: [PATCH 04/10] Testing link click events --- app/views/search/_results_sidebar.html.erb | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/app/views/search/_results_sidebar.html.erb b/app/views/search/_results_sidebar.html.erb index 44f73edd..bc376751 100644 --- a/app/views/search/_results_sidebar.html.erb +++ b/app/views/search/_results_sidebar.html.erb @@ -4,7 +4,7 @@

Were these results useful?

Your feedback can help shape the quality and relevance of our search results.

- Send feedback + Send feedback

@@ -12,7 +12,7 @@

Need help?

Via chat, email, or consultations, we'll help you find and access what you need.

- Ask us + Ask us
\ No newline at end of file From 24d96b9806e78838ae26c45a878f11386e27e649 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:35:32 -0500 Subject: [PATCH 05/10] Commenting click listener code --- app/javascript/matomo_tracking.js | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index 6dff39d1..c9dfdf8c 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -11,17 +11,25 @@ // asynchronously (Turbo frames, content-loader, etc.) without re-binding. document.addEventListener("click", (event) => { + + // Find the closest ancestor (or self) with the data-matomo-click attribute. const el = event.target.closest("[data-matomo-click]"); if (!el) return; + // Read the attribute value and break it apart into segments. Trim whitespace and ignore empty segments. const raw = el.dataset.matomoClick || ""; const parts = raw.split(",").map((s) => s.trim()).filter(Boolean); + + // Matomo requires at least a Category and an Action — bail out if we don't have both. if (parts.length < 2) return; + // Destructure into named variables; `name` will be undefined if not provided. const [category, action, name] = parts; + // Build the payload for trackEvent and push to Matomo. window._paq = window._paq || []; const payload = ["trackEvent", category, action]; if (name) payload.push(name); window._paq.push(payload); + }); From 531b7145e5f0d2102958c714593c4b2205f82b53 Mon Sep 17 00:00:00 2001 From: djanelle-mit Date: Fri, 6 Mar 2026 16:44:00 -0500 Subject: [PATCH 06/10] Visibility tracking helper refactor plus initial test attribute --- app/javascript/matomo_tracking.js | 102 ++++++++++++++++++--- app/views/search/_results_sidebar.html.erb | 2 +- 2 files changed, 91 insertions(+), 13 deletions(-) diff --git a/app/javascript/matomo_tracking.js b/app/javascript/matomo_tracking.js index c9dfdf8c..4b9cdda6 100644 --- a/app/javascript/matomo_tracking.js +++ b/app/javascript/matomo_tracking.js @@ -1,5 +1,6 @@ -// Matomo click event tracking via data attributes. +// Matomo event tracking via data attributes. // +// CLICK TRACKING // Add `data-matomo-click="Category, Action, Name"` to any element to track // clicks as Matomo events. The Name segment is optional. // @@ -9,27 +10,104 @@ // // Event delegation on `document` means this works for elements loaded // asynchronously (Turbo frames, content-loader, etc.) without re-binding. +// +// SEEN TRACKING +// Add `data-matomo-seen="Category, Action, Name"` to any element to fire a +// Matomo event as soon as that element is added to the DOM. The Name segment +// is optional. Works for elements present on initial page load and for elements +// injected later by Turbo frames or async content loaders. +// +// Examples: +//
...
+// ... -document.addEventListener("click", (event) => { - - // Find the closest ancestor (or self) with the data-matomo-click attribute. - const el = event.target.closest("[data-matomo-click]"); - if (!el) return; +// --------------------------------------------------------------------------- +// Shared helper +// --------------------------------------------------------------------------- - // Read the attribute value and break it apart into segments. Trim whitespace and ignore empty segments. - const raw = el.dataset.matomoClick || ""; - const parts = raw.split(",").map((s) => s.trim()).filter(Boolean); +// Parse a "Category, Action, Name" attribute string and push a trackEvent call +// to the Matomo queue. Name is optional; returns early if fewer than 2 parts. +function pushMatomoEvent(raw) { - // Matomo requires at least a Category and an Action — bail out if we don't have both. + // Split on commas, trim whitespace from each part, drop any empty strings. + const parts = (raw || "").split(",").map((s) => s.trim()).filter(Boolean); + // Matomo requires at least a Category and an Action. if (parts.length < 2) return; // Destructure into named variables; `name` will be undefined if not provided. const [category, action, name] = parts; - // Build the payload for trackEvent and push to Matomo. + // Ensure _paq exists even if the Matomo snippet hasn't loaded yet + // (e.g. in development). Matomo will replay queued calls once it initialises. window._paq = window._paq || []; const payload = ["trackEvent", category, action]; if (name) payload.push(name); window._paq.push(payload); - +} + +// --------------------------------------------------------------------------- +// Click tracking +// --------------------------------------------------------------------------- + +// Attach a single click listener to the entire document (event delegation). +// This catches clicks on any element, including those added to the DOM later +// by Turbo frames or async content loaders, without needing to re-bind. +document.addEventListener("click", (event) => { + // Walk up the DOM from the clicked element to find the nearest ancestor + // (or the element itself) that has a data-matomo-click attribute. + const el = event.target.closest("[data-matomo-click]"); + // If no such element exists in the ancestor chain, ignore this click. + if (!el) return; + + pushMatomoEvent(el.dataset.matomoClick); }); + +// --------------------------------------------------------------------------- +// Seen tracking +// --------------------------------------------------------------------------- + +// Track elements that have already been processed to avoid double-firing +// if the same node is observed more than once (e.g. re-attached to the DOM). +const seenTracked = new WeakSet(); + +// Fire a Matomo event for a single element if it carries data-matomo-seen +// and hasn't been tracked yet. +function trackIfSeen(el) { + // Only process element nodes (not text nodes, comments, etc.). + if (el.nodeType !== Node.ELEMENT_NODE) return; + // Skip if this element has already fired its seen event. + if (seenTracked.has(el)) return; + + // Check the element itself for the attribute. + if (el.dataset.matomoSeen) { + seenTracked.add(el); + pushMatomoEvent(el.dataset.matomoSeen); + } + + // Also check any descendants — content loaders often inject a whole subtree + // at once, so walking deep ensures every marked element is captured. + el.querySelectorAll("[data-matomo-seen]").forEach((child) => { + if (seenTracked.has(child)) return; + seenTracked.add(child); + pushMatomoEvent(child.dataset.matomoSeen); + }); +} + +// Process all elements already present in the DOM on initial page load. +document.querySelectorAll("[data-matomo-seen]").forEach((el) => { + seenTracked.add(el); + pushMatomoEvent(el.dataset.matomoSeen); +}); + +// Watch for any new nodes added to the DOM after initial load. +// MutationObserver fires synchronously after each DOM mutation, so it catches +// both Turbo frame renders and content-loader replacements immediately. +const observer = new MutationObserver((mutations) => { + mutations.forEach((mutation) => { + // Each mutation record lists the nodes that were added in this batch. + mutation.addedNodes.forEach(trackIfSeen); + }); +}); + +// Observe the entire document subtree so no async insertion is missed. +observer.observe(document.body, { childList: true, subtree: true }); diff --git a/app/views/search/_results_sidebar.html.erb b/app/views/search/_results_sidebar.html.erb index bc376751..d7d44cda 100644 --- a/app/views/search/_results_sidebar.html.erb +++ b/app/views/search/_results_sidebar.html.erb @@ -1,4 +1,4 @@ -