@escape-game-over/atlas 0.1.40 → 0.1.42

package/package.json

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

package/src/astro/attribution.ts

@@ -0,0 +1,122 @@
+/**
+ * Where a visit came from, for a lead form to report: the campaign tags it
+ * landed with, and the Google Ads click behind it.
+ *
+ * A lead is the one record that outlives the visit — an email, a row in a
+ * sheet — so it is where a conversion import has to find the click, and where
+ * anyone asking "which campaign brought this?" will look.
+ *
+ * The two are kept differently, on purpose:
+ *
+ * - **Campaign tags** (`utm_*`) are labels a campaign shares with everyone who
+ *   clicked it, not an identifier. They are kept for the tab in
+ *   `sessionStorage`, so a visitor who lands on one page and fills a form on
+ *   another still reports them. `rememberCampaign()` on every page does that.
+ * - **The ad click id** (`gclid`, `gbraid`, `wbraid`) identifies one click, and
+ *   is never stored here. Google keeps it under the visitor's consent: on the
+ *   URL while marketing is denied — `urlPassthrough` in `GoogleSettings` — and
+ *   in its own `_gcl_aw` cookie once granted. `adClick()` reads it from there.
+ */
+
+/** The campaign tags a link can carry. */
+export type CampaignTag =
+    | "utm_source"
+    | "utm_medium"
+    | "utm_campaign"
+    | "utm_term"
+    | "utm_content";
+
+const CAMPAIGN_TAGS: readonly CampaignTag[] = [
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+];
+
+/** The ids Google Ads puts on a landing URL. */
+export type AdClickId = "gclid" | "gbraid" | "wbraid";
+
+const AD_CLICK_IDS: readonly AdClickId[] = ["gclid", "gbraid", "wbraid"];
+
+export type Campaign = Partial<Record<CampaignTag, string>>;
+export type AdClick = Partial<Record<AdClickId, string>>;
+
+/** The `sessionStorage` key the tags are kept under. */
+const KEY = "atlas-campaign";
+
+/** The given parameters present on this page's URL. */
+function fromUrl<K extends string>(
+    names: readonly K[]
+): Partial<Record<K, string>> {
+    const params = new URLSearchParams(location.search);
+    const found: Partial<Record<K, string>> = {};
+    for (const name of names) {
+        const value = params.get(name);
+        if (value) found[name] = value;
+    }
+    return found;
+}
+
+/** Keeps this page's campaign tags for the tab, if it has any. */
+export function rememberCampaign(): void {
+    const landed = fromUrl(CAMPAIGN_TAGS);
+    if (Object.keys(landed).length === 0) return;
+    try {
+        sessionStorage.setItem(KEY, JSON.stringify(landed));
+    } catch {
+        // Storage refused: the tags still count on the page they arrived on.
+    }
+}
+
+/** The tags on this page's URL, else the ones the visit landed with. */
+export function campaign(): Campaign {
+    const here = fromUrl(CAMPAIGN_TAGS);
+    if (Object.keys(here).length > 0) return here;
+    try {
+        const kept: unknown = JSON.parse(sessionStorage.getItem(KEY) ?? "{}");
+        if (typeof kept !== "object" || kept === null) return {};
+        const found: Campaign = {};
+        for (const tag of CAMPAIGN_TAGS) {
+            const value = (kept as Record<string, unknown>)[tag];
+            if (typeof value === "string" && value !== "") found[tag] = value;
+        }
+        return found;
+    } catch {
+        return {};
+    }
+}
+
+/**
+ * A moment as a Google Ads conversion import reads it:
+ * `2026-09-24 12:42:10+00:00`. In UTC, so the file needs no time zone setting.
+ */
+export function conversionTime(at: Date = new Date()): string {
+    return `${at.toISOString().slice(0, 19).replace("T", " ")}+00:00`;
+}
+
+/**
+ * A cookie's value. `document.cookie` is always `name=value; name=value`, so a
+ * split reads it — `cookieStore.get` would too, but is async and newer than
+ * the Safari still in use.
+ */
+function cookie(name: string): string | undefined {
+    const prefix = `${name}=`;
+    return document.cookie
+        .split("; ")
+        .find((pair) => pair.startsWith(prefix))
+        ?.slice(prefix.length);
+}
+
+/**
+ * The Google Ads click behind this visit: from the URL, else `gclid` from
+ * Google's `_gcl_aw` cookie, whose value is `GCL.<time>.<gclid>`.
+ */
+export function adClick(): AdClick {
+    const click = fromUrl(AD_CLICK_IDS);
+    if (click.gclid === undefined) {
+        const gclid = cookie("_gcl_aw")?.split(".").slice(2).join(".");
+        if (gclid) click.gclid = gclid;
+    }
+    return click;
+}

package/src/astro/client.ts

@@ -9,8 +9,12 @@
  * import, so a component's contract can be imported from frontmatter too.
  */
 
+export * from "./attribution.ts";
 export * from "./background-video.ts";
 export * from "./carousel.ts";
+// Reading only: a form that reports what the visitor agreed to. Recording an
+// answer stays with the banner.
+export { type ConsentRecord, readConsent } from "./consent.ts";
 export {
     type Connect,
     type ElementContext,
@@ -20,4 +24,5 @@ export {
 export * from "./filters.ts";
 export * from "./filters-view.ts";
 export { data, ref, refs } from "./ref.ts";
+export * from "./umami-event.ts";
 export * from "./youtube.ts";

package/src/astro/umami-event.ts

@@ -0,0 +1,24 @@
+/**
+ * Records a named event with Umami — a form sent, a deck downloaded — from a
+ * client script.
+ *
+ * Umami's own script defines `window.umami` once it has loaded; atlas emits
+ * that script from `analytics.umami`. Before then, or where a blocker stopped
+ * it, there is nothing to call, and the event is dropped rather than thrown:
+ * an analytics call must never be the reason a page misbehaves.
+ *
+ * The data goes to Umami as it is, so it should carry what the visitor chose,
+ * never who they are. For an event on a plain click, Umami's
+ * `data-umami-event` attribute needs no script at all.
+ */
+export function umamiEvent(
+    name: string,
+    data?: Readonly<Record<string, string>>
+): void {
+    const umami = (
+        window as unknown as {
+            umami?: { track(event: string, data?: object): void };
+        }
+    ).umami;
+    umami?.track(name, data);
+}