Merge pull request #1806 from quarto-dev/algolia-cookie-opt-in

cderv · web-flow · commit f2bcba052ed4 · 2025-10-15T12:02:14.000+02:00
diff --git 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.
diff --git a/docs/websites/website-search.qmd b/docs/websites/website-search.qmd
@@ -167,7 +167,36 @@ 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. Quarto uses a **privacy-first approach** for handling cookies:
+
+- **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.
+
+- **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:
+  cookie-consent: true
+  search:
+    algolia:
+      index-name: <my-index-name>
+      application-id: <my-application-id>
+      search-only-api-key: <my-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-important}
+## Privacy Regulations
+
+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
@@ -321,7 +321,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:
@@ -335,9 +335,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:                                                                                                                                   |
 |              |                                                                                                                                                                                      |
@@ -376,8 +376,16 @@ website:
   google-analytics:
     tracking-id: "G-XXXXXXX"
     anonymize-ip: true
+  search:
+    algolia:
+      index-name: <my-index-name>
+      application-id: <my-application-id>
+      search-only-api-key: <my-search-only-api-key>
+      analytics-events: true
 ```
 
+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
 
 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:
