@makefully/adaptfully 3.13.0 → 3.15.0

package/CHANGELOG.md

@@ -2,6 +2,20 @@
 
 All notable changes to this project are documented in this file.
 
+## 3.15.0 — 2026-08-24
+
+### Added
+
+- **`http-analytics`** — vendor-neutral analytics plugin that batches `track` events to `config.analyticsEndpoint` via `sendBeacon` / `fetch` (works on web, Electron `file://`, and Capacitor). Config: `analyticsEndpoint`, `analyticsGameId`, `analyticsEnabled`, optional `analyticsPlatform` / `analyticsAppVersion`. API: `track`, `identify`, `setContext`, `optOut` / `optIn` / `isOptedOut`, `flush`.
+- **`noop-analytics`** — same surface with no network I/O (local/dev and privacy-off builds).
+
+## 3.14.0 — 2026-08-21
+
+### Added
+
+- **`platform.supportsLogout()`** — whether `logout()` yields a durable signed-out state. Google, social, and dev return `true`; Steam returns `false` (Steamworks identity returns on `autoLogin`). Defaults to `false` when the auth plugin omits the method. Games should hide Sign out UI when this is false.
+- **`platform.requiresEmail()`** — whether a complete identity needs email in addition to id. Google, social, and dev return `true`; Steam returns `false`. Defaults to `true` when unimplemented. Use instead of branching on `auth.name === 'steam'` for session completeness and account-sync routing.
+
 ## 3.13.0 — 2026-07-24
 
 ### Added

package/README.md

@@ -89,6 +89,34 @@ storage.set('playerName', 'Ada');
 storage.getObject('currentGame');
 ```
 
+### Analytics plugins
+
+| Plugin key | Registration | Runtime |
+|------------|--------------|---------|
+| `http-analytics` | `adaptfully.register('analytics', adaptfully.analytics.Http())` | Batches events to a first-party collector URL |
+| `noop-analytics` | `adaptfully.register('analytics', adaptfully.analytics.Noop())` | Same API; no network (dev / opt-out builds) |
+
+Register under the `analytics` key (same pattern as `auth` / `storage`). Point the HTTP plugin at your collector via Adaptfully **config**:
+
+| Config key | Purpose |
+|------------|---------|
+| `analyticsEndpoint` | `POST` URL for event batches (required for HTTP) |
+| `analyticsGameId` | Game id stamped on payloads (falls back to `window.gameConfig.id`) |
+| `analyticsEnabled` | Set `false` to disable without swapping plugins |
+| `analyticsPlatform` / `analyticsAppVersion` | Optional overrides; otherwise `window.gameConfig` |
+
+In-game:
+
+```javascript
+const analytics = adaptfully.get('analytics');
+analytics.setContext({ channel: 'web' });
+analytics.identify(accountId); // opaque id only — no emails
+analytics.track('game_start', { mapId: 28, players: 1 });
+analytics.optOut(); // persists via storage when registered
+```
+
+Games should call `adaptfully.has('analytics')` before `get` during rollout if older builds may omit the registration. Prefer named product events over fake page paths. Do not branch on Steam vs Capacitor for delivery — the HTTP plugin works across shells.
+
 ### Auth plugins
 
 | Plugin key | Registration | Runtime |
@@ -185,7 +213,7 @@ When `steam-auth` is registered on an **`electron`** platform, Adaptfully prebui
 - **`main.js`** — Electron shell with Steam overlay enabled and a preload script wired in
 - **`preload.js`** — initializes [steamworks.js](https://github.com/ceifa/steamworks.js) with `platforms.<name>.steamId` and exposes `window.__ADAPTFULLY_STEAMWORKS__`
 
-The renderer `steam-auth` plugin reads the Steam ID from that bridge. When Steam is available, `autoLogin()` succeeds immediately with `{ id: steamId64, email: '' }`. Optional config keys:
+The renderer `steam-auth` plugin reads the Steam ID from that bridge. When Steam is available, `autoLogin()` succeeds immediately with `{ id: steamId64, email: '' }`. `supportsLogout()` is `false` and `requiresEmail()` is `false` — games should not offer Sign out, and should treat id-only identity as complete. Optional config keys:
 
 | Key | Default | Purpose |
 |-----|---------|---------|
@@ -229,6 +257,9 @@ import {
 - **`runAdaptfullyStage('prebuild' | 'build' | 'deploy', platformKey, options)`** — run a pipeline stage programmatically.
 - **`platform.autoLogin(callback)`** — restore a prior session without UI when the auth plugin supports it (Google uses `lastLoggedIn` in storage and a cached OAuth token).
 - **`platform.supportsAutoLogin()`** — whether the active auth plugin can attempt automatic sign-in.
+- **`platform.logout(callback)`** — clear / revoke the platform session when supported.
+- **`platform.supportsLogout()`** — whether logout is a durable user-facing action. Steam returns `false` (identity is bound to the Steam client); Google, social, and dev return `true`. Prefer this over checking `auth.name` when showing Sign out UI.
+- **`platform.requiresEmail()`** — whether `getUser()` must include email for a complete session. Steam returns `false` (SteamID64 alone); Google, social, and dev return `true`. Prefer this over checking `auth.name` for session sync and account-link routing.
 
 ---
 

package/lib/node/registrations.js

@@ -38,6 +38,14 @@ export const STANDARD_PLUGINS = {
         scripts: ['core.js', 'storage/_helpers.js', 'storage/indexed-db.js'],
         registration: (key) => `adaptfully.register('${key}', adaptfully.storage.IndexedDB());`,
     },
+    'http-analytics': {
+        scripts: ['core.js', 'analytics/_helpers.js', 'analytics/http.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.analytics.Http());`,
+    },
+    'noop-analytics': {
+        scripts: ['core.js', 'analytics/_helpers.js', 'analytics/noop.js'],
+        registration: (key) => `adaptfully.register('${key}', adaptfully.analytics.Noop());`,
+    },
 };
 
 /** Default Wrapfully builder → config.platforms key */

