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!

[ydkmlt84]

It took me a while to get everything figured out. For anyone else coming here, I will try to outline what I did.

In my overrides/partials/integrations folder I have an analytics.html file and an analytics folder with the matomo.html tracking code.

matomo.html code:

<!-- Matomo Tag Manager -->

<script id="__analytics">
  function __md_analytics() {
    var _mtm = window._mtm = window._mtm || [];
    _mtm.push({'mtm.startTime': (new Date().getTime()), 'event': 'mtm.Start'});
    var d = document, g = d.createElement('script'), s = d.getElementsByTagName('script')[0];
    g.async = true; 
    g.src = 'https://analytics.mydomain.com/js/container_xxxxxx'; 
    s.parentNode.insertBefore(g, s);

  /* Set up feedback, i.e. "Was this page helpful?" */
    document.addEventListener("DOMContentLoaded", function() {
      document$.subscribe(function() {
        var feedback = document.forms.feedback
        if (typeof feedback === 'undefined') return

        /* Send feedback to Analytics */
        for (var button of feedback.querySelectorAll('[type=submit]')) {
          button.addEventListener('click', function (ev) {
            ev.preventDefault()

          /* Retrieve and send data */
          var page = document.location.pathname
          var data = this.getAttribute("data-md-value")
          console.log(page, data)
          window._paq.push(['trackEvent','Ratings','Feedback_Provided',page,data])

          /* Disable form and show note, if given */
          feedback.firstElementChild.disabled = true
          var note = feedback.querySelector(
            ".md-feedback__note [data-md-value='" + data + "']"
          )
          if (note) note.hidden = false
        })

        /* Show feedback */
        feedback.hidden = false
        }
      })
  })  
}
</script>
<!-- End Matomo Tag Manager -->

This implements the tracking as well as code for the feedback widget.

analytics.html code checks for consent before adding the matomo code:

<!-- Determine analytics provider -->
{% if config.extra.analytics %}
  {% set provider = config.extra.analytics.provider %}
{% endif %}

<!-- Set up analytics provider -->
{% if provider %}
  {% include "partials/integrations/analytics/" ~ provider ~ ".html" %}

  {% if config.extra.consent %}
  <script>
    // Initialize Matomo's _paq array
    window._paq = window._paq || [];
    window._paq.push(['requireCookieConsent']);
    
    // Check initial consent and load analytics
    var consent = __md_get("__consent");

    if (consent && consent.analytics) {
      console.log(`We have analytics liftoff. Value of consent, ${consent.analytics}`);
      window._paq.push(['rememberCookieConsentGiven']); // Remember consent
      __md_analytics(); // Load Matomo if consent is given
    }
     else if (!consent) { // Load consent popup
      console.log('It looks like you have not explicitly consented to analytics. Let us fix that.')
      window.location.href = "#__consent";
    }
     else if (consent && !consent.analytics) {
      console.log(`The launch of our analytics rocket is postponed. Value of consent, ${consent.analytics}`)
    }

    // Monitor local storage for changes in consent
    window.addEventListener("storage", function (event) {
      if (event.key === "__consent") {
        var updatedConsent = __md_get("__consent");

        if (updatedConsent && updatedConsent.analytics) {
          // Consent granted
          window._paq.push(['rememberCookieConsentGiven']);
          __md_analytics();
          __md_feedback();
        } else {
          // Consent revoked or not set
          window._paq.push(['forgetCookieConsentGiven']);
          console.log(`Analytics consent revoked. Consent value = ${updatedConsent.analytics}. Analytics disabled.`);
        }
      }
    });
  </script>
  {% endif %}
{% endif %}

my mkdocs.yml extra/analytics code:

analytics:
    provider: matomo
    property: docs
    feedback:
      title: Was this page helpful?
      ratings:
        - icon: fontawesome/solid/thumbs-up
          name: This page was helpful
          data: 1
          note: >-
            Thanks for your feedback!

        - icon: fontawesome/solid/thumbs-down
          name: This page could be improved
          data: 0
          note: >-
            Thanks for your feedback! Help us improve this page by
            submitting an issue to the docs repo.
    consent:
      title: Help us, help you! (consent to cookies)
      description: >-
        We use cookies to recognize your repeated visits and preferences, as well
        as to measure the effectiveness of our documentation. With your consent, you're helping us to
        make our documentation better. <a href="https://maintainerr.info/privacy.html" target="_blank">Privacy Policy</a>
      cookies:
        analytics: Maintainerr's self-hosted analytics system (Matomo).
      actions:
        - accept
        - reject

I didn't use any extra_javascripts to achieve this. I didn't end up using a "custom" cookie as I used the analytics one that would normally be used, and overriding the analytics.html file that normally has google analytics code in it.

Hopefully this helps someone in the future. If not, it is documented for me now :)