Google Analytics 4 measurement ID how to add?

gykovacs commented 2 years ago

Details

Read the Docs project URL: https://readthedocs.org/projects/common-datasets/
Build URL (if applicable): https://readthedocs.org/projects/common-datasets/builds/17858479/
Read the Docs username (if applicable): https://readthedocs.org/profiles/gykovacs/

Expected Result

I would like to get readthedocs work with Google Analytics 4.

Actual Result

I am trying to set up Google Analytics 4 with readthedocs.org. Previously I successfully set it up (a couple of years ago), by simply copying the GA tracking ID into the proper field on the settings page, and everything worked out of the box (I guess it was GA3). Now, with a new package, I need to deal with GA4. I realized that the format of the tracking id and also its name changed to measurement ID. Copied it into the same field on the settings page, did not work. After some googleing, I tried to set the GLOBAL_ANALYTICS_CODE environment variable in the readthedocs settings page to this new tracking code, I can see the code in source of the generated html, but GA is still not capturing any traffic.

Any comments are welcome!

Work related to this removal

[ ] Remove option in project settings
[ ] Deprecation timeline and notice to users
[ ] Documentation on manual support for Plausible/Google
[ ] Remove old documentation notes on Google support
- [ ] https://github.com/readthedocs/readthedocs.org/blob/ff56366c961bdf42db48d264646fb2a86e73741a/docs/user/tutorial/index.rst?plain=1#L636
- [ ] https://github.com/readthedocs/readthedocs.org/blob/ff56366c961bdf42db48d264646fb2a86e73741a/docs/user/analytics.rst?plain=1#L32

humitos commented 2 years ago

Hi! Read the Docs does not integrates with GA4 natively as it did for GA3. I don't know if we are going to build an easy integration for GA4, but in any case, if it happens, I don't think it will be soon, tho. So, I'd recommend you to include the required HTML/JavaScript code using Sphinx/MkDocs directly.

For Sphinx, there seems to be an extension that handles this for you automatically that could be useful: https://github.com/sphinx-contrib/googleanalytics. If you go for this extension and it works, please let us know. In that case, we can update our documentation to recommend it.

stsewd commented 2 years ago

The new GA4 should already be supported https://github.com/readthedocs/readthedocs.org/pull/7691/.

@gykovacs I don't see that your project has the analytics code set, see https://docs.readthedocs.io/en/stable/analytics.html#enabling-google-analytics-on-your-project. Also, you need to re-build your versions after setting the code for it to take effect.

humitos commented 2 years ago

The new GA4 should already be supported #7691.

We should mention this somewhere in our documentation.

humitos commented 2 years ago

@gykovacs were you able to try what @stsewd said? did it work for your case?

ericholscher commented 1 year ago

I've added this to our upcoming roadmap, since GA will be deprecated in July. We should figure out a path forward.

Universal Analytics standard properties will stop processing data on July 1, 2023. To maximize historical data and to ensure that Google Analytics 4 (GA4) meets your specific needs, we recommend you make the switch to Google Analytics 4 now. This will give you the opportunity to customize the setup including using the latest site tag.

Next steps

I think we have two options:

Upgrade the RTD integration to support GA4
Drop GA support from RTD

There are a couple different points here:

We offer GA integration to our users: https://github.com/readthedocs/readthedocs.org/blob/db531da671d0da70465042074c1532177cb7819d/readthedocs/projects/models.py#L249-L268
We use GA ourselves: https://github.com/benjaoming/readthedocs.org/blob/db531da671d0da70465042074c1532177cb7819d/media/javascript/readthedocs-analytics.js#L9

We are looking at migrating our internal analytics to Plausible, but I'm not confident that we continue to want RTD-owned analytics on all generated pages. I think we can get most of the data we need from either:

Our own analytics products
CDN & application logging
Ad revenue numbers

Proposal

I think the best next steps are:

Fully deprecate RTD's GA integration, both our integration and the client-facing one. Share with them how to integrate it themselves in their tool of choice via a guide in our docs
Fully remove RTD controlled analytics in doc pages
Continue to roll out Plausible to RTD-owned pages (our docs, dashboard, website ✅ )

Edit: Hah, I just read the thread above, and realize we already support GA4... but I still think this is probably a good excuse to deprecate our GA integration anyway? It doesn't work with build.commands, and I think it's the direction we want to go anyway. It will be good practice in deprecating a user-facing feature..

humitos commented 1 year ago

I'm 👍🏼 on deprecating GA from our application and convert the integration into a documentation page.

agjohnson commented 1 year ago

I'm also partially/mostly on board with dropping GA support, but would want to look at user/customer usage for this feature before we make a decision. This has been a fairly common feature for projects to use. I'll also say that global GA gives us internal data that is quite useful to have for making decisions.

