diff --git a/docs/setup/setting-up-site-analytics.md b/docs/setup/setting-up-site-analytics.md index e27c1f143..d185c9095 100644 --- a/docs/setup/setting-up-site-analytics.md +++ b/docs/setup/setting-up-site-analytics.md @@ -16,27 +16,21 @@ MkDocs natively integrates with [Google Analytics] and offers a customizable [:octicons-tag-24: 7.1.8][Google Analytics support] · :octicons-milestone-24: Default: _none_ -Material for MkDocs integrates with both, Google Analytics 4 and the now phasing -out Universal Analytics. Depending on the given property prefix, add the +Material for MkDocs integrates natively with Google Analytics 4[^1]. If you +already set up Google Analytics and have a property, enable it by adding the following lines to `mkdocs.yml`: -=== ":material-google-analytics: Google Analytics 4" + [^1]: + Prior to Material for MkDocs 9.2.0, Universal Analytics was supported as + well. However, since Universal Analytics has been sunset, this integration + was removed in 9.2.0. - ``` yaml - extra: - analytics: - provider: google - property: G-XXXXXXXXXX - ``` - -=== ":material-google-analytics: Universal Analytics" - - ``` yaml - extra: - analytics: - provider: google - property: UA-XXXXXXXX-X - ``` +``` yaml +extra: + analytics: + provider: google + property: G-XXXXXXXXXX +``` [Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8 @@ -46,21 +40,11 @@ following lines to `mkdocs.yml`: understand how people use your documentation and what they expect to find. In order to enable site search tracking, the following steps are required: - === ":material-google-analytics: Google Analytics 4" - - 1. Go to your Google Analytics __admin settings__ - 2. Select the property for the respective tracking code - 3. Select the __data streams__ tab and click the corresponding URL - 4. Click the gear icon within the __enhanced measurement__ section - 5. Ensure that __site search__ is enabled - - === ":material-google-analytics: Universal Analytics" - - 1. Go to your Google Analytics __admin settings__ - 2. Select the property for the respective tracking code - 3. Go to the __view settings__ tab - 4. Scroll down and enable __site search settings__ - 5. Set the __query parameter__ to `q` + 1. Go to your Google Analytics __admin settings__ + 2. Select the property for the respective tracking code + 3. Select the __data streams__ tab and click the corresponding URL + 4. Click the gear icon within the __enhanced measurement__ section + 5. Ensure that __site search__ is enabled [site search]: setting-up-site-search.md @@ -102,9 +86,9 @@ extra: Both properties, `title` and `ratings`, are required. Note that it's allowed to define more than two ratings, e.g. to implement a 1-5 star rating. Since the feedback widget sends data to a third-party service, it is, of course, natively -integrated with the [cookie consent] feature[^1]. +integrated with the [cookie consent] feature[^2]. - [^1]: + [^2]: If the user doesn't accept the `analytics` cookie, the feedback widget is not shown. @@ -114,46 +98,35 @@ integrated with the [cookie consent] feature[^1]. [Google Analytics] that will quickly show you the worst- and best-rated pages of your project documentation. - === ":material-google-analytics: Google Analytics 4" + 1. Go to your Google Analytics __dashboard__ - 1. Go to your Google Analytics __dashboard__ + 2. Go to the __configure__ page on the left hand menu, then select + __custom definitions__ - 2. Go to the __configure__ page on the left hand menu, then select - __custom definitions__ + 3. Click the __custom metrics__ tab and then __create custom metrics__, + enter the following values: - 3. Click the __custom metrics__ tab and then __create custom metrics__, - enter the following values: + * Metric name: Page helpful + * Description: Was this page helpful? + * Event parameter: `data` + * Unit of measurement: Standard - * Metric name: Page helpful - * Description: Was this page helpful? - * Event parameter: `data` - * Unit of measurement: Standard + 4. Go to the __explore__ page on the left hand menu, create a new + __blank exploration__ - 4. Go to the __explore__ page on the left hand menu, create a new - __blank exploration__ + 5. Configure the report as follows: - 5. Configure the report as follows: + * Dimensions: Add `Event name` and `Page location` + * Metrics: Add `Event count` and `Page helpful` + (the custom metric created in step 3) + * Rows: `Page location` + * Values: Drag in both `Event count` and `Page helpful` + * Filters: Add a new filter for + `Event name / exactly matches / feedback` - * Dimensions: Add `Event name` and `Page location` - * Metrics: Add `Event count` and `Page helpful` - (the custom metric created in step 3) - * Rows: `Page location` - * Values: Drag in both `Event count` and `Page helpful` - * Filters: Add a new filter for - `Event name / exactly matches / feedback` + !!! warning "Delay in data availability" - !!! warning "Delay in data availability" - - The report may take 24 hours or longer to begin displaying data - - === ":material-google-analytics: Universal Analytics" - - 1. Go to your Google Analytics __dashboard__ - 2. Open the __customization__ panel on the left and go to __custom reports__ - 3. Create a __new custom report__ and set a custom __title__ and __name__ - 4. Add `Avg. Value` and `Total Events` to __metric group__ - 5. Add `Event Label` to __dimension drilldown__ - 6. Add `Event Category` to __filters__ and filter for the value __feedback__ + The report may take 24 hours or longer to begin displaying data Now, after you've saved the report and collected some feedback ratings, you'll have a list of all pages with the total number of ratings, and an @@ -185,9 +158,9 @@ The following properties are available for each rating: : :octicons-milestone-24: Default: _none_ · :octicons-alert-24: __Required__ – The value of this property is sent as a data value with the custom event - that is transmitted to Google Analytics[^2] (or any custom integration). + that is transmitted to Google Analytics[^3] (or any custom integration). - [^2]: + [^3]: Note that for Google Analytics, the data value must be an integer. [`note`](#+analytics.feedback.ratings.note){ #+analytics.feedback.ratings.note } diff --git a/material/partials/integrations/analytics/google.html b/material/partials/integrations/analytics/google.html index b7ea49478..128854da2 100644 --- a/material/partials/integrations/analytics/google.html +++ b/material/partials/integrations/analytics/google.html @@ -4,8 +4,4 @@ {% if config.extra.analytics %} {% set property = config.extra.analytics.property | d("", true) %} {% endif %} -{% if property.startswith("G-") %} - -{% elif property.startswith("UA-") %} - -{% endif %} + diff --git a/src/partials/integrations/analytics/google.html b/src/partials/integrations/analytics/google.html index 1fe53da62..a9fa37d9c 100644 --- a/src/partials/integrations/analytics/google.html +++ b/src/partials/integrations/analytics/google.html @@ -25,150 +25,73 @@ {% set property = config.extra.analytics.property | d("", true) %} {% endif %} - -{% if property.startswith("G-") %} - - - -{% elif property.startswith("UA-") %} - -{% endif %} + /* Create script tag */ + var script = document.createElement("script") + script.async = true + script.src = "https://www.googletagmanager.com/gtag/js?id={{ property }}" + + /* Inject script tag */ + var container = document.getElementById("__analytics") + container.insertAdjacentElement("afterEnd", script) + } +