@escape-game-over/atlas 0.1.36 → 0.1.38

package/docs/client-scripts.md

@@ -46,8 +46,12 @@ finding them.
 analytics={…}>` (`@escape-game-over/atlas/astro/consent-banner`) renders the
 site's markup as its children, skips itself — script included — when the
 analytics need no permission, and remembers, expires and applies the answer. The
-markup marks its buttons `data-consent="grant"` and `data-consent="deny"`,
-and the control that brings it back `data-consent-reopen hidden`.
+answer is two, one per category: `analytics` (Google's `analytics_storage`) and
+`marketing` (the three `ad_*` signals, and any other ad network's tag). The
+markup marks its buttons `data-consent="grant"` and `data-consent="deny"` for
+everything at once, and `data-consent="save"` for the answer its checkboxes
+give — `data-consent-category="analytics"` and `"marketing"`, never ticked by
+default. The control that brings it back is `data-consent-reopen hidden`.
 
 `Document` ships one more: scroll restoration, on unless `restoreScroll={false}`.
 WebKit restores a page's position only at `load`, after every image, so a page
@@ -562,7 +566,8 @@ right properties is a faithful stand-in.
 - `tests/element.test.ts` stubs `customElements` to upgrade on `define`, as a
   browser does, and pins what `connect` is handed.
 - `tests/consent.test.ts` fakes `localStorage`, with a switch that makes it
-  throw, and the Google hook, and pins the six-month expiry to the day.
+  throw, and the Google hook, and pins the six-month expiry to the day and
+  that an answer missing a category is asked again.
 
 `carousel` has none, nor does the consent banner's element, and `element` has
 no lifecycle test — moves and teardown. They need a real DOM and

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@escape-game-over/atlas",
-    "version": "0.1.36",
+    "version": "0.1.38",
     "type": "module",
     "description": "Typed, data-driven machinery for static multi-locale, multi-deployment Astro sites.",
     "private": false,

package/src/analytics/consent-storage.ts

@@ -0,0 +1,52 @@
+/**
+ * What a visitor's consent answer is, where it is kept, and for how long it
+ * counts.
+ *
+ * Shared by the two halves that read it: the banner's module script
+ * (`astro/consent.ts`), and the inline head block Google's tags emit, which
+ * restores an answer before any tag fires. Two readers with their own copies of
+ * the key, the expiry or the categories would disagree the first time either
+ * changed.
+ */
+
+/** Granted or denied — the only two answers Consent Mode has. */
+export type ConsentChoice = "granted" | "denied";
+
+/**
+ * What a visitor is asked about, each answered on its own.
+ *
+ * - `analytics` — measuring how the site is used. Google's `analytics_storage`.
+ * - `marketing` — advertising: measuring ad conversions and remarketing. Google's
+ *   `ad_storage`, `ad_user_data` and `ad_personalization`, and any other ad
+ *   network's tag a site adds.
+ *
+ * Two, because the GDPR wants a choice per purpose: a yes to analytics that also
+ * granted advertising would not have asked about advertising at all.
+ */
+export type ConsentCategory = "analytics" | "marketing";
+
+export const CONSENT_CATEGORIES: readonly ConsentCategory[] = [
+    "analytics",
+    "marketing",
+];
+
+/** One answer per category. */
+export type ConsentChoices = Readonly<Record<ConsentCategory, ConsentChoice>>;
+
+/**
+ * How long an answer stands before the question is asked again.
+ *
+ * Consent is not forever and regulators say so: France's CNIL puts the outside
+ * limit at 13 months and recommends six, and the EDPB's position is that a
+ * choice made long enough ago is no longer informed. Six is the conservative
+ * reading, and the reason the record carries a date at all — without one there
+ * is no way to expire it, and no way to answer "when did this visitor agree?",
+ * which is a question only ever asked when somebody is already unhappy.
+ */
+export const CONSENT_MONTHS = 6;
+
+/**
+ * The `localStorage` key the answer is kept under. Prefixed to keep clear of the
+ * bare `"consent"` a third-party widget would reach for.
+ */
+export const CONSENT_KEY = "atlas-consent";

package/src/analytics/google.ts

@@ -1,5 +1,11 @@
 import type { NonEmpty } from "../types.ts";
 import { warn } from "../warn.ts";
+import {
+    CONSENT_CATEGORIES,
+    CONSENT_KEY,
+    CONSENT_MONTHS,
+    type ConsentCategory,
+} from "./consent-storage.ts";
 import { type AnalyticsTags, literal, preconnect } from "./tags.ts";
 
 /**
@@ -131,6 +137,17 @@ export interface GoogleSettings {
      * unstated case emits.
      */
     readonly consent?: NonEmpty<ConsentDefaults>;
+    /**
+     * Carries an ad click's id (`gclid`, `gbraid`, `wbraid`) from page to page
+     * in the URL while `ad_storage` is denied. **Off unless stated.**
+     *
+     * Denied, the Google tag cannot keep the click id in a cookie, so a visitor
+     * who lands on one page and converts on another loses it on the way. For a
+     * site running Google Ads — where that id is what ties a lead back to the
+     * click — this keeps it on the internal links they follow. A site without
+     * ads has no click id to carry.
+     */
+    readonly urlPassthrough?: true;
 }
 
 /**
@@ -180,7 +197,8 @@ const CONSENT_KEYS = {
 } as const satisfies Readonly<Record<keyof ConsentDefaults, string>>;
 
 /**
- * The global a consent banner calls to change its mind: `__consent('granted')`.
+ * The global a consent banner calls to change its mind:
+ * `__consent({ analytics: "granted", marketing: "denied" })`.
  *
  * Emitted by lib rather than written in each project, because the *signals* it
  * updates must be exactly the ones lib defaulted. A banner that built the
@@ -209,19 +227,68 @@ const SIGNAL_KEYS = [
 ] as const satisfies readonly (keyof ConsentDefaults)[];
 
 /**
- * `window.__consent(state)`, updating precisely what was defaulted.
+ * Which signals each answer moves.
+ *
+ * `functionality`, `personalization` and `security` are in neither: they are
+ * the site working, not something a visitor is asked about. A deployment that
+ * defaults one of them to denied is warned, since no answer can grant it back.
+ */
+const CATEGORY_SIGNALS: Readonly<
+    Record<ConsentCategory, readonly (keyof ConsentDefaults)[]>
+> = {
+    analytics: ["analyticsStorage"],
+    marketing: ["adStorage", "adUserData", "adPersonalization"],
+};
+
+/** The signals no answer grants — see `CATEGORY_SIGNALS`. */
+const UNASKED = SIGNAL_KEYS.filter(
+    (key) =>
+        !CONSENT_CATEGORIES.some((category) =>
+            CATEGORY_SIGNALS[category].includes(key)
+        )
+);
+
+/**
+ * `window.__consent(choices)`, updating precisely what was defaulted, each
+ * signal from the answer for its category.
  *
- * Every signal any default mentioned, and nothing else. Updating one that was
- * never defaulted is legal and pointless — Google reads it as a change from its
- * own implicit grant, which was never in force here.
+ * Only signals a default mentioned. Updating one that was never defaulted is
+ * legal and pointless — Google reads it as a change from its own implicit
+ * grant, which was never in force here.
  */
 function consentUpdater(defaults: readonly ConsentDefaults[]): string {
-    const signals = SIGNAL_KEYS.filter((key) =>
-        defaults.some((given) => given[key] !== undefined)
-    ).map((key) => `${literal(CONSENT_KEYS[key])}:s`);
+    const signals = CONSENT_CATEGORIES.flatMap((category) =>
+        CATEGORY_SIGNALS[category]
+            .filter((key) => defaults.some((given) => given[key] !== undefined))
+            .map((key) => `${literal(CONSENT_KEYS[key])}:c.${category}`)
+    );
 
     if (signals.length === 0) return "";
-    return `window.${CONSENT_UPDATE_GLOBAL}=function(s){gtag('consent','update',{${signals.join(",")}})};`;
+    return `window.${CONSENT_UPDATE_GLOBAL}=function(c){gtag('consent','update',{${signals.join(",")}})};`;
+}
+
+/**
+ * A returning visitor's answer, handed to Google before any tag fires.
+ *
+ * It has to happen here, in the head, ahead of `gtag('config', …)`. Left to the
+ * banner's module script it arrives after `gtag.js` has already sent the page
+ * view on the defaults — so every page a consenting visitor opened was recorded
+ * as denied: no cookie, no returning user, no session. Measured, not supposed:
+ * `gcs=G100` on the `page_view`, `G111` only on the hits after it.
+ *
+ * The same key, expiry and categories `astro/consent.ts` reads, from the one
+ * place both take them. Anything unreadable, expired, absent or missing a
+ * category — an answer given before that category was asked — leaves the
+ * defaults standing, and the banner will ask.
+ */
+function restoredConsent(): string {
+    const answered = CONSENT_CATEGORIES.map(
+        (category) => `(c.${category}==="granted"||c.${category}==="denied")`
+    ).join("&&");
+    const choices = CONSENT_CATEGORIES.map(
+        (category) => `${category}:c.${category}`
+    ).join(",");
+    return `try{var c=JSON.parse(localStorage.getItem(${literal(CONSENT_KEY)})),e=new Date(c.at);e.setMonth(e.getMonth()+${CONSENT_MONTHS});if(${answered}&&e>new Date())window.${CONSENT_UPDATE_GLOBAL}({${choices}})}catch(_){}`;
 }
 
 /** One `gtag('consent','default',{…})` per stated default, in order. */
@@ -333,13 +400,28 @@ export function googleScripts(
     }
 
     const consent = google.consent ?? DENIED_BY_DEFAULT;
+    for (const key of UNASKED) {
+        if (consent.some((given) => given[key] === "denied")) {
+            warn(
+                at,
+                `consent defaults ${CONSENT_KEYS[key]} to denied, and no answer a visitor gives grants it — it is neither analytics nor marketing. Leave it to Google's default unless it is meant to stay denied.`
+            );
+        }
+    }
+    // The way back out of the defaults, covering what they denied.
+    const updater = consentUpdater(consent);
     const inline = [
         "window.dataLayer=window.dataLayer||[];",
         "function gtag(){dataLayer.push(arguments)}",
         // Ahead of everything, which is the entire point of emitting this here.
         consentCalls(consent),
-        // And the way back out of it, covering exactly what was just denied.
-        consentUpdater(consent),
+        updater,
+        // Then a remembered answer, still ahead of the first tag.
+        updater === "" ? "" : restoredConsent(),
+        // Before any `config`, which is what reads it.
+        google.urlPassthrough === true
+            ? "gtag('set','url_passthrough',true);"
+            : "",
         tags.length > 0 ? "gtag('js',new Date());" : "",
         ...tags.map((id) => `gtag('config',${literal(id)});`),
         // Tag Manager's own loader, once per container. It appends its script

package/src/astro/consent-element.ts

@@ -1,44 +1,87 @@
+import { CONSENT_CATEGORIES } from "../analytics/consent-storage.ts";
 import {
-    applyConsent,
-    type ConsentChoice,
+    type ConsentCategory,
+    type ConsentChoices,
+    everyCategory,
     readConsent,
     recordConsent,
 } from "./consent.ts";
 import { element } from "./element.ts";
 import { data, refs } from "./ref.ts";
 
-/** What each button does, in the words Consent Mode records. */
-const ACTIONS: Readonly<Record<string, ConsentChoice>> = {
-    grant: "granted",
-    deny: "denied",
-};
-
 /**
  * The banner's behaviour. Its own module, and not re-exported from `client.ts`,
  * so the script ships only where `<ConsentBanner>` renders.
  *
- * A site's markup marks the two buttons inside the banner `data-consent="grant"`
- * and `data-consent="deny"`, and the control that brings it back — usually in
- * the footer — `data-consent-reopen hidden`: it stays hidden until there is an
- * answer to withdraw.
+ * A site's markup marks its buttons with what they do:
+ *
+ * - `data-consent="grant"` — every category granted.
+ * - `data-consent="deny"` — every category denied.
+ * - `data-consent="save"` — each category as its checkbox says:
+ *   `<input type="checkbox" data-consent-category="analytics">`, and one for
+ *   `marketing`.
+ *
+ * A banner with only the first two still works — one answer for everything.
+ * The checkboxes are never ticked by default; they show an answer already
+ * given, and nothing else.
+ *
+ * The control that brings it back — usually in the footer — is
+ * `data-consent-reopen hidden`: it stays hidden until there is an answer to
+ * withdraw.
  */
 export const consentBanner = element("atlas-consent", ({ root, signal }) => {
+    const boxes = refs<HTMLInputElement>(root, "[data-consent-category]").map(
+        (box) => {
+            const category = data(box, "consent-category");
+            if (!CONSENT_CATEGORIES.includes(category as ConsentCategory)) {
+                throw new Error(
+                    `data-consent-category is "${category}", not ${CONSENT_CATEGORIES.join(" or ")}`
+                );
+            }
+            return { box, category: category as ConsentCategory };
+        }
+    );
+
+    const fromBoxes = (): ConsentChoices => {
+        const granted = (category: ConsentCategory) =>
+            boxes.some((each) => each.category === category && each.box.checked)
+                ? "granted"
+                : "denied";
+        return {
+            analytics: granted("analytics"),
+            marketing: granted("marketing"),
+        };
+    };
+
     const show = (): void => {
+        // Only an answer already given ticks a box.
+        const stored = readConsent();
+        for (const { box, category } of boxes) {
+            box.checked = stored?.[category] === "granted";
+        }
         root.hidden = false;
     };
 
+    const ACTIONS: Readonly<Record<string, () => ConsentChoices>> = {
+        grant: () => everyCategory("granted"),
+        deny: () => everyCategory("denied"),
+        save: fromBoxes,
+    };
+
     for (const button of refs(root, "[data-consent]")) {
         const action = data(button, "consent");
-        const choice = Object.hasOwn(ACTIONS, action)
+        const choose = Object.hasOwn(ACTIONS, action)
             ? ACTIONS[action]
             : undefined;
-        if (choice === undefined) {
-            throw new Error(`data-consent is "${action}", not grant or deny`);
+        if (choose === undefined) {
+            throw new Error(
+                `data-consent is "${action}", not grant, deny or save`
+            );
         }
         button.addEventListener(
             "click",
             () => {
-                recordConsent(choice);
+                recordConsent(choose());
                 root.hidden = true;
             },
             { signal }
@@ -51,9 +94,9 @@ export const consentBanner = element("atlas-consent", ({ root, signal }) => {
         button.addEventListener("click", show, { signal });
     }
 
-    // Applied, not re-recorded: recording stamps today's date, and an answer
-    // renewed on every page view never expires.
-    const stored = readConsent();
-    if (stored === undefined) show();
-    else applyConsent(stored.choice);
+    // A stored answer is already applied: the head block hands it to Google
+    // before any tag fires, which this module runs too late to do. Nor is it
+    // re-recorded — that stamps today's date, and an answer renewed on every
+    // page view never expires.
+    if (readConsent() === undefined) show();
 });

package/src/astro/consent.ts

@@ -1,5 +1,17 @@
+import {
+    CONSENT_KEY,
+    CONSENT_MONTHS,
+    type ConsentChoice,
+    type ConsentChoices,
+} from "../analytics/consent-storage.ts";
 import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
 
+export type {
+    ConsentCategory,
+    ConsentChoice,
+    ConsentChoices,
+} from "../analytics/consent-storage.ts";
+
 /**
  * The browser half of consent: remembering an answer, expiring it, and handing
  * it to Google.
@@ -17,45 +29,32 @@ import { CONSENT_UPDATE_GLOBAL } from "../analytics/google.ts";
  * subtly wrong.
  */
 
-/** Granted or denied — the only two answers Consent Mode has. */
-export type ConsentChoice = "granted" | "denied";
-
-/** An answer, and when it was given. */
-export interface ConsentRecord {
-    readonly choice: ConsentChoice;
+/** An answer for every category, and when it was given. */
+export type ConsentRecord = ConsentChoices & {
     /** ISO 8601, so it is legible in devtools rather than a number. */
     readonly at: string;
-}
+};
 
-/**
- * How long an answer stands before the question is asked again.
- *
- * Consent is not forever and regulators say so: France's CNIL puts the outside
- * limit at 13 months and recommends six, and the EDPB's position is that a
- * choice made long enough ago is no longer informed. Six is the conservative
- * reading, and the reason the record carries a date at all — without one there
- * is no way to expire it, and no way to answer "when did this visitor agree?",
- * which is a question only ever asked when somebody is already unhappy.
- */
-const MONTHS = 6;
+/** The same answer for every category — what "accept all" and "reject all" give. */
+export function everyCategory(choice: ConsentChoice): ConsentChoices {
+    return { analytics: choice, marketing: choice };
+}
 
-/**
- * The `localStorage` key the answer is kept under. Prefixed to keep clear of the
- * bare `"consent"` a third-party widget would reach for.
- */
-const KEY = "atlas-consent";
+const isChoice = (value: unknown): value is ConsentChoice =>
+    value === "granted" || value === "denied";
 
 /**
  * The answer this visitor gave, if it still counts.
  *
- * `undefined` for never asked, for an expired answer, and for anything
- * unparseable — all three mean the same thing to a banner, and all three should
- * ask rather than assume.
+ * `undefined` for never asked, for an expired answer, for anything unparseable,
+ * and for one missing a category — given before that category was asked about.
+ * All of them mean the same thing to a banner, and all of them should ask
+ * rather than assume.
  */
 export function readConsent(): ConsentRecord | undefined {
     let raw: string | null = null;
     try {
-        raw = localStorage.getItem(KEY);
+        raw = localStorage.getItem(CONSENT_KEY);
     } catch {
         // Private browsing, or storage disabled. Nothing was remembered, so
         // nothing is assumed.
@@ -64,18 +63,17 @@ export function readConsent(): ConsentRecord | undefined {
     if (raw === null) return undefined;
 
     try {
-        const parsed = JSON.parse(raw) as Partial<ConsentRecord>;
-        if (parsed.choice !== "granted" && parsed.choice !== "denied") {
-            return undefined;
-        }
-        if (typeof parsed.at !== "string") return undefined;
+        const parsed = JSON.parse(raw) as Partial<Record<string, unknown>>;
+        const { analytics, marketing, at } = parsed;
+        if (!isChoice(analytics) || !isChoice(marketing)) return undefined;
+        if (typeof at !== "string") return undefined;
 
-        const expiry = new Date(parsed.at);
+        const expiry = new Date(at);
         if (Number.isNaN(expiry.getTime())) return undefined;
-        expiry.setMonth(expiry.getMonth() + MONTHS);
+        expiry.setMonth(expiry.getMonth() + CONSENT_MONTHS);
         if (expiry < new Date()) return undefined;
 
-        return { choice: parsed.choice, at: parsed.at };
+        return { analytics, marketing, at };
     } catch {
         return undefined;
     }
@@ -85,31 +83,36 @@ export function readConsent(): ConsentRecord | undefined {
  * Remembers an answer, dated now, and tells Google about it — one call, so the
  * two cannot come apart.
  */
-export function recordConsent(choice: ConsentChoice): void {
-    const record: ConsentRecord = { choice, at: new Date().toISOString() };
+export function recordConsent(choices: ConsentChoices): void {
+    const record: ConsentRecord = { ...choices, at: new Date().toISOString() };
     try {
-        localStorage.setItem(KEY, JSON.stringify(record));
+        localStorage.setItem(CONSENT_KEY, JSON.stringify(record));
     } catch {
         // Unable to remember it, which is a worse experience and not a wrong
         // one — the choice still applies to this page.
     }
-    applyConsent(choice);
+    applyConsent(choices);
 }
 
 /**
- * Hands a choice to Google, if there is a Google tag on this deployment.
+ * Hands an answer to Google, if there is a Google tag on this deployment.
  *
  * Reaches the head script through a global, which is the only way the two can
  * meet: that script runs before any module exists. The name lives in one place
  * — `CONSENT_UPDATE_GLOBAL` — and is referenced here and where it is emitted,
  * so a project never types it.
  *
- * What it updates is decided over there, from the same settings that decided
- * what to deny. A payload built here would be a second copy of that list.
+ * Which signals each category moves is decided over there, from the same
+ * settings that decided what to deny. A payload built here would be a second
+ * copy of that list.
  */
-export function applyConsent(choice: ConsentChoice): void {
+export function applyConsent(choices: ConsentChoices): void {
     const update = (
-        window as unknown as Record<string, ((c: string) => void) | undefined>
+        window as unknown as Record<
+            string,
+            ((c: ConsentChoices) => void) | undefined
+        >
     )[CONSENT_UPDATE_GLOBAL];
-    update?.(choice);
+    // Only the categories, so a record's date does not ride along.
+    update?.({ analytics: choices.analytics, marketing: choices.marketing });
 }