package/lib/runtime/analytics/_helpers.js

@@ -0,0 +1,139 @@
+/* global window */
+
+/**
+ * Shared helpers for Adaptfully analytics plugins.
+ *
+ * Config keys (via adaptfully.get('config')):
+ *   analyticsEndpoint  — POST URL for event batches
+ *   analyticsGameId    — game id stamped on every event (e.g. 'entanglement')
+ *   analyticsEnabled   — when false, track is a no-op (default true when endpoint set)
+ *   analyticsPlatform  — optional override; else window.gameConfig.platform
+ *   analyticsAppVersion — optional override; else window.gameConfig.version / config.appVersion
+ */
+(function registerAnalyticsHelpers(ns) {
+    const OPT_OUT_KEY = 'adaptfully_analytics_opt_out';
+
+    const helpers = {
+        configValue(key, fallback) {
+            if (!ns.has('config')) {
+                return fallback;
+            }
+            const config = ns.get('config');
+            if (config && config[key] != null) {
+                return config[key];
+            }
+            return fallback;
+        },
+
+        getStorage() {
+            return ns.has('storage') ? ns.get('storage') : null;
+        },
+
+        readOptOut() {
+            const storage = helpers.getStorage();
+            if (!storage) {
+                return false;
+            }
+            try {
+                const raw = storage.get(OPT_OUT_KEY);
+                return raw === true || raw === 'true' || raw === '1';
+            } catch {
+                return false;
+            }
+        },
+
+        writeOptOut(value) {
+            const storage = helpers.getStorage();
+            if (!storage) {
+                return;
+            }
+            try {
+                if (value) {
+                    storage.set(OPT_OUT_KEY, 'true');
+                } else {
+                    storage.remove(OPT_OUT_KEY);
+                }
+            } catch {
+                // ignore quota / private browsing
+            }
+        },
+
+        resolvePlatform() {
+            const fromConfig = helpers.configValue('analyticsPlatform', null);
+            if (fromConfig) {
+                return String(fromConfig);
+            }
+            try {
+                if (typeof window !== 'undefined' && window.gameConfig && window.gameConfig.platform) {
+                    return String(window.gameConfig.platform);
+                }
+            } catch {
+                // ignore
+            }
+            return 'unknown';
+        },
+
+        resolveAppVersion() {
+            const fromConfig = helpers.configValue('analyticsAppVersion', null)
+                || helpers.configValue('appVersion', null);
+            if (fromConfig) {
+                return String(fromConfig);
+            }
+            try {
+                if (typeof window !== 'undefined' && window.gameConfig && window.gameConfig.version) {
+                    return String(window.gameConfig.version);
+                }
+            } catch {
+                // ignore
+            }
+            return '';
+        },
+
+        resolveGameId() {
+            const fromConfig = helpers.configValue('analyticsGameId', null);
+            if (fromConfig) {
+                return String(fromConfig);
+            }
+            try {
+                if (typeof window !== 'undefined' && window.gameConfig && window.gameConfig.id) {
+                    return String(window.gameConfig.id);
+                }
+            } catch {
+                // ignore
+            }
+            return 'unknown';
+        },
+
+        createSessionId() {
+            try {
+                if (typeof crypto !== 'undefined' && crypto.randomUUID) {
+                    return crypto.randomUUID();
+                }
+            } catch {
+                // ignore
+            }
+            return `s_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 10)}`;
+        },
+
+        sanitizeProps(props) {
+            if (!props || typeof props !== 'object' || Array.isArray(props)) {
+                return {};
+            }
+            const out = {};
+            for (const [key, value] of Object.entries(props)) {
+                if (value === undefined) {
+                    continue;
+                }
+                const t = typeof value;
+                if (t === 'string' || t === 'number' || t === 'boolean' || value === null) {
+                    out[key] = value;
+                }
+            }
+            return out;
+        },
+    };
+
+    ns.analytics = ns.analytics || {};
+    ns.analytics.helpers = helpers;
+    ns.analytics.OPT_OUT_KEY = OPT_OUT_KEY;
+}(window.adaptfully));

