@escape-game-over/atlas 0.1.57 → 0.1.58

package/package.json

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

package/src/analytics/axon-pixel.ts

@@ -0,0 +1,20 @@
+import { warn } from "../warn.ts";
+import { UUID } from "./snap-pixel.ts";
+
+/** AppLovin's Axon pixel. Marketing: it loads only once a visitor grants that. */
+export interface AxonPixelSettings {
+    /** From the Axon dashboard: a UUID. */
+    readonly eventKey: string;
+}
+
+/** Warns about a key that is not an event key: it would report nowhere. */
+export function checkAxonPixel(
+    axon: AxonPixelSettings | undefined,
+    at: string
+): void {
+    if (axon === undefined || UUID.test(axon.eventKey)) return;
+    warn(
+        at,
+        `Axon event key "${axon.eventKey}" is not a UUID, so it reports nowhere. Copy it from the Axon dashboard.`
+    );
+}

package/src/analytics/index.ts

@@ -1,5 +1,6 @@
 import type { MetaTag } from "../meta/tag.ts";
 import type { HttpsUrl } from "../url.ts";
+import { type AxonPixelSettings, checkAxonPixel } from "./axon-pixel.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";
@@ -26,6 +27,7 @@ import {
  * project states ids; lib decides everything that follows from them.
  */
 
+export type { AxonPixelSettings } from "./axon-pixel.ts";
 export {
     CONSENT_UPDATE_GLOBAL,
     type ConsentDefaults,
@@ -52,6 +54,8 @@ export interface AnalyticsSettings {
     readonly tiktok?: TikTokPixelSettings;
     /** Loaded by `ConsentBanner`, after marketing is granted. */
     readonly snapchat?: SnapPixelSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly axon?: AxonPixelSettings;
 }
 
 /**
@@ -75,6 +79,7 @@ export function analyticsScripts(
     checkMetaPixel(analytics.meta, origin);
     checkTikTokPixel(analytics.tiktok, origin);
     checkSnapPixel(analytics.snapchat, origin);
+    checkAxonPixel(analytics.axon, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -119,6 +124,8 @@ export function consentVendors(
         tiktok: analytics.tiktok !== undefined,
         // No consent mode at all.
         snapchat: analytics.snapchat !== undefined,
+        // No consent mode at all.
+        axon: analytics.axon !== undefined,
     };
 
     return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(

package/src/analytics/snap-pixel.ts

@@ -7,7 +7,8 @@ export interface SnapPixelSettings {
     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;
+export 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(

package/src/astro/AxonPixel.astro

@@ -0,0 +1,18 @@
+---
+/** Internal to `ConsentBanner.astro`, so the pixel's script ships only where it is configured. */
+import type { AxonPixelSettings } from "../analytics/axon-pixel.ts";
+import AtlasElement from "./AtlasElement.astro";
+import { axonPixelElement } from "./axon-pixel.ts";
+
+interface Props {
+    readonly settings: AxonPixelSettings;
+}
+---
+
+<script src="./axon-pixel.ts" />
+
+<AtlasElement
+    of={axonPixelElement}
+    data-event-key={Astro.props.settings.eventKey}
+    hidden
+/>

package/src/astro/ConsentBanner.astro

@@ -5,11 +5,12 @@
  * 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 the Meta, TikTok and Snap 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, Snap and Axon 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 AxonPixel from "./AxonPixel.astro";
 import ConsentElement from "./ConsentElement.astro";
 import MetaPixel from "./MetaPixel.astro";
 import SnapPixel from "./SnapPixel.astro";
@@ -30,5 +31,6 @@ const { analytics, ...attrs } = Astro.props;
         {analytics?.meta && <MetaPixel settings={analytics.meta} />}
         {analytics?.tiktok && <TikTokPixel settings={analytics.tiktok} />}
         {analytics?.snapchat && <SnapPixel settings={analytics.snapchat} />}
+        {analytics?.axon && <AxonPixel settings={analytics.axon} />}
     </>
 )}

