mirror of
https://github.com/squidfunk/mkdocs-material.git
synced 2024-06-14 11:52:32 +03:00
Updated cookie consent documentation
This commit is contained in:
squidfunk
parent
c843fc7426
commit
0bbcdd45cd
@ -5,12 +5,12 @@ 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. While
|
||||
Material for MkDocs natively integrates with [Google Analytics][1], [other
|
||||
analytics providers][2] can be used, too.
|
||||
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]: #other-analytics-providers
|
||||
[2]: #cookie-consent
|
||||
|
||||
## Configuration
|
||||
|
||||
@ -63,69 +63,122 @@ yourself, [this tutorial][4] might be a good start._
|
||||
### Cookie consent
|
||||
|
||||
[:octicons-file-code-24: Source][5] ·
|
||||
:octicons-beaker-24: Experimental ·
|
||||
:octicons-milestone-24: Default: _none_ ·
|
||||
[:octicons-heart-fill-24:{ .mdx-heart } Insiders only][5]{ .mdx-insiders }
|
||||
|
||||
Material for MkDocs ships a native and extensible cookie consent form, which
|
||||
when enabled will ask the user for his consent prior to sending analytics.
|
||||
Add the following to `mkdocs.yml`:
|
||||
asks the user for his consent prior to setting up analytics. Add the following
|
||||
to `mkdocs.yml`:
|
||||
|
||||
``` yaml
|
||||
extra:
|
||||
consent:
|
||||
title: Cookie consent
|
||||
description: >
|
||||
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:
|
||||
|
||||
[![With tabs][6]][6]
|
||||
[![With tabs][7]][7]
|
||||
|
||||
[5]: ../insiders/index.md
|
||||
[6]: ../assets/screenshots/consent.png
|
||||
|
||||
_Let's get this feature out of the experimental status! You are encouraged to
|
||||
share your feedback in #1914, so we can provide the necessary configuration
|
||||
options for easy customizations. If you wish to customize it today, you can
|
||||
override_ `partials/consent.html`.
|
||||
[6]: #custom-cookies
|
||||
[7]: ../assets/screenshots/consent.png
|
||||
|
||||
## Customization
|
||||
|
||||
### Other analytics providers
|
||||
### Custom site analytics
|
||||
|
||||
[:octicons-file-code-24: Source][3] ·
|
||||
:octicons-mortar-board-24: Difficulty: _easy_
|
||||
:octicons-mortar-board-24: Difficulty: _moderate_
|
||||
|
||||
In order to integrate another analytics service provider offering an
|
||||
asynchronous JavaScript-based tracking solution, you can [extend the theme][7]
|
||||
and [override the `analytics` block][8]:
|
||||
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`:
|
||||
|
||||
``` html
|
||||
{% block analytics %}
|
||||
<!-- Add custom analytics integration here -->
|
||||
{% endblock %}
|
||||
``` yaml
|
||||
extra:
|
||||
analytics:
|
||||
provider: custom # (1)
|
||||
key: value # (2)
|
||||
```
|
||||
|
||||
[7]: ../customization.md#extending-the-theme
|
||||
[8]: ../customization.md#overriding-blocks-recommended
|
||||
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.
|
||||
|
||||
If you're using [instant loading][9], you may use the `location$` observable,
|
||||
[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) {
|
||||
/* Add custom page event tracking here */
|
||||
/* Track a page event */
|
||||
})
|
||||
```
|
||||
|
||||
Note that this must be integrated with [additional JavaScript][10], and cannot be
|
||||
included as part of the `analytics` block, as it is included in the `head` of
|
||||
the document.
|
||||
Note that this must be integrated with [additional JavaScript][11].
|
||||
|
||||
[9]: setting-up-navigation.md#instant-loading
|
||||
[10]: ../customization.md#additional-javascript
|
||||
[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
|
||||
|
||||
Loading…
Reference in New Issue
Block a user