@escape-game-over/atlas 0.1.56 → 0.1.57

package/package.json

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

package/src/analytics/index.ts

@@ -2,6 +2,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 { checkSnapPixel, type SnapPixelSettings } from "./snap-pixel.ts";
 import type { AnalyticsTags } from "./tags.ts";
 import { checkTikTokPixel, type TikTokPixelSettings } from "./tiktok-pixel.ts";
 import {
@@ -32,6 +33,7 @@ export {
     type GoogleSettings,
 } from "./google.ts";
 export type { MetaPixelSettings } from "./meta-pixel.ts";
+export type { SnapPixelSettings } from "./snap-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";
 export type { TikTokPixelSettings } from "./tiktok-pixel.ts";
 export type {
@@ -48,6 +50,8 @@ export interface AnalyticsSettings {
     readonly meta?: MetaPixelSettings;
     /** Loaded by `ConsentBanner`, after marketing is granted. */
     readonly tiktok?: TikTokPixelSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly snapchat?: SnapPixelSettings;
 }
 
 /**
@@ -70,6 +74,7 @@ export function analyticsScripts(
     checkUmamiDomains(analytics.umami, origin);
     checkMetaPixel(analytics.meta, origin);
     checkTikTokPixel(analytics.tiktok, origin);
+    checkSnapPixel(analytics.snapchat, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -112,6 +117,8 @@ export function consentVendors(
         meta: analytics.meta !== undefined,
         // Its Cookie Consent Mode holds events back; it is not cookieless.
         tiktok: analytics.tiktok !== undefined,
+        // No consent mode at all.
+        snapchat: analytics.snapchat !== undefined,
     };
 
     return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(

package/src/analytics/snap-pixel.ts

@@ -0,0 +1,25 @@
+import type { NonEmpty } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/** Snapchat's pixel. Marketing: it loads only once a visitor grants that. */
+export interface SnapPixelSettings {
+    /** From Snap's Events Manager: a UUID. */
+    readonly pixelIds: NonEmpty<string>;
+}
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/** Warns about an id that is not a pixel id: it would report nowhere. */
+export function checkSnapPixel(
+    snapchat: SnapPixelSettings | undefined,
+    at: string
+): void {
+    for (const id of snapchat?.pixelIds ?? []) {
+        if (!UUID.test(id)) {
+            warn(
+                at,
+                `Snap pixel id "${id}" is not a UUID, so it reports nowhere. Copy it from Snap's Events Manager.`
+            );
+        }
+    }
+}

package/src/astro/ConsentBanner.astro

@@ -5,13 +5,14 @@
  * buttons.
  *
  * Renders nothing — and ships no script — when this site's analytics need no
- * permission. Also loads the vendors that wait for consent, such as Meta's and TikTok's pixels. Otherwise the banner starts hidden and shows only to a visitor
+ * permission. Also loads the vendors that wait for consent, such as the Meta, TikTok and Snap pixels. 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";
+import SnapPixel from "./SnapPixel.astro";
 import TikTokPixel from "./TikTokPixel.astro";
 
 type Props = HTMLAttributes<"div"> & {
@@ -28,5 +29,6 @@ const { analytics, ...attrs } = Astro.props;
         </ConsentElement>
         {analytics?.meta && <MetaPixel settings={analytics.meta} />}
         {analytics?.tiktok && <TikTokPixel settings={analytics.tiktok} />}
+        {analytics?.snapchat && <SnapPixel settings={analytics.snapchat} />}
     </>
 )}

package/src/astro/SnapPixel.astro

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

package/src/astro/client.ts

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

package/src/astro/meta-pixel.ts

@@ -25,11 +25,15 @@ const SCRIPT = "https://connect.facebook.net/en_US/fbevents.js";
 function defineFbq(): Fbq {
     const global = window as unknown as PixelWindow;
     if (global.fbq !== undefined) return global.fbq;
+    // `arguments` is the list of whatever a call passed, which every regular
+    // `function` gets without declaring it (an arrow function does not). The
+    // queue stores that object rather than an array because Meta's official
+    // snippet does: it is the shape Meta promises its script will replay.
     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);
+        // biome-ignore lint/complexity/noArguments: see above.
+        const args = arguments;
+        if (fbq.callMethod) Reflect.apply(fbq.callMethod, fbq, args);
+        else fbq.queue.push(args);
     } as Fbq;
     fbq.push = fbq;
     fbq.loaded = true;

package/src/astro/snap-event.ts

