@makefully/adaptfully 3.14.0 → 3.15.0

package/CHANGELOG.md

@@ -2,6 +2,13 @@
 
 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

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 |

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/package.json

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