mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-12-18 10:25:58 +01:00
198 lines
5.9 KiB
Markdown
198 lines
5.9 KiB
Markdown
---
|
|
template: overrides/main.html
|
|
---
|
|
|
|
# Setting up site analytics
|
|
|
|
As with any other service offered on the web, understanding how your project
|
|
documentation is actually used can be an essential success factor. Material for
|
|
MkDocs natively integrates with [Google Analytics][1] and offers a customizable
|
|
and extendable [cookie consent][2].
|
|
|
|
[1]: https://developers.google.com/analytics
|
|
[2]: #cookie-consent
|
|
|
|
## Configuration
|
|
|
|
### Google Analytics
|
|
|
|
:octicons-hash-24: Setting ·
|
|
:octicons-milestone-24: Default: _none_ ·
|
|
[:octicons-tag-24: 7.1.8 ... present][Google Analytics support]
|
|
|
|
Material for MkDocs integrates with both, Google Analytics 4 and the now phasing
|
|
out Universal Analytics (`UA-*`). Depending on the prefix of the property, add
|
|
the following to `mkdocs.yml`:
|
|
|
|
=== "Google Analytics 4"
|
|
|
|
``` yaml
|
|
extra:
|
|
analytics:
|
|
provider: google
|
|
property: G-XXXXXXXXXX
|
|
```
|
|
|
|
=== "Universal Analytics"
|
|
|
|
``` yaml
|
|
extra:
|
|
analytics:
|
|
provider: google
|
|
property: UA-XXXXXXXX-X
|
|
```
|
|
|
|
[Google Analytics support]: https://github.com/squidfunk/mkdocs-material/releases/tag/7.1.8
|
|
[3]: https://github.com/squidfunk/mkdocs-material/blob/master/src/partials/integrations/analytics.html
|
|
|
|
#### Site search tracking
|
|
|
|
Besides basic page views, _site search_ can also be tracked to understand better
|
|
how people use your documentation and what they expect to find. To enable
|
|
search tracking:
|
|
|
|
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`.
|
|
|
|
_Site search tracking is not supported with Google Analytics 4 due to the much
|
|
more complicated manual setup. If you want to set up site search tracking
|
|
yourself, [this tutorial][4] might be a good start._
|
|
|
|
[4]: https://www.analyticsmania.com/post/track-site-search-with-google-tag-manager-and-google-analytics/
|
|
|
|
### Cookie consent
|
|
|
|
[:octicons-heart-fill-24:{ .mdx-heart } Insiders][Insiders]{ .mdx-insiders } ·
|
|
:octicons-hash-24: Setting ·
|
|
:octicons-milestone-24: Default: _none_ ·
|
|
[:octicons-tag-24: insiders-2.10.0 ... present][Insiders]
|
|
|
|
Material for MkDocs ships a native and extensible cookie consent form, which
|
|
asks the user for his consent prior to setting up analytics. Add the following
|
|
to `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
extra:
|
|
consent:
|
|
title: Cookie consent
|
|
description: > # (1)
|
|
We use cookies to recognize your repeated visits and preferences, as well
|
|
as to measure the effectiveness of our documentation and whether users
|
|
find what they're searching for. With your consent, you're helping us to
|
|
make our documentation better.
|
|
```
|
|
|
|
1. You can add arbitrary HTML tags in the `description`, e.g. to link to your
|
|
terms of service or other parts of the site.
|
|
|
|
Note that both, `title` and `description`, are required. If Google Analytics was
|
|
configured via `mkdocs.yml`, the cookie consent will automatically include a
|
|
setting for the user to disable it. Furthermore, [custom cookies][6] can be
|
|
integrated by using the `cookies` field:
|
|
|
|
=== "Change cookie name"
|
|
|
|
``` yaml
|
|
extra:
|
|
consent:
|
|
cookies:
|
|
analytics: Custom name # (1)
|
|
```
|
|
|
|
1. The default name of the `analytics` cookie is `Google Analytics`.
|
|
|
|
=== "Add custom cookie"
|
|
|
|
``` yaml
|
|
extra:
|
|
consent:
|
|
cookies:
|
|
analytics: Google Analytics # (1)
|
|
custom: Custom cookie
|
|
```
|
|
|
|
1. If you add a custom cookie to the `cookies` field, the `analytics` cookie
|
|
must be added back explicitly, or analytics won't be triggered.
|
|
|
|
When a user first visits your site, a cookie consent form is rendered:
|
|
|
|
[![Cookie consent][7]][7]
|
|
|
|
In order to comply with GDPR, users must be able to change their cookie settings
|
|
at any time. This can be done by creating a simple link as part of any document,
|
|
e.g. privacy policy:
|
|
|
|
``` markdown
|
|
[Change cookie settings](#__consent){ .md-button }
|
|
```
|
|
|
|
[Insiders]: ../insiders/index.md
|
|
[5]: ../insiders/index.md
|
|
[6]: #custom-cookies
|
|
[7]: ../assets/screenshots/consent.png
|
|
|
|
## Customization
|
|
|
|
### Custom site analytics
|
|
|
|
[:octicons-file-code-24: Source][3] ·
|
|
:octicons-mortar-board-24: Difficulty: _moderate_
|
|
|
|
In order to integrate another analytics service provider offering a
|
|
JavaScript-based tracking solution, you can [extend the theme][8] and add a new
|
|
`custom.html` partial [here][9]. The name of the partial can then be used to
|
|
configure the custom integration from `mkdocs.yml`:
|
|
|
|
``` yaml
|
|
extra:
|
|
analytics:
|
|
provider: custom # (1)
|
|
key: value # (2)
|
|
```
|
|
|
|
1. Of course, you can change the name to the partial to anything you like.
|
|
2. You can add arbitrary `key` and `value` combinations to configure your custom
|
|
integration. This is especially useful if you're sharing the custom
|
|
integration across multiple repositories.
|
|
|
|
[8]: ../customization.md#extending-the-theme
|
|
[9]: https://github.com/squidfunk/mkdocs-material/tree/master/src/partials/integrations/analytics
|
|
|
|
#### Instant loading
|
|
|
|
If you're using [instant loading][10], you may use the `location$` observable,
|
|
which will emit the current `URL` to listen for navigation events and register
|
|
a page view event with:
|
|
|
|
``` js
|
|
location$.subscribe(function(url) {
|
|
/* Track a page event */
|
|
})
|
|
```
|
|
|
|
Note that this must be integrated with [additional JavaScript][11].
|
|
|
|
[10]: setting-up-navigation.md#instant-loading
|
|
[11]: ../customization.md#additional-javascript
|
|
|
|
### Custom cookies
|
|
|
|
[:octicons-file-code-24: Source][3] ·
|
|
:octicons-mortar-board-24: Difficulty: _moderate_
|
|
|
|
If you've customized the [cookie consent][12] and added a `custom` cookie, the
|
|
user will be prompted to accept your custom cookie. Use
|
|
[additional JavaScript][11] to check whether the user accepted it:
|
|
|
|
``` js
|
|
var consent = __md_get("__consent")
|
|
if (consent && consent.custom) {
|
|
/* The user accepted the cookie */
|
|
}
|
|
```
|
|
|
|
[12]: #cookie-consent
|