mirror of https://github.com/cncf/techdocs.git
97 lines
4.0 KiB
Markdown
97 lines
4.0 KiB
Markdown
# Analytics
|
|
|
|
This page describes how to setup or upgrade Google Analytics (GA) for your CNCF
|
|
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).
|
|
|
|
## Adding Google Analytics
|
|
|
|
For instructions on how to setup [Google Analytics 4 (GA4)][ga4] for your
|
|
[Docsy][]-based website, see [Adding Analytics][].
|
|
|
|
## Migrating to Google Analytics 4
|
|
|
|
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:
|
|
|
|
- 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`
|
|
- 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 **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][]
|
|
|
|
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
|
|
[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
|