@@ -0,0 +1,59 @@
+import type { CurrencyCode } from "../money.ts";
+import { readConsent } from "./consent.ts";
+
+/** Snap's standard events that a website sends. */
+export type SnapStandardEvent =
+    | "VIEW_CONTENT"
+    | "LIST_VIEW"
+    | "SEARCH"
+    | "ADD_CART"
+    | "ADD_TO_WISHLIST"
+    | "START_CHECKOUT"
+    | "ADD_BILLING"
+    | "PURCHASE"
+    | "SIGN_UP"
+    | "SUBSCRIBE"
+    | "LOGIN"
+    | "SAVE"
+    | "SHARE"
+    | "RESERVE"
+    | "START_TRIAL";
+
+/** Snap's standard parameters. What the visitor chose, never who they are. */
+export interface SnapEventData {
+    readonly price?: number;
+    readonly currency?: CurrencyCode;
+    readonly item_ids?: readonly string[];
+    readonly item_category?: string;
+    readonly number_items?: number;
+    readonly transaction_id?: string;
+    readonly search_string?: string;
+    readonly description?: string;
+}
+
+/** `PURCHASE` needs a price and currency for Snap to report a return on spend. */
+type SnapEventArgs<E extends SnapStandardEvent> = E extends "PURCHASE"
+    ? [data: SnapEventData & { price: number; currency: CurrencyCode }]
+    : [data?: SnapEventData];
+
+/** What `snap-pixel.ts` defines once marketing is granted. */
+interface SnapWindow {
+    snaptr?: (...args: unknown[]) => void;
+}
+
+/**
+ * Records a standard event with Snap's pixel — a lead sent, a booking made.
+ *
+ * Dropped unless the pixel loaded and marketing is still granted: Snap has no
+ * consent call of its own, so the check is here. An analytics call must never
+ * be the reason a page misbehaves, so a dropped event is silent.
+ */
+export function snapEvent<E extends SnapStandardEvent>(
+    event: E,
+    ...[data]: SnapEventArgs<E>
+): void {
+    if (readConsent()?.marketing !== "granted") return;
+    const snaptr = (window as unknown as SnapWindow).snaptr;
+    if (data === undefined) snaptr?.("track", event);
+    else snaptr?.("track", event, data);
+}

package/src/astro/snap-pixel.ts

@@ -0,0 +1,69 @@
+import { appendScript } from "./append-script.ts";
+import type { ConsentGated } from "./consent-gate.ts";
+import { whenGranted } from "./consent-gate.ts";
+import { element } from "./element.ts";
+import { data } from "./ref.ts";
+
+/** Snap's `snaptr`: a queue until `scevent.min.js` arrives and replays it. */
+interface Snaptr {
+    (...args: unknown[]): void;
+    handleRequest?: (...args: unknown[]) => void;
+    queue: unknown[];
+}
+
+interface PixelWindow {
+    snaptr?: Snaptr;
+}
+
+const SCRIPT = "https://sc-static.net/scevent.min.js";
+
+/** Snap's own base code, as it defines `snaptr` before the script loads. */
+function defineSnaptr(): Snaptr {
+    const global = window as unknown as PixelWindow;
+    if (global.snaptr !== undefined) return global.snaptr;
+    // `arguments` is the list of whatever a call passed, which every regular
+    // `function` gets without declaring it (an arrow function does not). The
+    // queue stores that object rather than an array because Snap's official
+    // snippet does: it is the shape Snap promises its script will replay.
+    const snaptr = function () {
+        // biome-ignore lint/complexity/noArguments: see above.
+        const args = arguments;
+        if (snaptr.handleRequest)
+            Reflect.apply(snaptr.handleRequest, snaptr, args);
+        else snaptr.queue.push(args);
+    } as Snaptr;
+    snaptr.queue = [];
+    global.snaptr = snaptr;
+    return snaptr;
+}
+
+/**
+ * The pixel, loaded on the first grant. Snap has no consent call, so a
+ * withdrawal cannot pause what already loaded: `snapEvent` stops sending, and
+ * the next page does not load it.
+ */
+export function snapPixel(pixelIds: readonly string[]): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            if (loaded) return;
+            loaded = true;
+            const snaptr = defineSnaptr();
+            for (const id of pixelIds) snaptr("init", id);
+            snaptr("track", "PAGE_VIEW");
+            appendScript(SCRIPT);
+        },
+    };
+}
+
+/** Internal to `SnapPixel.astro`. */
+export const snapPixelElement = element(
+    "atlas-snap-pixel",
+    ({ root, signal }) => {
+        whenGranted(
+            "marketing",
+            snapPixel(JSON.parse(data(root, "pixel-ids"))),
+            signal
+        );
+    }
+);

package/src/index.ts

@@ -29,6 +29,7 @@ export {
     consentVendors,
     type GoogleSettings,
     type MetaPixelSettings,
+    type SnapPixelSettings,
     type TikTokPixelSettings,
     type UmamiReplay,
     type UmamiSettings,