# Cookies, Analytics & Custom Scripts

## Cookies, Analytics & Custom Scripts

**Files:** `src/config/config.toml`, `src/content/sections/english/cookie-consent.md` · **Skill level:** Beginner (you paste your analytics snippet)

### Add Analytics Or Any Script
Everything in `[head] content` is added to the `<head>` of every page. Paste the snippet your analytics tool gives you (Plausible, Umami, Fathom, Google Analytics, a verification tag, and so on):

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

### The Cookie Banner
Ecozen ships a cookie banner (bottom right on large screens, along the bottom on phones) with **Accept all**, **Reject all**, and **Customize**. Accept and Reject have the same size and style, so refusing is as easy as accepting. Visitors can choose three categories: **Necessary** (always on), **Analytics**, and **Marketing**. Their choice is saved in their browser.

```toml
[settings.cookieConsent]
  enable   = true   # false removes the banner
  revision = 1      # raise by 1 when your cookie use changes, to ask everyone again
```

The banner's text, button labels, categories, and the link to your privacy policy are in `src/content/sections/english/cookie-consent.md` (and the other language folders):

```yaml
title: "We use cookies"
description: "Necessary cookies keep this site working. With your permission, we also use analytics and marketing cookies..."
link:
  enable: true
  label: "Privacy policy"
  url: "/privacy-policy/"
categories:
  - id: "necessary"      # necessary | analytics | marketing
    title: "Necessary"
    description: "Security, form submissions, and your language choice."
```

Ecozen has no separate cookie policy page: the link points to the privacy policy, whose **Cookies** section you should update to match the tools you use.

### Make Scripts Wait For Consent
With the banner on, mark each tracking script with the category it belongs to. It then runs only after the visitor accepts that category:

<Steps>

1. Change `<script` to `<script type="text/plain"`.
2. Add `data-consent="analytics"` (or `"marketing"`).
3. Keep every other attribute (`src`, `defer`, `data-...`) as it is.

</Steps>

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

- Inline scripts work the same way: add the two attributes to the `<script>` tag.
- To require two categories, list both: `data-consent="analytics marketing"`.
- For a module script, also add `data-type="module"`.

<Aside type="caution">
  Scripts marked `type="text/plain"` **never run** when the banner is off. If you
  turn the banner off, change them back to plain `<script>` tags.
</Aside>

<Aside type="tip" title="Do you need the banner?">
  Privacy-friendly analytics such as Plausible, Fathom, or Umami don't use
  cookies, and in many regions don't require a consent banner. If that's all you
  use, you can set `enable = false` and add the script normally. Check the rules
  that apply to your business.
</Aside>

### Reopen The Preferences
Any link with `href="#cookie-settings"` (or the `data-cookie-settings` attribute) reopens the preferences. The footer's **Cookie settings** link in the Legal column does this. If you turn the banner off, set that link's `"enable": false` in `footerPrivacy` of every `src/config/menu.*.json` file.

### For Developers
- `window.cookieConsent.get()` returns the saved choice (or `null`), and `window.cookieConsent.open()` opens the preferences.
- A `consentchange` event fires on `document` after each choice, and on every later page load once a choice is saved:

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

### Do It With AI
```text
Add my analytics to the site: [PASTE SNIPPET]. Put it in [head] content in src/config/config.toml.
The cookie banner is on, so gate it on the "analytics" category: type="text/plain" and
data-consent="analytics", keeping all other attributes. Update the Cookies section of
privacy-policy.md in every language folder of src/content/pages/ to mention [TOOL NAME].
```