Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Google Analytics v4 (gtag) #2252

Closed
nemchik opened this issue Dec 13, 2020 · 11 comments · Fixed by #2253
Closed

Google Analytics v4 (gtag) #2252

nemchik opened this issue Dec 13, 2020 · 11 comments · Fixed by #2253
Labels
Enhancement Theme-general Issues involving the theme related code within MkDocs
Milestone
1.2

Comments

@nemchik
Copy link

nemchik commented Dec 13, 2020

Google recently introduces Analytics v4.

ga4 no longer provides IDs compatible with analytics.js which are in the format UA-#####-#

ga4 now uses a new gtag.js and IDs in the format G-ABC123

Google no longer allows creation of properties with the older analytics IDs. Existing Google Analytics properties can be upgraded and converted to ga4 which will replace their UA-#####-# ID with a G-ABC123 ID. There is no way to downgrade.

Google is emailing existing users encouraging them to upgrade to ga4. To my knowledge at this time they have not announced any kind of cut off date for when migrating to ga4 must be completed.

Currently it is possible to use template overrides to put the new ga4 into an mkdocs site, however the

google_analytics:
  - UA-#####
  - auto

format is extremely convenient and easy to use (by comparison to the slightly more advanced setup of overrides).

For the purpose of making the transition possible without breaking existing setups without warning, I think it would be great to add

gtag:
  - G-ABC123

options to mkdocs.yml that would use the new gtag.js which is documented by google to be implemented as

<script async src="https://www.googletagmanager.com/gtag/js?id=G-ABC123"></script>
<script>
    window.dataLayer = window.dataLayer || [];
    function gtag() {
        dataLayer.push(arguments);
    }
    gtag('js', new Date());
    gtag('config', 'G-ABC123');
</script>

This would allow existing mkdocs users to continue using google_analytics: for as long as google continues to support it, or upgrade to gtag: very easily at their own discretion.

Alternatively it would also probably be file to implement something in google_analytics: handling that uses gtag depending on the ID specified.
This was referenced Dec 13, 2020
Closed
Closed
@waylan
Copy link
Member

waylan commented Dec 13, 2020

We have wanted to move analytics to a plugin for some time (which would make it easier for users to switch it out for another service of their choice). This would be a great opportunity to do that. As users would need to update their config to include the new gtag anyway, they can do so by enabling the plugin and providing the gtag as a config option on the plugin.

Personally, the time I have available to work on MkDocs is very limited these days, so any contributions would help this alone.

@waylan
Copy link
Member

waylan commented Dec 13, 2020

I just noticed that there are some references to this issue from the material theme. Rather than moving analytics to a plugin, another possibility would be to make the new gtag config option a theme option (nested under the theme setting). This would give theme developers complete control over it and possibly allow users to support a different service through theme customization.

The more I think about it, I'm not sure a plugin makes sense. All we need to do is insert a few lines of javascript into each page with the gtag included. That is clearly the role of templates. But to make that work from a plugin would be more difficult as a plugin can't override part of a template. It would have to work with an "included" template provided by the plugin. And that means the plugin would need to provide the relevant template. However, I suspect some template devs would prefer to provide their own.

@squidfunk, do you have any comments on whether this would make more sense as a plugin or as a theme specific config option?

@squidfunk
Copy link
Contributor

squidfunk commented Dec 13, 2020 •
edited
Loading

I just noticed that there are some references to this issue from the material theme. Rather than moving analytics to a plugin, another possibility would be to make the new gtag config option a theme option (nested under the theme setting). This would give theme developers complete control over it and possibly allow users to support a different service through theme customization.

That's definitely an option, but I first wanted to discuss this with you. IIRC, you were considering removing the top-level google_analytics key anyway, as it was added in a time were there was basically only Google Analytics offering this service. I agree that it would make much more sense as either a theme option or as a plugin. The former would give more flexibility. I just did not want to offer two options, one at the top-level and one below theme, as that would lead to confusion.

If you ask me, I'd be all for deprecating the google_analytics key and leaving it up to the theme to implement it. Just print a notice that it's deprecated and that themes should implement it downstream. Over at Material for MkDocs I'll move configuration into the theme or extra scope, and fall back to the google_analytics key as long as it is in deprecation phase. Then, with the next major release, we could remove it altogether. This would essentially free you from maintaining it.

@waylan
Copy link
Member

waylan commented Dec 13, 2020

If you ask me, I'd be all for deprecating the google_analytics key and leaving it up to the theme to implement it. Just print a notice that it's deprecated and that themes should implement it downstream.

I think that's an excellent plan. The deprecation notice should include a comment that Google is deprecating the old ID format. Let's pass on the blame for the change. 😁

We could raise the warning for two separate conditions: (1) when a user sets the google_analytics config setting, and (2) when a template references config.google_analytics. Does it make more sense to do 1, 2 or both?

