From 3dd63ff6a0762390fe2345c69deab7cac135e7dc Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Fri, 10 Oct 2025 14:09:25 +0200 Subject: [PATCH 1/3] document new cookie behavior for algolia See https://github.com/quarto-dev/quarto-cli/pull/13525 --- docs/websites/website-search.qmd | 29 ++++++++++++++++++++++++++++- docs/websites/website-tools.qmd | 10 +++++++++- 2 files changed, 37 insertions(+), 2 deletions(-) diff --git a/docs/websites/website-search.qmd b/docs/websites/website-search.qmd index 97f33c383b..35ae2d8eab 100644 --- a/docs/websites/website-search.qmd +++ b/docs/websites/website-search.qmd @@ -167,7 +167,34 @@ website: analytics-events: true ``` -You can confirm that events are being properly sent to Algolia using the [Event Debugger](https://www.algolia.com/events/debugger). Note that the click and conversion events use cookies to maintain an anonymous user identifier---if [cookie consent](website-tools.qmd#cookie-consent) is enabled, search events will only be enabled if cookie consent has been granted. +You can confirm that events are being properly sent to Algolia using the [Event Debugger](https://www.algolia.com/events/debugger). + +#### Cookie Consent and User Tracking + +Algolia Insights uses user tokens to track click and conversion events. By default, Quarto uses a **privacy-first approach** that does not store cookies: + +- **Default behavior (no cookies)**: A random session token is generated for each browser session. This allows tracking of search interactions during a single visit without storing persistent cookies. This default is compliant with privacy regulations like GDPR. + +- **Persistent tracking (with cookies)**: To track users across multiple sessions, you must enable [cookie consent](website-tools.qmd#cookie-consent). When cookie consent is enabled, Algolia will only use cookies after the user grants "tracking" consent: + +``` yaml +website: + cookie-consent: true + search: + algolia: + index-name: + application-id: + search-only-api-key: + analytics-events: true +``` + +With this configuration, the Algolia Insights API will use cookies to maintain an anonymous user identifier across sessions, but only after the user has explicitly granted consent. + +::: {.callout-note} +## Privacy and Compliance + +The default session-only tracking provides meaningful analytics about search usage patterns while respecting user privacy. Enabling persistent cookie tracking may require compliance with privacy regulations in your jurisdiction, which is why Quarto requires explicit configuration of cookie consent. +::: ### Advanced Configuration diff --git a/docs/websites/website-tools.qmd b/docs/websites/website-tools.qmd index c2fcaa2bee..c4c4dfd773 100644 --- a/docs/websites/website-tools.qmd +++ b/docs/websites/website-tools.qmd @@ -258,7 +258,7 @@ If you choose `none` for storage, this will have the following effects: Quarto includes the ability to request cookie consent before enabling scripts that set cookies, using [Cookie Consent](https://www.cookieconsent.com). -The user's cookie preferences will automatically control [Google Analytics] (if enabled) and can be used to control custom scripts you add as well (see [Custom Scripts and Cookie Consent]). You can enable the default request for cookie consent using the following: +The user's cookie preferences will automatically control [Google Analytics] and [Algolia search analytics](/docs/websites/website-search.qmd#algolia-insights) (if enabled) and can be used to control custom scripts you add as well (see [Custom Scripts and Cookie Consent]). You can enable the default request for cookie consent using the following: ``` yaml website: @@ -313,8 +313,16 @@ website: google-analytics: tracking-id: "G-XXXXXXX" anonymize-ip: true + search: + algolia: + index-name: + application-id: + search-only-api-key: + analytics-events: true ``` +Note that with cookie consent enabled, both Google Analytics and Algolia search analytics will only use cookies after the user has granted "tracking" consent. Without cookie consent enabled, Algolia will use session-only tracking without cookies. See [Algolia Insights](/docs/websites/website-search.qmd#algolia-insights) for more details. + ### Cookie Preferences In addition to requesting consent when a new user visits your website, Cookie Consent will also add a cookie preferences link to the footer of the website. You can control the text of this link using `prefs-text`. If you would rather position this link yourself, just add a link with the id `#open_preferences_center` to the website and Cookie Consent will not add the preferences link to the footer. For example: From 91abd33c3a2c423f124e91d2d32db7c1d5eb3dd3 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Tue, 14 Oct 2025 17:38:01 +0200 Subject: [PATCH 2/3] Adapt our docs to 'type: express' being the default for cookie consent now --- docs/prerelease/1.9/_highlights.qmd | 2 ++ docs/websites/website-search.qmd | 14 ++++++++------ docs/websites/website-tools.qmd | 6 +++--- 3 files changed, 13 insertions(+), 9 deletions(-) diff --git a/docs/prerelease/1.9/_highlights.qmd b/docs/prerelease/1.9/_highlights.qmd index b099f0a68d..763f977ecd 100644 --- a/docs/prerelease/1.9/_highlights.qmd +++ b/docs/prerelease/1.9/_highlights.qmd @@ -1,3 +1,5 @@ Quarto 1.9 includes the following new features: +- [Privacy-first cookie consent](/docs/websites/website-tools.qmd#cookie-consent): The default for cookie consent has changed to `type: express`, providing opt-in consent that blocks cookies until users explicitly agree. This privacy-conscious default is designed with modern privacy regulations in mind. + - [`aria-label` for videos](/docs/authoring/videos.qmd#accessibility-label): Improve accessibility of embedded videos by providing custom descriptive labels for screen readers instead of the default "Video Player" label. \ No newline at end of file diff --git a/docs/websites/website-search.qmd b/docs/websites/website-search.qmd index 35ae2d8eab..dcf91846dd 100644 --- a/docs/websites/website-search.qmd +++ b/docs/websites/website-search.qmd @@ -171,11 +171,11 @@ You can confirm that events are being properly sent to Algolia using the [Event #### Cookie Consent and User Tracking -Algolia Insights uses user tokens to track click and conversion events. By default, Quarto uses a **privacy-first approach** that does not store cookies: +Algolia Insights uses user tokens to track click and conversion events. Quarto uses a **privacy-first approach** for handling cookies: -- **Default behavior (no cookies)**: A random session token is generated for each browser session. This allows tracking of search interactions during a single visit without storing persistent cookies. This default is compliant with privacy regulations like GDPR. +- **Without cookie consent enabled**: A random session token is generated for each browser session. This allows tracking of search interactions during a single visit without storing persistent cookies. This privacy-first approach avoids persistent cookies entirely. -- **Persistent tracking (with cookies)**: To track users across multiple sessions, you must enable [cookie consent](website-tools.qmd#cookie-consent). When cookie consent is enabled, Algolia will only use cookies after the user grants "tracking" consent: +- **With cookie consent enabled**: When you enable [cookie consent](website-tools.qmd#cookie-consent), cookies are blocked by default until the user expressly grants consent. After the user grants "tracking" consent, Algolia will use cookies to maintain an anonymous user identifier across sessions: ``` yaml website: @@ -190,10 +190,12 @@ website: With this configuration, the Algolia Insights API will use cookies to maintain an anonymous user identifier across sessions, but only after the user has explicitly granted consent. -::: {.callout-note} -## Privacy and Compliance +::: {.callout-important} +## Privacy Regulations -The default session-only tracking provides meaningful analytics about search usage patterns while respecting user privacy. Enabling persistent cookie tracking may require compliance with privacy regulations in your jurisdiction, which is why Quarto requires explicit configuration of cookie consent. +The default session-only tracking (without cookie consent) provides meaningful analytics about search usage patterns without using persistent cookies. When cookie consent is enabled, Quarto uses an opt-in approach (express consent) by default, blocking cookies until the user explicitly agrees. + +While these features are designed with privacy regulations in mind, website owners should consult with legal counsel to ensure their specific implementation meets applicable privacy laws and regulations in their jurisdiction. ::: ### Advanced Configuration diff --git a/docs/websites/website-tools.qmd b/docs/websites/website-tools.qmd index c4c4dfd773..eac9e8f6c7 100644 --- a/docs/websites/website-tools.qmd +++ b/docs/websites/website-tools.qmd @@ -272,9 +272,9 @@ You can further customize the appearance and behavior of the consent using the f +==============+======================================================================================================================================================================================+ | `type` | The type of consent that should be requested, using one of these two values: | | | | -| | **implied -** (default) This will notify the user that the site uses cookies and permit them to change preferences, but not block cookies unless the user changes their preferences. | +| | **express -** (default) This will block cookies until the user expressly agrees to allow them (or continue blocking them if the user doesn't agree). | | | | -| | **express -** This will block cookies until the user expressly agrees to allow them (or continue blocking them if the user doesn't agree). | +| | **implied -** This will notify the user that the site uses cookies and permit them to change preferences, but not block cookies unless the user changes their preferences. | +--------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | `style` | The style of the consent banner that is displayed: | | | | @@ -321,7 +321,7 @@ website: analytics-events: true ``` -Note that with cookie consent enabled, both Google Analytics and Algolia search analytics will only use cookies after the user has granted "tracking" consent. Without cookie consent enabled, Algolia will use session-only tracking without cookies. See [Algolia Insights](/docs/websites/website-search.qmd#algolia-insights) for more details. +Note that with cookie consent enabled (which uses opt-in "express" consent by default), both Google Analytics and Algolia search analytics will only use cookies after the user has granted "tracking" consent. Without cookie consent enabled, Algolia will use session-only tracking without cookies. See [Algolia Insights](/docs/websites/website-search.qmd#algolia-insights) for more details. ### Cookie Preferences From c98f9e121122549729f56e992f5ebd025529c426 Mon Sep 17 00:00:00 2001 From: Christophe Dervieux Date: Wed, 15 Oct 2025 12:01:56 +0200 Subject: [PATCH 3/3] Update docs/websites/website-tools.qmd Co-authored-by: Charlotte Wickham --- docs/websites/website-tools.qmd | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/websites/website-tools.qmd b/docs/websites/website-tools.qmd index eac9e8f6c7..a45f6379db 100644 --- a/docs/websites/website-tools.qmd +++ b/docs/websites/website-tools.qmd @@ -321,7 +321,7 @@ website: analytics-events: true ``` -Note that with cookie consent enabled (which uses opt-in "express" consent by default), both Google Analytics and Algolia search analytics will only use cookies after the user has granted "tracking" consent. Without cookie consent enabled, Algolia will use session-only tracking without cookies. See [Algolia Insights](/docs/websites/website-search.qmd#algolia-insights) for more details. +When cookie consent is enabled, Google Analytics and Algolia search analytics will use cookies based on user preference: for `type: express`, the default, they will not use cookies unless a user opts-in; for `type: implied`, they will use cookies unless a user opts-out. Without cookie consent enabled, Algolia will use session-only tracking without cookies. See [Algolia Insights](/docs/websites/website-search.qmd#algolia-insights) for more details. ### Cookie Preferences