SPIKE: Creation of a GA4 adapter (provider) for hyrax/hyku

[crisr15]

Summary

hyrax and hyku are currently using google analytics version UA, which is being decommissioned in July. In order to continue for hyrax to received analytics using google a new adapter (provider) needs to be made to work with GA4.

hyrax will need to be able to make calls to google analytics using GA4. Then the individual calls and reports will need to be modeled to work properly.

Acceptance Criteria

• [ ] research what needs to be done to allow analytics to work with google analytics 4
• [ ] create the related tickets for the above

Testing Instructions

Notes

This issue on hyrax has some suggestions and next steps: https://github.com/samvera/hyrax/issues/5970

This documentations deals with the differences between V1 and V4 API calls for google analytics. Confirm we are using V1 before proceeding: https://developers.google.com/analytics/devguides/migration/api/reporting-ua-to-ga4#data-api-v1-request

And this documentation outlines the different dimensions for field names between V1 and V4. https://developers.google.com/analytics/devguides/migration/api/reporting-ua-to-ga4-dims-mets

PR for adding analytics initially to get an overview of the work: https://github.com/samvera/hyrax/pull/5089/files

[crisr15]

Use google-analytics-data gem as it works with V4 and would let us wait until Legato was updated.

[alishaevn]

terminology

• Google Analytics Reporting API v4 => Universal Analytics (what we already have)
• Google Analytics Data API v1 => Google Analytics 4 (what we're going to)

[alishaevn]

tasks

(all file references are in hyrax)

• determine ENV variables needed for ga4
• add ga4 variables to ".dassie/config/analytics.yml" and "lib/generators/hyrax/templates/config/analytics.yml"
• update the default config.analytics_provider in ".dassie/config/initializers/hyrax.rb"?
• update comment in .env to reference ga4 as a potential HYRAX_ANALYTICS_PROVIDER value
• update the readme
• update conditionals in "app/assets/javascripts/hyrax/analytics_events.js" to account for ga4
• move the methods in "app/services/hyrax/analytics/matomo.rb" to a file structure like "app/services/hyrax/analytics/google/"
  • instead of using "google" in the new file structure, it needs to match the new HYRAX_ANALYTICS_PROVIDER name we created
• uniform all provider actions (events, visitors, etc) in the "app/services/hyrax/analytics/xxx" path
• figure out what to do with "app/services/hyrax/analytics/google.rb" should that code go in one of the actions files?
• create a "app/views/shared/_HYRAX_ANALYTICS_PROVIDER.html.erb" file
• how do we track events??
• how do we track downloads?

to be continued...

[alishaevn]

ref legato pr:

• https://github.com/tpitale/legato/pull/141

[alishaevn]

tasks

• set up the ga4 property
• see the state of the legato gem on monday, may 15.
  • if it's ready to go, great
  • if it's not ready to go....it seems best to take it across the line and use it since that's what we already have (is about 80-90% ready today per tpitale)

resources for rails

• https://medium.com/fiatinsight/using-the-google-analytics-reporting-api-v4-with-rails-8d3c2f689807

[alishaevn]

sample breakdown

• property: 1-2
• legato: 5-8 (based on only doing the "filter" work. may increase otherwise. needs someone "fairly senior" and potentially pairing)
• determine g4a properties that need to be set in hyrax env/analytics files: 2-3
• restructure matomo to use the google file structure: 1-2
• make existing google and matomo actions uniform: 2-3-5
• setup ga4 actions/file structure: 3-5
• make ga4 the default for everything and set up the app to be without "google": 2-3
• update/add specs: 2-3

(if we don't use legato and go with the google-analytics-data gem, that's another unknown risk. probably a 5-8)

[crisr15]

Why are we restructuring matomo? Matomo is not broken and should not need to change.

And why this step: make ga4 the default for everything and set up the app to be without “google”: 2-3.? We want people to be able to use google, googleGA4 or matomo so I dont understand why it becomes the default for everything or why we are removing service from the other?

[DiemBTran]

Moving this to Client QA for further discussion

[sephirothkod]

@crisr15 I think the matomo restructure was an option that we talked about to make everything uniform, but not required as part of this work.

the step about the app being "without google" meant the app would be able to run GA4 as default without the need to rely on any of the old google analytics code (called 'google' in the code).

[crisr15]

We would not want to remove any of the current google functionality until July as some users will not have switched over and we would want to contribute this back

[alishaevn]

(moving the convo from slack here since the questions were also asked here)

Why are we restructiring matomo? Matomo is not broken and should not need to change.

true, matomo works. the new structure would be in line with how google is though, as well as what we plan to do for ga4. so, more of a best practice change.

make ga4 the default for everything

google (ua) is the default for all things analytics right now. since it’s about to be deprecated, we need to change that.

and set up the app to be without “google”

the idea here is to make it easy to yank out the old google stuff once july comes since it won’t be of any use

[alishaevn]

context about next steps can be found in slack.

[cazzerson]

Thank you so much for working on this! We're trying to move to Matomo at UNC at Chapel Hill Libraries, and have discovered that the Matomo implementation is incomplete. This issue describes part of the problem. Basically, things like page view stats and public download stats aren't working for Matomo.

If we can be helpful with this work, please let me know. At a minimum, we have an active instance of Matomo that we can test against.