Over at Material for MkDocs I'll move configuration into the theme or extra scope, and fall back to the google_analytics key as long as it is in deprecation phase. Then, with the next major release, we could remove it altogether.

We'll plan on doing the same with the built-in themes and recommend third party themes do the same.

This would essentially free you from maintaining it.

Not entirely, but it would move maintenance strictly to the built-in themes, which ensures that any details are theme specific. That eliminates any backward compatibility issues with third party themes in the future.

As an aside, this move will also be more consistent. From time to time we receive a request for some feature and I respond that the feature should be implemented through a theme. An often cited counterargument is that analytics is not implemented through a theme. This change will eliminate that counterargument.

@waylan waylan added this to the 1.2 milestone Dec 13, 2020
@waylan waylan added Theme-general Issues involving the theme related code within MkDocs and removed Needs design decision labels Dec 13, 2020
@waylan
Copy link
Member

waylan commented Dec 14, 2020

Google no longer allows creation of properties with the older analytics IDs. Existing Google Analytics properties can be upgraded and converted to ga4 which will replace their UA-#####-# ID with a G-ABC123 ID. There is no way to downgrade.

Is there a link we can point to for this?

@nemchik
Copy link
Author

nemchik commented Dec 14, 2020

Google no longer allows creation of properties with the older analytics IDs. Existing Google Analytics properties can be upgraded and converted to ga4 which will replace their UA-#####-# ID with a G-ABC123 ID. There is no way to downgrade.

Is there a link we can point to for this?

https://support.google.com/analytics/answer/9744165?hl=en

@waylan
Copy link
Member

waylan commented Dec 14, 2020

Thanks @nemchik. That will be helpful to link to in the release notes. However, I was also looking for confirmation that "Google no longer allows creation of properties with the older analytics IDs." We don't want to make that claim unless we can confirm it.

@waylan
Copy link
Member

waylan commented Dec 14, 2020

The note at the top of this page seems to discourage using the old IDs, but I get the sense that you can still create them and use them.

@nemchik
Copy link
Author

nemchik commented Dec 14, 2020

I looked into this and actually found I was slightly mistaken.

Google defaults to new accounts being created as GA4, but does still offer the ability to create property IDs for the older version of GA. They hide the option under the "advanced" button during creation.

image

Also for existing accounts that do the upgrade it looks like a new property for GA4 is created, but the old one is still usable even after performing this upgrade. Collection of information will only happen on one or the other (depending on whether you have analytics.js or gtag.js on the page). When I first upgraded one of my properties to GA4 the old property ID disappeared so I thought this was an irreversible change, however it has now reappeared (I'm not crazy, I promise it was gone 😄 ).

@waylan
Copy link
Member

waylan commented Dec 14, 2020 •
edited
Loading

Based on the comments in the bottom section of this page, if you properly do an upgrade, the new and old IDs will be linked and the old data will continue to be updated from the new ID. However, the new ID will not have the old data transferred over.

This is good to know as some users may want to continue to use the old data format. They can continue to do so. According to this, even new users can still create an old style ID and link it to the new G- ID.

@waylan waylan mentioned this issue Dec 14, 2020
Merged
@waylan
Copy link
Member

waylan commented Dec 14, 2020

I have a working and documented (but not fully tested) implementation in #2253. Any feedback is welcome.

@waylan waylan linked a pull request Dec 16, 2020 that will close this issue
Deprecate google_analytics config option. #2253
Merged
@squidfunk squidfunk mentioned this issue Mar 1, 2021
Closed
waylan added a commit that referenced this issue Jun 2, 2021
@waylan
Deprecate google_analytics config option.
80feaf0 
A new replacement option (theme.analytics.gtag) was added to the built-in themes. Multiple different services could be offered under theme.analytics. At this time only support for gtag exists, but more could be added in the future.

Fixes #2252.
@ciaransweet ciaransweet mentioned this issue Aug 2, 2021
Merged
bringhurst added a commit to bringhurst/python-devtools that referenced this issue Apr 27, 2022
@bringhurst
Type checking improvements
13f0b07 
- Add a PEP 561 marker file (py.typed).
- Run mypy during CI.
- Update black to avoid pallets/click#2225
- Update mkdocs to avoid mkdocs/mkdocs#2799
- Disable mkdocs strict mode to avoid mkdocs/mkdocs#2252
This was referenced Apr 27, 2022
Closed
Closed
@andrew-s28 andrew-s28 mentioned this issue Apr 25, 2023
Merged
@djenkins-nefco djenkins-nefco mentioned this issue Nov 20, 2023
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
Enhancement Theme-general Issues involving the theme related code within MkDocs
Projects
None yet
Milestone
1.2
Development

Successfully merging a pull request may close this issue.

Deprecate google_analytics config option. waylan/mkdocs
3 participants
@waylan @nemchik @squidfunk