package/src/astro/axon-event.ts

@@ -0,0 +1,34 @@
+import type { CurrencyCode } from "../money.ts";
+import { readConsent } from "./consent.ts";
+
+/**
+ * Axon's events that a site without a cart sends. The cart and purchase events
+ * are left out: Axon requires line items for them, and the visitor's email or
+ * phone for `purchase`.
+ */
+export type AxonEvent = "generate_lead" | "sign_up" | "login" | "subscribe";
+
+/** What the visitor chose, never who they are. */
+export interface AxonEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+}
+
+/** What `axon-pixel.ts` defines once marketing is granted. */
+interface AxonWindow {
+    axon?: (...args: unknown[]) => void;
+}
+
+/**
+ * Records an event with Axon's pixel — a lead sent, an account made.
+ *
+ * Dropped unless the pixel loaded and marketing is still granted: Axon 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 axonEvent(event: AxonEvent, data?: AxonEventData): void {
+    if (readConsent()?.marketing !== "granted") return;
+    const axon = (window as unknown as AxonWindow).axon;
+    if (data === undefined) axon?.("track", event);
+    else axon?.("track", event, data);
+}

package/src/astro/axon-pixel.ts

@@ -0,0 +1,72 @@
+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";
+
+/** Axon's `axon`: a queue until its scripts arrive and replay it. */
+interface Axon {
+    (...args: unknown[]): void;
+    performOperation?: (...args: unknown[]) => void;
+    operationQueue: unknown[];
+    ts: number;
+    eventKey: string;
+}
+
+interface PixelWindow {
+    axon?: Axon;
+}
+
+const SCRIPTS = [
+    "https://s.axon.ai/pixel.js",
+    "https://res4.applovin.com/p/l/loader.iife.js",
+];
+
+/** Axon's own base code, as it defines `axon` before the scripts load. */
+function defineAxon(eventKey: string): Axon {
+    const global = window as unknown as PixelWindow;
+    if (global.axon !== undefined) return global.axon;
+    // `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 Axon's official
+    // snippet does: it is the shape Axon promises its script will replay.
+    const axon = function () {
+        // biome-ignore lint/complexity/noArguments: see above.
+        const args = arguments;
+        if (axon.performOperation)
+            Reflect.apply(axon.performOperation, axon, args);
+        else axon.operationQueue.push(args);
+    } as Axon;
+    axon.operationQueue = [];
+    axon.ts = Date.now();
+    axon.eventKey = eventKey;
+    global.axon = axon;
+    for (const src of SCRIPTS) appendScript(src);
+    return axon;
+}
+
+/**
+ * The pixel, loaded on the first grant. Axon has no consent call, so a
+ * withdrawal cannot pause what already loaded: `axonEvent` stops sending, and
+ * the next page does not load it.
+ */
+export function axonPixel(eventKey: string): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            if (loaded) return;
+            loaded = true;
+            const axon = defineAxon(eventKey);
+            axon("init");
+            axon("track", "page_view");
+        },
+    };
+}
+
+/** Internal to `AxonPixel.astro`. */
+export const axonPixelElement = element(
+    "atlas-axon-pixel",
+    ({ root, signal }) => {
+        whenGranted("marketing", axonPixel(data(root, "event-key")), signal);
+    }
+);

package/src/astro/client.ts

@@ -10,6 +10,7 @@
  */
 
 export * from "./attribution.ts";
+export * from "./axon-event.ts";
 export * from "./background-video.ts";
 export * from "./carousel.ts";
 // Reading only: a form that reports what the visitor agreed to. Recording an

package/src/index.ts

@@ -22,6 +22,7 @@ export {
 export {
     type AnalyticsSettings,
     type AnalyticsTags,
+    type AxonPixelSettings,
     CONSENT_UPDATE_GLOBAL,
     type ConsentDefaults,
     type ConsentState,