workbox
workbox copied to clipboard
GoogleChrome
Next steps for replaying offline analytics
Background
Hey all—there are a number of outstanding open issues related to workbox-google-analytics, as well as questions and issues from folks who are planning to move to Google Analytics 4. We thought it would be helpful to take a step back and reevaluate our original decision to ship "offline Google Analytics" as a core module in Workbox.
What does workbox-google-analytics currently do?
workbox-google-analytics's functionality can be broken down into a few parts:
- It registers runtime caching routes to match requests for the CDN-served JavaScript files needed to use the Google Analytics runtime, and handles those with a network-first strategy. This ensures that if you're offline, the necessary JavaScript can still be loaded.
- It registers runtime caching routes for the actual Google Analytics data collection requests, using a network-only strategy along with a properly configured instance of the
BackgroundSyncPlugin. - That
BackgroundSyncPluginis configured to attempt to modify theqtparameter, if present, when replaying failed data collection requests in order to reflect the original time the request was attempted. If there was a failed request that then successfully resent via background sync after, say, two hours, the modifiedqtparameter will tell Google Analytics that the event actually happened two hours ago.
And that's about it.
Problems with the current approach
First off, there are other similar platforms to Google Analytics, but Workbox has never shipped an "official" module for any of them. This might have given the false impression that using Google Analytics was required if you wanted offline analytics, when in fact it was just a question of mixing together the right runtime caching and background sync logic for your analytics platform of choice.
Second, we've historically had to play catch-up with Google Analytics as they're rolled out new URLs for loading the runtime libraries and new data collection endpoints. This doesn't happen too often, but having workbox-google-analytics paper over the underlying URLs that are supported can be confusing to folks who need to use a specific, newer interface, and are confused why it doesn't work.
Third, there is no officially supported Google Analytics 4 equivalent to the qt parameter, which the BackgroundSyncPlugin uses to indicate the time at which the event originally occurred. Automatically setting this parameter was one of the main benefits that workbox-google-analytics offered, and that benefit will no longer be relevant.
The plan moving forward
Given all that, our current plan is to cease new development of workbox-google-analytics and mark the module as deprecated. Until you upgrade to Google Analytics v4, you should be able to continue using it, but we're not likely to add in any additional functionality and may not address all the open issues.
Instead, what we'd like to do is take a "recipes" approach to enabling offline analytics, similar to how we've previously offered guidance for other use cases, like serving cached media files.
We will create new copy-and-pasteable documentation that shows how to mix bits of workbox-routing, workbox-strategies, and workbox-background-sync together to get the similar functionality for legacy Google Analytics, Google Analytics 4 (without the ability to adjust the original event timestamp), as well similar documentation for any other analytics platforms that people would like to contribute.
If members of the community would like to take these snippets of Workbox code and package them up into an unofficial module, they're more than welcome to do so—we love seeing folks build and release third-party enhancements to Workbox!
If there's sufficient demand, we may also package up these recipes and release them as part of the workbox-recipes module, which would then roughly serve the same purpose of the current workbox-google-analytics. I'm not clear how important that is to the community vs. having the usage outlined in our documentation. Please let us know if you feel strongly about it!
CC: @tropicadri, who is the new lead for Workbox, to see whether there is any update on that front.
https://github.com/GoogleChrome/workbox/issues/3149#issuecomment-1368923167
CC: @tropicadri