# Cookies, Analytics & Custom Scripts

## Cookies, Analytics & Custom Scripts

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

Margo itself sets no cookies and ships no analytics. It only keeps a few of the visitor's own choices in their browser, such as light or dark mode and the answer to the cookie banner. A consent banner matters once **you** add analytics or ad tags, and Margo's banner holds those tags back until the visitor agrees.

### The Cookie Banner
The banner is a card in the bottom-right corner on larger screens, and across 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. **Customize** lists three categories: **Necessary** (always on), **Analytics**, and **Marketing**. The choice is saved in the visitor's browser (`localStorage`, key `cookie-consent`).

```toml
# src/config/config.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 the same file in `french/` and `arabic/`):

```yaml
title: "Cookies on this site"
description: "Necessary cookies keep the site working. With your consent, analytics and marketing cookies show which pages people read and where visits come from."
link:
  enable: true
  label: "Cookie policy"
  url: "/cookie-policy/"
acceptLabel: "Accept all"
rejectLabel: "Reject all"
customizeLabel: "Customize"
saveLabel: "Save choices"
preferencesLabel: "Cookie preferences" # name of the category list for screen readers
requiredLabel: "Always on"             # shown next to the necessary category
categories:
  - id: "necessary" # necessary | analytics | marketing
    title: "Necessary"
    description: "Page loading, forms, and your language and theme choices."
```

Keep each category's `id` as `necessary`, `analytics`, or `marketing`; change the titles and descriptions freely. The link points to `/cookie-policy/` (`src/content/pages/english/cookie-policy.mdx`), 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, Margo stores only the visitor's own choices, 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 site verification tag, and so on). It ships with an empty `<script></script>`, which you can replace:

```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 **Cookie settings** item in the **Legal** column of the footer menu does this. If you turn the banner off, set that item's `"enable"` to `false` in each `src/config/menu.<language>.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`.

### 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 cookie-policy.mdx in
src/content/pages/english/, french/, and arabic/ to name [TOOL NAME] and what it stores.
```