package/lib/runtime/analytics/http.js

@@ -0,0 +1,180 @@
+/* global window, navigator, fetch, Blob */
+
+(function registerHttpAnalytics(ns) {
+    const {helpers} = ns.analytics;
+    const MAX_QUEUE = 50;
+    const FLUSH_MS = 2000;
+    const MAX_BATCH = 20;
+
+    /**
+     * HTTP analytics — batches events to config.analyticsEndpoint.
+     * Works on web (https), Electron file://, and Capacitor schemes via fetch.
+     */
+    ns.analytics.Http = function httpAnalyticsFactory() {
+        const sessionId = helpers.createSessionId();
+        let userId = null;
+        let context = {};
+        let optedOut = helpers.readOptOut();
+        /** @type {object[]} */
+        let queue = [];
+        let flushTimer = null;
+        let flushing = false;
+
+        function isEnabled() {
+            if (optedOut) {
+                return false;
+            }
+            const enabled = helpers.configValue('analyticsEnabled', null);
+            if (enabled === false || enabled === 'false') {
+                return false;
+            }
+            const endpoint = helpers.configValue('analyticsEndpoint', '');
+            return typeof endpoint === 'string' && endpoint.length > 0;
+        }
+
+        function baseProps() {
+            return {
+                game: helpers.resolveGameId(),
+                platform: helpers.resolvePlatform(),
+                appVersion: helpers.resolveAppVersion(),
+                sessionId,
+                ...context,
+            };
+        }
+
+        function scheduleFlush() {
+            if (flushTimer != null || flushing) {
+                return;
+            }
+            flushTimer = setTimeout(() => {
+                flushTimer = null;
+                flush();
+            }, FLUSH_MS);
+        }
+
+        function deliver(body) {
+            const endpoint = helpers.configValue('analyticsEndpoint', '');
+            if (!endpoint) {
+                return;
+            }
+            const payload = JSON.stringify(body);
+            try {
+                if (typeof navigator !== 'undefined'
+                    && typeof navigator.sendBeacon === 'function') {
+                    const blob = new Blob([payload], {type: 'application/json'});
+                    if (navigator.sendBeacon(endpoint, blob)) {
+                        return;
+                    }
+                }
+            } catch {
+                // fall through to fetch
+            }
+            try {
+                fetch(endpoint, {
+                    method: 'POST',
+                    headers: {'Content-Type': 'application/json'},
+                    body: payload,
+                    keepalive: true,
+                    mode: 'cors',
+                    credentials: 'omit',
+                }).catch(() => {
+                    // drop on failure — do not block gameplay
+                });
+            } catch {
+                // ignore
+            }
+        }
+
+        function flush() {
+            if (flushing || queue.length === 0 || !isEnabled()) {
+                return;
+            }
+            flushing = true;
+            const batch = queue.splice(0, MAX_BATCH);
+            const body = {
+                game: helpers.resolveGameId(),
+                platform: helpers.resolvePlatform(),
+                appVersion: helpers.resolveAppVersion(),
+                sessionId,
+                userId: userId || undefined,
+                events: batch,
+            };
+            deliver(body);
+            flushing = false;
+            if (queue.length > 0) {
+                scheduleFlush();
+            }
+        }
+
+        return {
+            name: 'http',
+
+            track(name, props) {
+                if (!name || typeof name !== 'string' || !isEnabled()) {
+                    return;
+                }
+                const event = {
+                    name: String(name).slice(0, 64),
+                    ts: Date.now(),
+                    props: {
+                        ...baseProps(),
+                        ...helpers.sanitizeProps(props),
+                    },
+                    sessionId,
+                    userId: userId || undefined,
+                };
+                queue.push(event);
+                if (queue.length > MAX_QUEUE) {
+                    queue = queue.slice(-MAX_QUEUE);
+                }
+                if (queue.length >= MAX_BATCH) {
+                    if (flushTimer != null) {
+                        clearTimeout(flushTimer);
+                        flushTimer = null;
+                    }
+                    flush();
+                } else {
+                    scheduleFlush();
+                }
+            },
+
+            identify(id) {
+                userId = id == null || id === '' ? null : String(id).slice(0, 128);
+            },
+
+            setContext(partial) {
+                if (!partial || typeof partial !== 'object') {
+                    return;
+                }
+                context = {...context, ...helpers.sanitizeProps(partial)};
+            },
+
+            optOut() {
+                optedOut = true;
+                helpers.writeOptOut(true);
+                queue = [];
+                if (flushTimer != null) {
+                    clearTimeout(flushTimer);
+                    flushTimer = null;
+                }
+            },
+
+            optIn() {
+                optedOut = false;
+                helpers.writeOptOut(false);
+            },
+
+            isOptedOut() {
+                return optedOut;
+            },
+
+            /** Flush pending events immediately (page hide / tests). */
+            flush,
+
+            /** @internal test/debug */
+            _getState() {
+                return {userId, context, optedOut, queue: queue.slice(), sessionId};
+            },
+        };
+    };
+}(window.adaptfully));

