npm - @makefully/adaptfully - Versions diffs - 3.14.0 → 3.15.1 - Mend

@makefully/adaptfully 3.14.0 → 3.15.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/CHANGELOG.md +13 -0
package/README.md +28 -0
package/lib/node/packagers/base.js +93 -23
package/lib/node/registrations.js +8 -0
package/lib/runtime/analytics/_helpers.js +139 -0
package/lib/runtime/analytics/http.js +180 -0
package/lib/runtime/analytics/noop.js +53 -0
package/package.json +1 -1

package/CHANGELOG.md CHANGED Viewed

@@ -2,6 +2,19 @@
 All notable changes to this project are documented in this file.
+## 3.15.1 — 2026-09-01
+### Fixed
+- **Capacitor/Cordova HTML injection** — packager `<meta>` tags (CSP, viewport) are injected into `<head>`; script tags stay in the body `<!-- adaptfully -->` slot. Fixes browsers ignoring CSP delivered outside `<head>`.
+## 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 CHANGED Viewed

@@ -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/packagers/base.js CHANGED Viewed

@@ -11,6 +11,8 @@ export const VALID_PACKAGERS = ['web', 'electron', 'cordova', 'capacitor'];
 const PACKAGER_MARKER = '<!-- adaptfully-packager -->';
 const PACKAGER_END_MARKER = '<!-- /adaptfully-packager -->';
+const HEAD_PACKAGER_MARKER = '<!-- adaptfully-packager-head -->';
+const HEAD_PACKAGER_END_MARKER = '<!-- /adaptfully-packager-head -->';
 /**
  * @typedef {Object} PackagerOptions
@@ -58,21 +60,64 @@ function writeGameConfig(dest, platformKey, pkg, log) {
 /**
  * @param {string} html
+ * @param {string} marker
+ * @param {string} endMarker
  * @param {string} injection
  */
-function injectPackagerExtras(html, injection) {
-    if (!injection) {
-        return html;
-    }
+function replaceMarkedBlock(html, marker, endMarker, injection) {
     const markerPattern = new RegExp(
-        `${escapeRegExp(PACKAGER_MARKER)}[\\s\\S]*?${escapeRegExp(PACKAGER_END_MARKER)}\\n?`,
+        `${escapeRegExp(marker)}[\\s\\S]*?${escapeRegExp(endMarker)}\\n?`,
     );
     if (markerPattern.test(html)) {
         return html.replace(markerPattern, injection);
     }
+    if (html.includes(marker)) {
+        return html.replace(marker, `${injection}${marker}`);
+    }
+    return html;
+}
+/**
+ * @param {string} html
+ * @param {string} injection
+ */
+function injectHeadPackagerExtras(html, injection) {
+    if (!injection) {
+        return html;
+    }
+    let updated = replaceMarkedBlock(html, HEAD_PACKAGER_MARKER, HEAD_PACKAGER_END_MARKER, injection);
+    if (updated === html && html.includes('</head>')) {
+        updated = html.replace('</head>', `${injection}</head>`);
+    } else if (updated === html) {
+        throw new Error(
+            'Cannot inject packager head extras: HTML needs '
+            + `${HEAD_PACKAGER_MARKER}…${HEAD_PACKAGER_END_MARKER} or </head>`,
+        );
+    }
+    return updated;
+}
+/**
+ * @param {string} html
+ * @param {string} injection
+ */
+function injectBodyPackagerExtras(html, injection) {
+    if (!injection) {
+        return html;
+    }
+    let updated = replaceMarkedBlock(html, PACKAGER_MARKER, PACKAGER_END_MARKER, injection);
+    if (updated !== html) {
+        return updated;
+    }
     if (html.includes(PACKAGER_MARKER)) {
         return html.replace(PACKAGER_MARKER, `${injection}${PACKAGER_MARKER}`);
     }
@@ -85,17 +130,36 @@ function injectPackagerExtras(html, injection) {
         return html.replace('<!-- scripts -->', `${injection}<!-- scripts -->`);
     }
-    if (html.includes('</head>')) {
-        return html.replace('</head>', `${injection}</head>`);
+    if (html.includes('</body>')) {
+        return html.replace('</body>', `${injection}</body>`);
     }
     throw new Error(
-        'Cannot inject packager extras: HTML needs '
+        'Cannot inject packager body extras: HTML needs '
         + '<!-- adaptfully-packager -->…<!-- /adaptfully-packager -->, '
-        + '<!-- adaptfully -->, <!-- scripts -->, or </head>',
+        + '<!-- adaptfully -->, <!-- scripts -->, or </body>',
     );
 }
+/**
+ * @param {string} html
+ * @param {{ head?: string, body?: string }} injection
+ */
+function injectPackagerExtras(html, injection) {
+    if (!injection?.head && !injection?.body) {
+        return html;
+    }
+    let updated = html;
+    if (injection.head) {
+        updated = injectHeadPackagerExtras(updated, injection.head);
+    }
+    if (injection.body) {
+        updated = injectBodyPackagerExtras(updated, injection.body);
+    }
+    return updated;
+}
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -243,22 +307,28 @@ export class Packager {
     /**
      * @param {string[]} headExtras
      * @param {string[]} bodyScripts
-     * @returns {string}
+     * @returns {{ head: string, body: string }}
      */
     formatHtmlInjection(headExtras, bodyScripts) {
-        if (headExtras.length === 0 && bodyScripts.length === 0) {
-            return '';
+        let head = '';
+        if (headExtras.length > 0) {
+            head = `${HEAD_PACKAGER_MARKER}\n`;
+            for (const extra of headExtras) {
+                head += `${extra}\n`;
+            }
+            head += `${HEAD_PACKAGER_END_MARKER}\n`;
         }
-        let block = `${PACKAGER_MARKER}\n`;
-        for (const extra of headExtras) {
-            block += `${extra}\n`;
-        }
-        for (const script of bodyScripts) {
-            block += `${script}\n`;
+        let body = '';
+        if (bodyScripts.length > 0) {
+            body = `${PACKAGER_MARKER}\n`;
+            for (const script of bodyScripts) {
+                body += `${script}\n`;
+            }
+            body += `${PACKAGER_END_MARKER}\n`;
         }
-        block += `${PACKAGER_END_MARKER}\n`;
-        return block;
+        return { head, body };
     }
     /** @param {string} dest */
@@ -268,7 +338,7 @@ export class Packager {
         }
     }
-    /** @returns {string} */
+    /** @returns {{ head: string, body: string }} */
     buildHtmlInjection() {
         const bodyScripts = [];
         if (this.needsGameConfig()) {
@@ -283,7 +353,7 @@ export class Packager {
      */
     applyHtmlExtras(dest, htmlPaths) {
         const injection = this.buildHtmlInjection();
-        if (!injection) {
+        if (!injection.head && !injection.body) {
             return;
         }

package/lib/node/registrations.js CHANGED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 ADDED Viewed

@@ -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 CHANGED Viewed

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