@escape-game-over/atlas 0.1.54 → 0.1.55

package/package.json

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

package/src/analytics/index.ts

@@ -1,6 +1,7 @@
 import type { MetaTag } from "../meta/tag.ts";
 import type { HttpsUrl } from "../url.ts";
 import { type GoogleSettings, googleEmits, googleScripts } from "./google.ts";
+import { checkMetaPixel, type MetaPixelSettings } from "./meta-pixel.ts";
 import type { AnalyticsTags } from "./tags.ts";
 import {
     checkUmamiDomains,
@@ -29,6 +30,7 @@ export {
     type ConsentState,
     type GoogleSettings,
 } from "./google.ts";
+export type { MetaPixelSettings } from "./meta-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";
 export type {
     UmamiReplay,
@@ -40,6 +42,8 @@ export type {
 export interface AnalyticsSettings {
     readonly umami?: UmamiSettings;
     readonly google?: GoogleSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly meta?: MetaPixelSettings;
 }
 
 /**
@@ -60,6 +64,7 @@ export function analyticsScripts(
     if (analytics === undefined) return { head: [], body: [] };
 
     checkUmamiDomains(analytics.umami, origin);
+    checkMetaPixel(analytics.meta, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -98,6 +103,8 @@ export function consentVendors(
         umami: false,
         // Consent Mode, but only once there is a tag reading it.
         google: googleEmits(analytics.google),
+        // No cookieless mode: nothing loads until marketing is granted.
+        meta: analytics.meta !== undefined,
     };
 
     return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(

package/src/analytics/meta-pixel.ts

@@ -0,0 +1,23 @@
+import type { NonEmpty } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/** Meta's pixel. Marketing: it loads only once a visitor grants that. */
+export interface MetaPixelSettings {
+    /** From Events Manager: 15 or 16 digits. Several share one script. */
+    readonly pixelIds: NonEmpty<string>;
+}
+
+/** Warns about an id that is not a pixel id: it would report nowhere. */
+export function checkMetaPixel(
+    meta: MetaPixelSettings | undefined,
+    at: string
+): void {
+    for (const id of meta?.pixelIds ?? []) {
+        if (!/^\d{15,16}$/.test(id)) {
+            warn(
+                at,
+                `Meta pixel id "${id}" is not 15 or 16 digits, so it reports nowhere. Copy it from Events Manager.`
+            );
+        }
+    }
+}

package/src/astro/ConsentBanner.astro

@@ -5,12 +5,13 @@
  * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
- * permission. Otherwise the banner starts hidden and shows only to a visitor
+ * permission. Also loads the vendors that wait for consent, such as Meta's pixel. Otherwise the banner starts hidden and shows only to a visitor
  * with no answer on record, or when a `data-consent-reopen` control is pressed.
  */
 import type { HTMLAttributes } from "astro/types";
 import { type AnalyticsSettings, consentRequired } from "../analytics/index.ts";
 import ConsentElement from "./ConsentElement.astro";
+import MetaPixel from "./MetaPixel.astro";
 
 type Props = HTMLAttributes<"div"> & {
     readonly analytics: AnalyticsSettings | undefined;
@@ -20,7 +21,10 @@ const { analytics, ...attrs } = Astro.props;
 ---
 
 {consentRequired(analytics) && (
-    <ConsentElement {...attrs}>
-        <slot />
-    </ConsentElement>
+    <>
+        <ConsentElement {...attrs}>
+            <slot />
+        </ConsentElement>
+        {analytics?.meta && <MetaPixel settings={analytics.meta} />}
+    </>
 )}

package/src/astro/MetaPixel.astro

@@ -0,0 +1,18 @@
+---
+/** Internal to `ConsentBanner.astro`, so the pixel's script ships only where it is configured. */
+import type { MetaPixelSettings } from "../analytics/meta-pixel.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { metaPixelElement } from "./meta-pixel.ts";
+
+interface Props {
+    readonly settings: MetaPixelSettings;
+}
+---
+
+<script src="./meta-pixel.ts" />
+
+<AtlasElement
+    of={metaPixelElement}
+    data-pixel-ids={JSON.stringify(Astro.props.settings.pixelIds)}
+    hidden
+/>

package/src/astro/client.ts

@@ -23,6 +23,7 @@ export {
 } from "./element.ts";
 export * from "./filters.ts";
 export * from "./filters-view.ts";
+export * from "./meta-event.ts";
 export { data, ref, refs } from "./ref.ts";
 export * from "./umami-event.ts";
 export * from "./youtube.ts";

package/src/astro/consent-gate.ts

@@ -0,0 +1,48 @@
+import {
+    CONSENT_EVENT,
+    type ConsentCategory,
+    type ConsentChoices,
+    readConsent,
+} from "./consent.ts";
+
+/** What a vendor does as its category is granted and withdrawn. */
+export interface ConsentGated {
+    /** After `load`, each time the category is granted: a stored answer, or one given now. */
+    readonly grant: () => void;
+    /** Each time a grant is withdrawn on this page. */
+    readonly revoke?: () => void;
+}
+
+/** Runs `vendor` as the visitor's answer for `category` says, until `signal` aborts. */
+export function whenGranted(
+    category: ConsentCategory,
+    vendor: ConsentGated,
+    signal?: AbortSignal
+): void {
+    let granted = readConsent()?.[category] === "granted";
+
+    // After `load`, so a vendor does not compete with the page. Checked again
+    // then: an answer withdrawn before `load` cancels the grant.
+    const grantAfterLoad = () => {
+        const run = () => {
+            if (granted) vendor.grant();
+        };
+        if (document.readyState === "complete") run();
+        else addEventListener("load", run, { once: true, signal });
+    };
+
+    if (granted) grantAfterLoad();
+
+    addEventListener(
+        CONSENT_EVENT,
+        (event) => {
+            const choices = (event as CustomEvent<ConsentChoices>).detail;
+            const now = choices[category] === "granted";
+            if (now === granted) return;
+            granted = now;
+            if (now) grantAfterLoad();
+            else vendor.revoke?.();
+        },
+        { signal }
+    );
+}

package/src/astro/meta-event.ts

@@ -0,0 +1,61 @@
+import type { CurrencyCode } from "../money.ts";
+
+/** Meta's standard events, which its ad optimisation understands by name. */
+export type MetaStandardEvent =
+    | "AddPaymentInfo"
+    | "AddToCart"
+    | "AddToWishlist"
+    | "CompleteRegistration"
+    | "Contact"
+    | "CustomizeProduct"
+    | "Donate"
+    | "FindLocation"
+    | "InitiateCheckout"
+    | "Lead"
+    | "Purchase"
+    | "Schedule"
+    | "Search"
+    | "StartTrial"
+    | "SubmitApplication"
+    | "Subscribe"
+    | "ViewContent";
+
+/** Meta's standard parameters. What the visitor chose, never who they are. */
+export interface MetaEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+    readonly content_name?: string;
+    readonly content_category?: string;
+    readonly content_ids?: readonly string[];
+    readonly content_type?: "product" | "product_group";
+    readonly num_items?: number;
+    readonly search_string?: string;
+    readonly status?: boolean;
+}
+
+/** `Purchase` is the one event Meta rejects without a value and currency. */
+type MetaEventArgs<E extends MetaStandardEvent> = E extends "Purchase"
+    ? [data: MetaEventData & { value: number; currency: CurrencyCode }]
+    : [data?: MetaEventData];
+
+/** What `meta-pixel.ts` defines once marketing is granted. */
+interface MetaWindow {
+    fbq?: (...args: unknown[]) => void;
+}
+
+/**
+ * Records a standard event with Meta's pixel — a lead sent, a booking made.
+ *
+ * `fbq` exists only once the visitor granted marketing and the pixel loaded.
+ * Before that, without consent, or where Meta is not configured, the event is
+ * dropped: no consent means nothing to send, and an analytics call must never
+ * be the reason a page misbehaves.
+ */
+export function metaEvent<E extends MetaStandardEvent>(
+    event: E,
+    ...[data]: MetaEventArgs<E>
+): void {
+    const fbq = (window as unknown as MetaWindow).fbq;
+    if (data === undefined) fbq?.("track", event);
+    else fbq?.("track", event, data);
+}

package/src/astro/meta-pixel.ts

@@ -0,0 +1,76 @@
+import type { ConsentGated } from "./consent-gate.ts";
+import { whenGranted } from "./consent-gate.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** Meta's `fbq`: a queue until `fbevents.js` arrives and replays it. */
+interface Fbq {
+    (...args: unknown[]): void;
+    callMethod?: (...args: unknown[]) => void;
+    queue: unknown[];
+    push: Fbq;
+    loaded: boolean;
+    version: string;
+}
+
+interface PixelWindow {
+    fbq?: Fbq;
+    _fbq?: Fbq;
+}
+
+const SCRIPT = "https://connect.facebook.net/en_US/fbevents.js";
+
+/** Meta's own base code, as it defines `fbq` before the script loads. */
+function defineFbq(): Fbq {
+    const global = window as unknown as PixelWindow;
+    if (global.fbq !== undefined) return global.fbq;
+    const fbq = function () {
+        // biome-ignore lint/complexity/noArguments: Meta's queue takes the arguments object, as its snippet pushes it.
+        if (fbq.callMethod) Reflect.apply(fbq.callMethod, fbq, arguments);
+        // biome-ignore lint/complexity/noArguments: as above.
+        else fbq.queue.push(arguments);
+    } as Fbq;
+    fbq.push = fbq;
+    fbq.loaded = true;
+    fbq.version = "2.0";
+    fbq.queue = [];
+    global.fbq = fbq;
+    global._fbq ??= fbq;
+    return fbq;
+}
+
+/** The pixel: loaded on the first grant, paused and resumed by later answers. */
+export function metaPixel(pixelIds: readonly string[]): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            const fbq = defineFbq();
+            if (loaded) {
+                fbq("consent", "grant");
+                return;
+            }
+            loaded = true;
+            for (const id of pixelIds) fbq("init", id);
+            fbq("track", "PageView");
+            const script = document.createElement("script");
+            script.async = true;
+            script.src = SCRIPT;
+            document.head.append(script);
+        },
+        revoke: () => {
+            (window as unknown as PixelWindow).fbq?.("consent", "revoke");
+        },
+    };
+}
+
+/** Internal to `MetaPixel.astro`. */
+export const metaPixelElement = element(
+    "atlas-meta-pixel",
+    ({ root, signal }) => {
+        whenGranted(
+            "marketing",
+            metaPixel(JSON.parse(data(root, "pixel-ids"))),
+            signal
+        );
+    }
+);

package/src/index.ts

@@ -28,6 +28,7 @@ export {
     consentRequired,
     consentVendors,
     type GoogleSettings,
+    type MetaPixelSettings,
     type UmamiReplay,
     type UmamiSettings,
     type UmamiTracker,