diff --git a/docs/analytics.md b/docs/analytics.md index a5340c9..7598dc4 100644 --- a/docs/analytics.md +++ b/docs/analytics.md @@ -6,43 +6,91 @@ project's website. > **Deprecation notice**: Google's [Universal Analytics will be going away][ua] > in 2023. -When adding analytics to a new CNCF project website, use [Google -Analytics 4][ga4] (GA4). +When adding analytics to a new CNCF project website, use [Google Analytics +4][ga4] (GA4). ## Adding Google Analytics -For instructions on how to setup [Google Analytics 4 (GA4)][GA4] for your +For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your [Docsy][]-based website, see [Adding Analytics][]. ## Migrating to Google Analytics 4 -Suggested process for upgrading a CNCF project's website from [Universal Analytics][ua] to [GA4][]: +There are many ways to upgrade your project to [GA4][]. We describe one such +process below. Adapt it to your needs. Useful resources to consider include: + +- **Developer resources** for [migrating to Google Analytics 4][ga4-dev], + especially relevant is the following page: + - [Add Google Analytics 4 to an existing Universal Analytics + implementation][ga4+ua-dev] +- **Help center** resource: [Migrate from Universal Analytics to Google + Analytics 4][migration-help] + +### Phase 1 - create and activate a GA4 site tag + +1. Create an issue over the project's website with the title "Setup Google + Analytics 4" and link to [Issue #108][]. For example, see the [etcd.io issue + #595][]. + +2. Create a GA4 site tag and [connect][] it to the existing UA id. + + From your project's UA console: -1. Create a GA4 site tag and [connect][] it to the existing UA id. - From the UA console: - Select **Admin** (bottom of left-nav) - Select **Property Settings** - - Change the property name (which usually matches the project name), by adding the following suffix: `- UA` + - Change the property name (which usually matches the project name), by + adding the following suffix: `- UA` - Go back to the **Admin** level settings - Select **GA4 Setup Assistant** - - Select **I want to create a new Google Analytics 4 property > Get started** + - Select **I want to create a new Google Analytics 4 property > Get + started** - Select **Go to your GA4 property** - - Select **Admin** > **Data stream** - - Select the (only) data stream - - 📋 Copy the **MEASUREMENT ID**, we'll need it later, and past it into the appropriate row of the [status table] - - **Check**: after a while, from GA4 console home, you should see **active users** in realtime -- roughly the same number and distribution of active users reported by the UA console. I've seen the GA4 console show realtime data after a few minutes, but it has taken much longer in some cases. -2. Configure the GA4 ID as the main GA ID - - Ensure that the website supports the GA configuration of more than one id. - If it doesn't, consider using a project-specific layout like the following: - [opentelemetry.io/layouts/partials/google-analytics.html] - (which was setup via https://github.com/open-telemetry/opentelemetry.io/pull/1544) - - Set the GA4 ID as the main GA ID -3. Eventually migrate to using the Docsy or Hugo support for GA IDs (@chalin plans to upstream changes in 22Q3) + - Select **Admin** > **Data stream** + - Select the (only) data stream + - 📋 Copy the **MEASUREMENT ID**, we'll need it later, and past it into the + appropriate row of the [status table][] -[adding analytics]: https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics +3. Configure your new GA4 tag: + + - If your site is using `gtag.js`, then you have nothing more to do. Proceed + to the next step. + - If your site is using `analytics.js`, then consider upgrading to `gtag.js` + or at least adding a `gtag.js` configuration for the new GA4 site tag + (while keeping the current `analytics.js` configuration). Once this is + done, proceed to the next step. + +4. Ensure that the new GA4 site tag is receiving data. + + From GA4 console home, you should see **active users** in realtime -- + roughly the same number and distribution of active users reported by the UA + console. + +### Phase 2 - configure the GA4 ID as the main GA ID + +- Ensure that the website supports the GA configuration of more than one id. If + it doesn't, consider using a project-specific layout like the following: + [opentelemetry.io/layouts/partials/google-analytics.html] (which was setup via + https://github.com/open-telemetry/opentelemetry.io/pull/1544) +- Set the GA4 ID as the main GA ID + +### Phase 3 - switch to native Docsy or Hugo support for GA + +Eventually migrate to using the Docsy or Hugo support for GA IDs (@chalin plans +to upstream changes in 22Q3). + +[adding analytics]: + https://www.docsy.dev/docs/adding-content/feedback/#adding-analytics [connect]: https://support.google.com/analytics/answer/9973999 +[etcd.io issue #595]: https://github.com/etcd-io/website/issues/595 [docsy]: https://www.docsy.dev +[ga4-dev]: https://developers.google.com/analytics/devguides/migration [ga4]: https://support.google.com/analytics/answer/10089681 -[opentelemetry.io/layouts/partials/google-analytics.html]: https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html -[project migration status]: https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA +[ga4+ua-dev]: + https://developers.google.com/analytics/devguides/migration/measurement/add-ga4 +[issue #108]: https://github.com/cncf/techdocs/issues/108 +[migration-help]: https://support.google.com/analytics/answer/10759417 +[opentelemetry.io/layouts/partials/google-analytics.html]: + https://github.com/open-telemetry/opentelemetry.io/blob/3d8a59ea508b46497500297f334a079a4f91e293/layouts/partials/google-analytics.html +[status table]: + https://docs.google.com/spreadsheets/d/1Mx4LhdI2Un-rvGMI73SlHxQH9D2HABAJclMB3dd6lnA [ua]: https://support.google.com/analytics/answer/11583528