What to put in for custom cookie

[ydkmlt84]

I have searched and just can't seem to find it. What do I put in for the custom cookie? I am not using Google analytics, using Matomo, and don't really understand what to put in mkdocs.yml

analytics:
    provider: matomo
    property: docs
  consent:
    title: Cookie consent
    description: >- 
      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.
    actions:
      - accept
      - reject
      - manage
    cookies:
      analytics: matomo
      custom: WHAT GOES HERE, FOR ME?

Do I put the name of the cookie that my analytics provider uses?

Do I put the names from the table in this documentation? https://matomo.org/faq/general/faq_146/#:~:text=with%20privacy%20requirements.-,Default%20Cookies,-To%20track%20users

If so...do I use one custom:entry per cookie, or can I list them like this:

custom:
  - one_cookie
  - two_cookie
  - three_cookie

Thanks in advance for the help! Right now, my cookies aren't being removed when the consent is rejected, and I am assuming this is why.

[squidfunk]

It's basically just an identifier, specifically custom that you can query in JavaScript to do whatever you want with it, as mentioned. For instance, you can call it banana:

analytics:
    ...
    cookies:
      banana: some_value

And then:

var consent = __md_get("__consent")
if (consent && consent.banana) {
   consent.banana // will contain "some_value"
} else {
   // No cookie for you
}

[ydkmlt84]

Thank you. For some_value, is that where I put in the cookie name, that I get from the provider? Or do I not need to do that at all? How will it know which cookie to delete if the user rejects it? Sorry, this is new territory. I assume the accept or reject is just for the browser, and the analytics provider only cares if the cookie is there or not, not necessarily if they accepted it or rejected it?

[squidfunk]

Generally, our implementation is only a cookie consent – it does not include any setting or unsetting of cookies. For instance, our Google Analytics integration will only load if the consent is accepted, but it will not delete the cookie. Whether a cookie can be deleted from the browser depends on the nature of the cookie, which is not generalizable. For instance, secure, HTTPS-only cookies can never be deleted from the client (AFAIK). Thus, we can't generalize deletion.

Thus, if you integrate a custom cookie, you need to provide the logic to delete the cookie in your customization:

var consent = __md_get("__consent")
if (consent && consent.analytics) {
   consent.banana // will contain "some_value"
} else {
   // Delete cookie here
}

I assume the accept or reject is just for the browser, and the analytics provider only cares if the cookie is there or not, not necessarily if they accepted it or rejected it?

Correct, which is why you should write the custom partial in a way that will only trigger the inclusion of the script if the cookie was accepted, as we've done for our Google Analytics integration:

mkdocs-material/src/templates/partials/integrations/analytics.html

Lines 33 to 40 in 0b327bc

	{% if config.extra.consent %}
	<script>
	if (typeof __md_analytics !== "undefined") {
	var consent = __md_get("__consent")
	if (consent && consent.analytics)
	__md_analytics()
	}
	</script>

... and then conditionally:

mkdocs-material/src/templates/partials/integrations/analytics/google.html

Lines 88 to 95 in 0b327bc

	/* 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)

[ydkmlt84]

Perfect! Thanks for the information!