====== Cookie Consent ======

:!: Available starting with VuFind 9.0.

The cookie consent prompt and settings allow the user to be informed about cookies used by the service and manage consent for non-essential cookies. 

===== Configuration =====

The configuration for enabling cookie consent is in the Cookies section of config.ini. It contains the settings to turn on cookie consent and select the categories to display and allow toggling in the cookie settings dialog. 

Cookie categories and further configuration is in CookieConsent.yaml. See the comments in the file and the sample configurations below for further information.

Note that if enabled categories or cookies in the categories are changed, the **consentRevision setting in config.ini must be incremented**. This makes VuFind re-request consent and ensures that invalid categories do not remain in the consent cookie. There is also ''popup_revision_message_html'' translation string that allows you to add a message for those that have previously consented but are now prompted again because of the new revision.

Default translation texts include a link to the [[configuration:user_privacy#privacy_policy|Privacy Policy]] page that also displays the current cookie consent. Please ensure that the page contains correct information.
 
===== Language Translations =====

Most text strings used in the cookie consent component have translations in the CookieConsent [[development:architecture:localization#text_domains|text domain]].

===== Information for Developers =====

==== Checking for Consent ====

You can check for user's consent in phtml templates:
<code php>
<?php if ($this->cookieConsent()->isEnabled():?>
  <?php if ($this->cookieConsent()->isCategoryAccepted('essential')):?>
    Essential category is accepted (as it should be)!
  <?php endif; ?>
  <?php if ($this->cookieConsent()->isServiceAllowed('matomo')):?>
    Matomo service is allowed!
  <?php endif; ?>
<?php endif; ?>
</code>

You can also check consent in JavaScript:
<code javascript>
if (VuFind.cookie.isCategoryAccepted('essential')) { ... }
if (VuFind.cookie.isServiceAllowed('matomo')) { ... }
</code>

==== JavaScript Events ====

The following events are emitted:

^ Event                       ^ Description                                    ^
| vf-cookie-consent-first-done   | User has given first consent                   |
| vf-cookie-consent-done         | User has given consent or the page has been loaded with a stored consent |
| vf-cookie-consent-changed      | User has changed their consent                 |
| vf-cookie-consent-initialized  | Cookie consent service has been initialized    |

===== Sample Configurations =====

VuFind comes with cookie consent category configuration for the built-in cookies and Matomo. The following sample configurations can be added to CookieConsent.yaml (typically in local/config/vufind directory) for additional services. The samples only include the relevant parts for the service, so merge them with the full configuration as required.

Since these are third-party services, you will need to verify that the sample configurations are up to date and suitable for the region. 

Note that the sample configuration have all the texts in English. The texts can be replaced with translation strings for multi-language support.

==== YouTube ====

:!: At least expiration times may differ depending on region.

The following template and configuration allow you to display videos based on user consent. If the user has allowed the cookies for the category, videos are displayed. If not, the user gets a message and a link instead.

Template example:
<code php>
<?php $cookieConsent = $this->plugin('cookieConsent'); ?>
<?php if (!$cookieConsent->isEnabled() || $cookieConsent->isCategoryAccepted('video')): ?>
  <iframe width="560" height="315" src="https://www.youtube.com/embed/5q70TokaSrw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
<?php else: ?>
  <div class="alert alert-warning">
    <p>
      The video cannot be displayed due to missing cookie consent.
      Check <a href="#" type="button" data-cc="show-preferencesModal" aria-haspopup="dialog">Cookie Settings</a> to make changes.
    </p>
    <p>
      You can also view the video on <a href="https://www.youtube.com/watch?v=5q70TokaSrw" target="_blank">YouTube</a> (external link).
    </p>
  </div>
<?php endif; ?>
</code>

CookieConsent.yaml:
<code yaml>
CookieConsent:
  Categories:
    video:
      Title: Cookies for embedded video
      Description: Cookies set by video platforms when you view embedded media.
      DefaultEnabled: false
      Essential: false
      Cookies:
        - Name: yt-player-bandwidth
          Domain: youtube.com
          ThirdParty: true
          Description: Used to estimate bandwidth.
          Expiration: session
        - Name: yt-player-headers-readable
          Domain: youtube.com
          ThirdParty: true
          Description: Used to store user's preferences.
          Expiration: session
        - Name: GPS
          Domain: youtube.com
          ThirdParty: true
          Description: Used to store user's location.
          Expiration: session
        - Name: VISITOR_INFO1_LIVE
          Domain: youtube.com
          ThirdParty: true
          Description: Used to estimate bandwidth.
          Expiration: 6
          ExpirationUnit: months
        - Name: PREF, __Secure-YEC
          Domain: youtube.com
          ThirdParty: true
          Description: Used to store user's preferences.
          Expiration: 8
          ExpirationUnit: months
        - Name: YSC, CONSENT, SOCS
          Domain: youtube.com
          ThirdParty: true
          Description: Used to track user's actions for marketing purposes.
          Expiration: 8
          ExpirationUnit: months
      AutoClearCookies:
        - Name: '/^(yt-player-.*|GPS|VISITOR_INFO1_LIVE|PREF|__Secure-YEC|YSC|CONSENT|SOCS)$/'
</code>