# 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)

Homio itself sets no tracking cookies. It only keeps a few necessary things in the visitor's browser: the light or dark choice, a closed announcement bar, and a booking request that wasn't sent yet. A consent banner matters once **you** add analytics or ad tags, and Homio's banner holds those tags back until the visitor agrees.

### The Cookie Banner
The banner is a card in the bottom-right corner (above the call bar on phones) with **Accept all**, **Reject all**, and **Choose**. Accept and Reject have the same size and style, so refusing is as easy as accepting. **Choose** lists three categories: **Necessary** (always on), **Analytics**, and **Marketing**. The choice is saved in the visitor's browser (`localStorage`, key `cookie-consent`).

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

The banner's text, button labels, categories, and link are in `src/content/sections/english/cookie-consent.md` (and `french/`):

```yaml
title: "Cookies on this site"
description: "We use necessary storage to run the site. With your OK, we also measure visits and ad results."
link:
  enable: true
  label: "Cookie policy"
  url: "/cookie-policy/"
acceptLabel: "Accept all"
rejectLabel: "Reject all"
customizeLabel: "Choose"
saveLabel: "Save choices"
categories:
  - id: "necessary"   # necessary | analytics | marketing
    title: "Necessary"
    description: "Your language and light/dark choice, a closed announcement, and a booking you haven't sent yet."
```

The `id` of each category must stay `necessary`, `analytics`, or `marketing`; change the titles and descriptions freely. The link points to `/cookie-policy/` (`src/content/pages/english/cookie-policy.md`), a placeholder text you must adapt to the tools you use.

<Aside type="tip" title="Do you need the banner?">
  Without analytics or ad tags, Homio stores only necessary data, and you can
  set `enable = false`. Some privacy-friendly analytics tools don't use cookies
  either. Check the rules that apply to your business and region.
</Aside>

### 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 (Google Analytics, Plausible, Fathom, a Meta pixel, a site verification tag, and so on):

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

### Make Scripts Wait For Consent
With the banner on, mark each tracking script with its category. It then runs only after the visitor accepts that category, on that page and every page after:

<Steps>

1. Change `<script` to `<script type="text/plain"`.
2. Add `data-consent="analytics"` (or `"marketing"` for ad and conversion tags).
3. Keep every other attribute (`src`, `async`, `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** while the banner is off. If you
  turn the banner off, change them back to plain `<script>` tags.
</Aside>

### Reopen The Preferences
Any link with `href="#cookie-settings"` (or a `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"` to `false` in `src/config/menu.en.json` and `menu.fr.json`.

### For Developers
- `window.cookieConsent.get()` returns the saved choice (or `null`), and `window.cookieConsent.open()` reopens the preferences.
- A `consentchange` event fires on `document` on every page load and after each choice, with `{ necessary, analytics, marketing }` in `detail`:

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

The banner's code is `src/layouts/components/widgets/CookieConsent.astro`, and its styles are `.cookie-consent` in `src/styles/components.css`.

### 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. Then update
src/content/pages/english/cookie-policy.md (and french/) to name [TOOL NAME] and what it stores.
```