package/lib/runtime/analytics/noop.js

@@ -0,0 +1,53 @@
+/* global window */
+
+(function registerNoopAnalytics(ns) {
+    const {helpers} = ns.analytics;
+
+    /**
+     * No-op analytics — same surface as http-analytics, no network.
+     * Use for local/dev platforms or privacy-off builds.
+     */
+    ns.analytics.Noop = function noopAnalyticsFactory() {
+        let userId = null;
+        let context = {};
+        let optedOut = helpers.readOptOut();
+
+        return {
+            name: 'noop',
+
+            track(_name, _props) {
+                // intentionally empty
+            },
+
+            identify(id) {
+                userId = id == null || id === '' ? null : String(id);
+            },
+
+            setContext(partial) {
+                if (!partial || typeof partial !== 'object') {
+                    return;
+                }
+                context = {...context, ...helpers.sanitizeProps(partial)};
+            },
+
+            optOut() {
+                optedOut = true;
+                helpers.writeOptOut(true);
+            },
+
+            optIn() {
+                optedOut = false;
+                helpers.writeOptOut(false);
+            },
+
+            isOptedOut() {
+                return optedOut;
+            },
+
+            /** @internal test/debug */
+            _getState() {
+                return {userId, context, optedOut};
+            },
+        };
+    };
+}(window.adaptfully));

