@escape-game-over/atlas 0.1.55 → 0.1.56

package/package.json

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

package/src/analytics/index.ts

@@ -3,6 +3,7 @@ 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 { checkTikTokPixel, type TikTokPixelSettings } from "./tiktok-pixel.ts";
 import {
     checkUmamiDomains,
     type UmamiSettings,
@@ -32,6 +33,7 @@ export {
 } from "./google.ts";
 export type { MetaPixelSettings } from "./meta-pixel.ts";
 export type { AnalyticsTags } from "./tags.ts";
+export type { TikTokPixelSettings } from "./tiktok-pixel.ts";
 export type {
     UmamiReplay,
     UmamiSettings,
@@ -44,6 +46,8 @@ export interface AnalyticsSettings {
     readonly google?: GoogleSettings;
     /** Loaded by `ConsentBanner`, after marketing is granted. */
     readonly meta?: MetaPixelSettings;
+    /** Loaded by `ConsentBanner`, after marketing is granted. */
+    readonly tiktok?: TikTokPixelSettings;
 }
 
 /**
@@ -65,6 +69,7 @@ export function analyticsScripts(
 
     checkUmamiDomains(analytics.umami, origin);
     checkMetaPixel(analytics.meta, origin);
+    checkTikTokPixel(analytics.tiktok, origin);
     const google = googleScripts(analytics.google, origin);
     return {
         head: [...google.head, ...umamiScripts(analytics.umami)],
@@ -105,6 +110,8 @@ export function consentVendors(
         google: googleEmits(analytics.google),
         // No cookieless mode: nothing loads until marketing is granted.
         meta: analytics.meta !== undefined,
+        // Its Cookie Consent Mode holds events back; it is not cookieless.
+        tiktok: analytics.tiktok !== undefined,
     };
 
     return (Object.keys(VENDORS) as (keyof AnalyticsSettings)[]).filter(

package/src/analytics/tiktok-pixel.ts

@@ -0,0 +1,23 @@
+import type { NonEmpty } from "../types.ts";
+import { warn } from "../warn.ts";
+
+/** TikTok's pixel. Marketing: it loads only once a visitor grants that. */
+export interface TikTokPixelSettings {
+    /** From TikTok Events Manager: 20 capital letters and digits. */
+    readonly pixelIds: NonEmpty<string>;
+}
+
+/** Warns about an id that is not a pixel id: it would report nowhere. */
+export function checkTikTokPixel(
+    tiktok: TikTokPixelSettings | undefined,
+    at: string
+): void {
+    for (const id of tiktok?.pixelIds ?? []) {
+        if (!/^[A-Z0-9]{20}$/.test(id)) {
+            warn(
+                at,
+                `TikTok pixel id "${id}" is not 20 capital letters and digits, so it reports nowhere. Copy it from TikTok 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 pixel. Otherwise the banner starts hidden and shows only to a visitor
+ * 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
  * 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 TikTokPixel from "./TikTokPixel.astro";
 
 type Props = HTMLAttributes<"div"> & {
     readonly analytics: AnalyticsSettings | undefined;
@@ -26,5 +27,6 @@ const { analytics, ...attrs } = Astro.props;
             <slot />
         </ConsentElement>
         {analytics?.meta && <MetaPixel settings={analytics.meta} />}
+        {analytics?.tiktok && <TikTokPixel settings={analytics.tiktok} />}
     </>
 )}

package/src/astro/TikTokPixel.astro

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

package/src/astro/append-script.ts

@@ -0,0 +1,8 @@
+/** Fetches a vendor's script without blocking the page. */
+export function appendScript(src: string): HTMLScriptElement {
+    const script = document.createElement("script");
+    script.async = true;
+    script.src = src;
+    document.head.append(script);
+    return script;
+}

package/src/astro/client.ts

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

package/src/astro/google-map.ts

@@ -1,5 +1,6 @@
 /// <reference types="google.maps" />
 import type { MapFrame } from "../map.ts";
+import { appendScript } from "./append-script.ts";
 import { reportDevError } from "./dev-log.ts";
 import { element } from "./element.ts";
 import { data } from "./ref.ts";
@@ -33,17 +34,19 @@ export function loadGoogleMaps(apiKey: string): Promise<typeof google.maps> {
     loading ??= new Promise((resolve, reject) => {
         (window as unknown as Record<string, () => void>)[CALLBACK] = () =>
             resolve(google.maps);
-        const script = document.createElement("script");
-        script.src = `https://maps.googleapis.com/maps/api/js?${new URLSearchParams(
-            { key: apiKey, v: "weekly", loading: "async", callback: CALLBACK }
-        )}`;
-        script.async = true;
-        script.onerror = () => {
+        const params = {
+            key: apiKey,
+            v: "weekly",
+            loading: "async",
+            callback: CALLBACK,
+        };
+        appendScript(
+            `https://maps.googleapis.com/maps/api/js?${new URLSearchParams(params)}`
+        ).onerror = () => {
             // So the next click tries again.
             loading = undefined;
             reject(new Error("the Maps JavaScript API failed to load"));
         };
-        document.head.append(script);
     });
     return loading;
 }

package/src/astro/meta-pixel.ts

@@ -1,3 +1,4 @@
+import { appendScript } from "./append-script.ts";
 import type { ConsentGated } from "./consent-gate.ts";
 import { whenGranted } from "./consent-gate.ts";
 import { element } from "./element.ts";
@@ -52,10 +53,7 @@ export function metaPixel(pixelIds: readonly string[]): ConsentGated {
             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);
