# Cookies & Analytics

## Cookies & Analytics

**Files:** `src/config/config.toml`, `src/content/widgets/english/cookie-consent.md` · **Skill level:** Beginner

### The Cookie Banner
A card at the bottom right with **Accept all**, **Reject all**, and **Customize**. Reject and Accept have the same size and style, so refusing is as easy as accepting. The choice is saved in the visitor's browser. While the search window is open, the card is hidden so it never covers it, and it comes back when search closes.

```toml
[settings.cookieConsent]
  enable   = true   # false removes the banner
  revision = 1      # increase it when your cookie use changes, to ask every visitor again
```

The text and categories are in `src/content/widgets/english/cookie-consent.md` (and `french/`):

```yaml
title: "We use cookies"
description: "Necessary cookies keep this site running. With your permission, ..."
link: { enable: true, label: "Cookie policy", url: "/cookie-policy/" }
acceptLabel: "Accept all"
rejectLabel: "Reject all"
customizeLabel: "Customize"
saveLabel: "Save choices"
categories:
  - id: "necessary"      # always on
    title: "Necessary"
  - id: "analytics"
    title: "Analytics"
  - id: "marketing"
    title: "Marketing"
```

`id` is one of `necessary`, `analytics`, `marketing`. Remove a category you don't use.

### Add Analytics
Analytics and marketing tags go in `[head]` in `config.toml`. With the banner on, **gate each tag on a category** so it only runs after the visitor accepts it:

<Steps>

1. Paste the tag your analytics provider gives you into `[head] content`.
2. Change `<script>` to `<script type="text/plain" data-consent="analytics">` (or `"marketing"`).
3. Keep `src`, `async`, and the other attributes as they are. Inline scripts work the same way.

</Steps>

```toml
[head]
  content = """
  <script type="text/plain" data-consent="analytics" defer src="https://analytics.example.com/script.js" data-site="example.com"></script>
  """
```

- To require several categories: `data-consent="analytics marketing"`.
- For a module script, add `data-type="module"`.
- Gated scripts never run while the banner is off. If you turn the banner off, use plain `<script>` tags, and remove the sentence that links to the "cookie settings" from `cookie-policy.md` (in `src/content/pages/english/` and `french/`).

<Aside type="caution">
  A plain `<script>` in `[head]` runs for every visitor, whatever they choose
  in the banner. Many privacy laws require consent before analytics cookies.
</Aside>

### For Developers
- A `consentchange` event fires on `document` on every page load and after each choice:

  ```js
  document.addEventListener("consentchange", (e) => {
    if (e.detail.analytics) {
      /* load analytics */
    }
  });
  ```

- `window.cookieConsent.get()` returns the saved choice (or `null`), and `window.cookieConsent.open()` reopens the preferences.
- Any link with `data-cookie-settings` or `href="#cookie-settings"` reopens the preferences. The cookie policy page has one ("cookie settings"); add one to the footer menu if you want (`"url": "#cookie-settings"`).

### Cookie Policy
`src/content/pages/english/cookie-policy.md` is a placeholder. Describe the cookies your site really uses, and have it reviewed.

### Do It With AI
```text
Add [Google Analytics 4 with ID G-XXXX | Plausible for my domain | ...] to [head] in
src/config/config.toml, gated on the "analytics" consent category (type="text/plain"
data-consent="analytics"). I don't use marketing cookies: remove that category from
src/content/widgets/english/cookie-consent.md and french/, and update the cookie policy in
src/content/pages/english/cookie-policy.md to match.
```