package/lib/runtime/auth/_helpers.js

@@ -11,6 +11,8 @@
  * @property {(callback: AuthCallback) => void} login
  * @property {(callback: AuthCallback) => void} autoLogin
  * @property {() => boolean} [supportsAutoLogin]
+ * @property {() => boolean} [supportsLogout] — durable signed-out state (false for Steamworks-bound identity)
+ * @property {() => boolean} [requiresEmail] — whether getUser() must include email for a complete session
  * @property {(callback: () => void) => void} logout
  * @property {() => AuthUser | null} getUser
  * @property {() => boolean} isAuthenticated

package/lib/runtime/auth/dev-auth.js

@@ -58,6 +58,14 @@
             return true;
         }
 
+        supportsLogout() {
+            return true;
+        }
+
+        requiresEmail() {
+            return true;
+        }
+
         logout(callback) {
             const storage = getStorage();
             this.authenticated = false;

package/lib/runtime/auth/google-auth.js

@@ -21,6 +21,14 @@
             return true;
         }
 
+        supportsLogout() {
+            return true;
+        }
+
+        requiresEmail() {
+            return true;
+        }
+
         #tokenKey() {
             return configValue('googleTokenKey', DEFAULT_TOKEN_KEY);
         }

package/lib/runtime/auth/social-auth.js

@@ -74,6 +74,14 @@
             return true;
         }
 
+        supportsLogout() {
+            return true;
+        }
+
+        requiresEmail() {
+            return true;
+        }
+
         #autoLoginStorageKey() {
             return configValue('autoLoginStorageKey', DEFAULT_AUTO_LOGIN_KEY);
         }

package/lib/runtime/auth/steam-auth.js

@@ -118,6 +118,14 @@
             return true;
         }
 
+        supportsLogout() {
+            return false;
+        }
+
+        requiresEmail() {
+            return false;
+        }
+
         #autoLoginStorageKey() {
             return configValue('autoLoginStorageKey', DEFAULT_AUTO_LOGIN_KEY);
         }

package/lib/runtime/platform.js

@@ -78,6 +78,27 @@
                 : typeof this.auth.autoLogin === 'function';
         }
 
+        /**
+         * Whether logout() yields a durable signed-out state for this auth backend.
+         * Games should hide Sign out UI when this is false (e.g. Steam).
+         * Defaults to false when the plugin does not implement the method.
+         */
+        supportsLogout() {
+            return typeof this.auth.supportsLogout === 'function'
+                ? this.auth.supportsLogout()
+                : false;
+        }
+
+        /**
+         * Whether a complete identity requires email in addition to id.
+         * Id-only backends (Steam) return false. Defaults to true when unimplemented.
+         */
+        requiresEmail() {
+            return typeof this.auth.requiresEmail === 'function'
+                ? this.auth.requiresEmail()
+                : true;
+        }
+
         logout(callback) {
             this.whenReady(() => {
                 this.auth.logout(() => {

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@makefully/adaptfully",
-    "version": "3.13.0",
+    "version": "3.15.0",
     "description": "Platform abstraction and Wrapfully deploy client for Makefully games",
     "type": "module",
     "main": "./lib/node/index.js",