+            appendScript(SCRIPT);
         },
         revoke: () => {
             (window as unknown as PixelWindow).fbq?.("consent", "revoke");

package/src/astro/tiktok-event.ts

@@ -0,0 +1,59 @@
+import type { CurrencyCode } from "../money.ts";
+
+/** TikTok's standard events, by their current names (May 2025 onwards). */
+export type TikTokStandardEvent =
+    | "AddPaymentInfo"
+    | "AddToCart"
+    | "AddToWishlist"
+    | "CompleteRegistration"
+    | "Contact"
+    | "Download"
+    | "InitiateCheckout"
+    | "Lead"
+    | "Login"
+    | "Purchase"
+    | "Search"
+    | "StartTrial"
+    | "SubmitApplication"
+    | "Subscribe"
+    | "ViewContent";
+
+/** TikTok's standard parameters. What the visitor chose, never who they are. */
+export interface TikTokEventData {
+    readonly value?: number;
+    readonly currency?: CurrencyCode;
+    readonly content_id?: string;
+    readonly content_type?: "product" | "product_group";
+    readonly content_name?: string;
+    readonly content_category?: string;
+    readonly quantity?: number;
+    readonly query?: string;
+    readonly description?: string;
+}
+
+/** `Purchase` needs a value and currency to be worth anything to TikTok. */
+type TikTokEventArgs<E extends TikTokStandardEvent> = E extends "Purchase"
+    ? [data: TikTokEventData & { value: number; currency: CurrencyCode }]
+    : [data?: TikTokEventData];
+
+/** What `tiktok-pixel.ts` defines once marketing is granted. */
+interface TikTokWindow {
+    ttq?: { track(event: string, data?: object): void };
+}
+
+/**
+ * Records a standard event with TikTok's pixel — a lead sent, a booking made.
+ *
+ * `ttq` exists only once the visitor granted marketing and the pixel loaded.
+ * Before that, without consent, or where TikTok 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 tiktokEvent<E extends TikTokStandardEvent>(
+    event: E,
+    ...[data]: TikTokEventArgs<E>
+): void {
+    const ttq = (window as unknown as TikTokWindow).ttq;
+    if (data === undefined) ttq?.track(event);
+    else ttq?.track(event, data);
+}

package/src/astro/tiktok-pixel.ts

@@ -0,0 +1,112 @@
+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";
+
+/** TikTok's `ttq`: a queue of calls until `events.js` arrives and replays it. */
+interface Ttq extends Array<unknown> {
+    methods: readonly string[];
+    setAndDefer(target: unknown[], method: string): void;
+    instance(id: string): unknown[];
+    load(id: string, options?: object): void;
+    _i: Record<string, unknown[] & { _u?: string }>;
+    _t: Record<string, number>;
+    _o: Record<string, object>;
+    [method: string]: unknown;
+}
+
+interface PixelWindow {
+    ttq?: Ttq;
+    TiktokAnalyticsObject?: string;
+}
+
+const SCRIPT = "https://analytics.tiktok.com/i18n/pixel/events.js";
+
+const METHODS = [
+    "page",
+    "track",
+    "identify",
+    "instances",
+    "debug",
+    "on",
+    "off",
+    "once",
+    "ready",
+    "alias",
+    "group",
+    "enableCookie",
+    "disableCookie",
+    "holdConsent",
+    "revokeConsent",
+    "grantConsent",
+] as const;
+
+/** TikTok's own base code, as it defines `ttq` before the script loads. */
+function defineTtq(): Ttq {
+    const global = window as unknown as PixelWindow;
+    if (global.ttq !== undefined) return global.ttq;
+    global.TiktokAnalyticsObject = "ttq";
+    const ttq = [] as unknown as Ttq;
+    ttq.methods = METHODS;
+    ttq.setAndDefer = (target, method) => {
+        (target as unknown as Record<string, unknown>)[method] = (
+            ...args: unknown[]
+        ) => target.push([method, ...args]);
+    };
+    for (const method of METHODS) ttq.setAndDefer(ttq, method);
+    ttq.instance = (id) => {
+        const queue = ttq._i?.[id] ?? [];
+        for (const method of METHODS) ttq.setAndDefer(queue, method);
+        return queue;
+    };
+    ttq.load = (id, options = {}) => {
+        ttq._i ??= {};
+        ttq._i[id] = Object.assign([], { _u: SCRIPT });
+        ttq._t ??= {};
+        ttq._t[id] = Date.now();
+        ttq._o ??= {};
+        ttq._o[id] = options;
+        appendScript(
+            `${SCRIPT}?${new URLSearchParams({ sdkid: id, lib: "ttq" })}`
+        );
+    };
+    global.ttq = ttq;
+    return ttq;
+}
+
+const call = (ttq: Ttq, method: (typeof METHODS)[number], ...args: unknown[]) =>
+    (ttq[method] as (...args: unknown[]) => void)(...args);
+
+/** The pixel: loaded on the first grant, paused and resumed by later answers. */
+export function tiktokPixel(pixelIds: readonly string[]): ConsentGated {
+    let loaded = false;
+    return {
+        grant: () => {
+            const ttq = defineTtq();
+            // Also lifts the hold of TikTok's Cookie Consent Mode, where a
+            // pixel has it on in Events Manager.
+            call(ttq, "grantConsent");
+            if (loaded) return;
+            loaded = true;
+            for (const id of pixelIds) ttq.load(id);
+            call(ttq, "page");
+        },
+        revoke: () => {
+            const ttq = (window as unknown as PixelWindow).ttq;
+            if (ttq !== undefined) call(ttq, "revokeConsent");
+        },
+    };
+}
+
+/** Internal to `TikTokPixel.astro`. */
+export const tiktokPixelElement = element(
+    "atlas-tiktok-pixel",
+    ({ root, signal }) => {
+        whenGranted(
+            "marketing",
+            tiktokPixel(JSON.parse(data(root, "pixel-ids"))),
+            signal
+        );
+    }
+);

package/src/index.ts

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