Overall, I don't feel great about extending the reach of Google though. I would feel much better about pointing users towards alternatives like Plausible, but agreed we need to document GA if we are deprecating it though.

humitos commented 1 year ago

I'm talking about deprecating the integration we offer with GA to users, mainly. The one they specify in the project's admin page. We now have integrated analytics on Read the Docs that would be enough for 80% of the projects. Those wanting more detailed analytics can always inject it using the configurations from their doctool. I don't think it's something we have to do magically behind the scenes.

On the other hand, we can decide what to do with ours analytics, the "Global Read the Docs GA", later.

From our meeting, I understand the work required here is:

[ ] send an on-site notification to those users
[ ] write a small "Changelog" blog post communicating this globally
[ ] Update analytics docs page
[ ] send an email to users defining Project.analytics_code

ericholscher commented 1 year ago

@humitos That is my understanding of the tasks as well! 💯

Though we also need a step 4 of "Note deprecation timeline in help_text with link to blog post" 👍

ericholscher commented 1 year ago

Interesting... the warning in GA now says:

To continue collecting data, go to Setup Assistant to migrate your property to Google Analytics 4. Otherwise, one may be created for you based on your current settings. Learn more about UA deprecation

I wonder if they are planning to force migration folks, which might save us some pain 🤔

agjohnson commented 1 year ago

[ ] Add support answer for users that have questions
[ ] We probably need to upgrade the client if we want our analytics

ericholscher commented 1 year ago

I'm surprised this hasn't lead to any support requests at this point. I think we can probably assume most users aren't actively looking at the GA numbers, or have migrated themselves using our docs on adding custom JS: https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html

thephez commented 1 year ago

I hesitate to mention this lest it change :sweat_smile: But I'm still getting analytics (GA4) as of today and did a build as recently as yesterday. Sounds like you wouldn't expect that to be the case? I'm not using any custom stuff - just plugged my info into the RtD interface.

ericholscher commented 1 year ago

@thephez Ah, that could be part of it. Guessing Google has delayed their cutoff because so many users haven't migrated :)

The main thing needed is to follow the GA upgrade instructions, and add it to your docs using our guide on adding JS: https://docs.readthedocs.io/en/stable/guides/adding-custom-css.html

humitos commented 8 months ago

We don't have that many valid projects here:

In [6]: Project.objects.filter(Q(analytics_code__startswith="UA-") | Q(analytics_code__startswith="G-")).count()
Out[6]: 4998  # valid

In [7]: Project.objects.filter(analytics_code__isnull=False).count()
Out[7]: 26141  # valid + invalid

I also wanted to note here that the new beta addons doesn't inject GA by default. Users wanting to use GA should inject by themselves using the configuration provided by their documentation tool.

Deprecating and removing this feature, would be another step forward on the "remove magic from the build process" since this code is currently being injected into the Sphinx's context at build time and also into the READTHEDOCS_DATA javascript object.

ericholscher commented 8 months ago

Yea, GA3 seems to also have been deprecated since mid year and we haven't heard much from users, so I think we're probably safe to move ahead.

thephez commented 8 months ago

Any idea how soon the deprecation might happen so I can plan appropriately? I didn't see any update for this on #10587.

ericholscher commented 8 months ago

@thephez I believe Google has already deprecated GA4 sometime last summer.

thephez commented 8 months ago

@thephez I believe Google has already deprecated GA4 sometime last summer.

Ah, my message wasn't very clear. I meant to ask how soon readthedocs will end support for configuring Google Analytics.

GA3 is what Google deprecated last year. GA4 is what they forced everyone to migrate to. It is alive and well (and supported by readthedocs). We've been using it for months.

ericholscher commented 8 months ago

@thephez If you want to continue to use GA4, you should be able to just include it into your build configuration, and that will continue to work. If you're using Sphinx, something like this should always work: https://github.com/sphinx-contrib/googleanalytics

agjohnson commented 7 months ago

I'm doing some issue cleanup. Are we going to do anything else here? Can this issue be closed?

ericholscher commented 7 months ago

I think the main work here is to probably remove GA from our settings and fully deprecate it.

humitos commented 2 months ago

Read the Docs will stop injecting GA automatically starting on July 29th for new projects and October 7th for all the projects. Read more about this change at https://about.readthedocs.com/blog/2024/07/addons-by-default/ and https://github.com/readthedocs/readthedocs.org/issues/11474

Users that want to keep GA working could use the Google Analytics Sphinx extension: https://github.com/sphinx-contrib/googleanalytics

readthedocs / readthedocs.org