Google Analytics 4 measurement ID how to add?

[gykovacs]

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

  • readthedocs.org/docs/user/tutorial/index.rst

    Line 636 in ff56366

    :ref:`enabling Google Analytics <analytics:Enabling Google Analytics on your Project>`.

  • readthedocs.org/docs/user/analytics.rst

    Line 32 in ff56366

    Enabling Google Analytics on your project

[humitos]

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]

The new GA4 should already be supported #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]

The new GA4 should already be supported #7691.

We should mention this somewhere in our documentation.

[humitos]

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

[ericholscher]

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:

  readthedocs.org/readthedocs/projects/models.py

  Lines 249 to 268 in db531da

  	analytics_code = models.CharField(
  	_('Analytics code'),
  	max_length=50,
  	null=True,
  	blank=True,
  	help_text=_(
  	'Google Analytics Tracking ID '
  	'(ex. <code>UA-22345342-1</code>). '
  	'This may slow down your page loads.',
  	),
  	)
  	analytics_disabled = models.BooleanField(
  	_('Disable Analytics'),
  	default=False,
  	null=True,
  	help_text=_(
  	'Disable Google Analytics completely for this project '
  	'(requires rebuilding documentation)',
  	),
  	)

• 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]

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

[agjohnson]

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]

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]

@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]

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]

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

[ericholscher]

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]

I hesitate to mention this lest it change 😅 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]

@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]

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]

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]

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

[ericholscher]

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

[thephez]

@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]

@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]

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

[ericholscher]

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

[humitos]

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 #11474

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