Which route fits a Construct 3 game?

A main script file with fetch(). Construct 3 runs your game in a browser engine on every export, and its manual points script code to the browser Fetch API. Event sheets can call the functions that the script puts on globalThis.

Event sheet only? The AJAX plugin can post too: Set request header for Content-Type and x-publishable-key, then Post to URL with a tag, the JSON text and the POST method. Read AJAX.LastStatusCode in On completed. The manual says request headers are cleared after each request, so set both again before every post.

Sources: Construct 3 manual, AJAX plugin, Scripting overview and Script files.

What must every Construct 3 event contain?

One JSON envelope, the same one the Godot and Unity SDKs send. POST it to /v0/events on your collector with two headers: x-publishable-key and Content-Type: application/json. The body is {"events": [...]} with 1 to 50 events. A good request returns {"accepted":N}.

  • type "track", an event name in snake_case, channel "app" and version (your tracker version, up to 32 characters).
  • message_id: a new UUID version 4 for each event. Keep it on a retry. The collector counts each message_id once.
  • anonymous_id: one UUID version 4 per install, saved on the device. The collector checks the version digit, so a random hex string of the same length is refused.
  • session_id: 1 to 64 characters of letters, digits and . _ : -. Start a new one after 30 minutes without play.
  • original_timestamp: the time of the event in ISO 8601 UTC, such as 2026-11-09T10:00:00Z. It can be up to 7 days old, and at most 10 minutes in the future.
  • context.app.platform (windows, macos, linux, web, android, ios or other) and engine "other". Add storefront, app_version and build to filter reports by build.
  • properties: a flat object of strings, numbers, booleans or null.

Sources: Manalens app events documentation.

How do I send events from Construct 3?

Add this to the main script file of your project. runOnStartup() gives the runtime. runtime.storage is the IStorage interface, a key-value store based on IndexedDB that the Local Storage plugin also uses. Its calls are async, so the code awaits them.

The suspend event fires when the game goes to the background. The code sends session_end there and flushes the queue.

JavaScript (main script file)

const MANALENS_URL = 'https://YOUR_COLLECTOR_ENDPOINT/v0/events';
const MANALENS_KEY = 'YOUR_PUBLISHABLE_KEY';
const WEEK_MS = 7 * 24 * 3600 * 1000;
const S = { rt: null, consent: false, anonId: null, sessionId: null, queue: [], busy: false, backoff: 2000, startMs: 0 };

function uuid4() {
  const b = crypto.getRandomValues(new Uint8Array(16));
  b[6] = (b[6] & 0x0f) | 0x40; b[8] = (b[8] & 0x3f) | 0x80;
  const h = Array.from(b, x => x.toString(16).padStart(2, '0')).join('');
  return `${h.slice(0, 8)}-${h.slice(8, 12)}-${h.slice(12, 16)}-${h.slice(16, 20)}-${h.slice(20)}`;
}
const saveQueue = () => S.rt.storage.setItem('mana_queue', S.queue);

function track(event, properties = {}) {
  if (!S.consent) return;
  S.queue.push({ type: 'track', event, channel: 'app', version: '0.1.0',
    message_id: uuid4(), anonymous_id: S.anonId, session_id: S.sessionId,
    original_timestamp: new Date().toISOString(),
    context: { app: { platform: 'web', storefront: 'itch', app_version: '1.4.0', build: '571', engine: 'other' },
               locale: 'en', library_name: 'my-game', library_version: '1.4.0' },
    properties });
  saveQueue();
  if (S.queue.length >= 50) flush();
}

async function flush() {
  if (!S.consent || S.busy) return;
  S.queue = S.queue.filter(e => Date.now() - Date.parse(e.original_timestamp) < WEEK_MS);
  const batch = S.queue.slice(0, 50);
  if (!batch.length) return;
  S.busy = true;
  let status = 0;
  try {
    const res = await fetch(MANALENS_URL, { method: 'POST',
      headers: { 'Content-Type': 'application/json', 'x-publishable-key': MANALENS_KEY },
      body: JSON.stringify({ events: batch }) });
    status = res.status;
  } catch (e) { status = 0; } // offline, or refused by CORS
  S.busy = false;
  if (!S.consent) return;
  if (status === 0 || status >= 500 || status === 408 || status === 429) {
    setTimeout(flush, S.backoff); S.backoff = Math.min(S.backoff * 2, 300000); return;
  }
  S.queue.splice(0, batch.length); await saveQueue(); S.backoff = 2000;
  if (status >= 200 && status < 300) flush();
}

async function setConsent(on) {
  const st = S.rt.storage;
  S.consent = on;
  await st.setItem('mana_consent', on);
  if (!on) {
    S.queue = []; S.anonId = null;
    await st.removeItem('mana_anon_id'); await st.removeItem('mana_first_open_at'); await st.removeItem('mana_queue');
    return;
  }
  S.anonId = await st.getItem('mana_anon_id');
  const first = !S.anonId;
  if (first) {
    S.anonId = uuid4();
    await st.setItem('mana_anon_id', S.anonId);
    await st.setItem('mana_first_open_at', new Date().toISOString());
  }
  S.queue = (await st.getItem('mana_queue')) || [];
  S.sessionId = uuid4(); S.startMs = Date.now();
  track('game_open', { is_first_open: first, first_open_at: await st.getItem('mana_first_open_at') });
  track('session_start');
  flush();
}

runOnStartup(async runtime => {
  S.rt = runtime;
  globalThis.Manalens = { track, setConsent, flush };
  if ((await runtime.storage.getItem('mana_consent')) === true) await setConsent(true);
  runtime.addEventListener('suspend', () => {
    track('session_end', { duration_s: Math.round((Date.now() - S.startMs) / 1000) });
    flush();
  });
  setInterval(flush, 30000);
});

Sources: Construct 3 manual, Script files, IRuntime and IStorage; MDN, fetch() and Crypto.getRandomValues().

How do I track events from an event sheet?

Add a script action to any event. The functions are on globalThis.Manalens, so an event sheet can call them by name. Use the event conventions, such as level_start, level_complete and resource, so the Game KPIs board reads them.

JavaScript (script action in an event sheet)

// Event: Player, On collision with Goal
// Action: Add script
Manalens.track('level_complete', { level: 3, attempt: 1, score: 1200 });
Manalens.flush();

// Event: ConsentYes, On clicked
// Action: Add script
Manalens.setConsent(true);

Sources: Construct 3 manual, Script files and Scripting overview; Manalens app events documentation.

What changes for web, desktop and mobile builds?

Construct 3 exports to the web, to Android and iOS through the build service or a Cordova project, and to Windows (WebView2), macOS (WKWebView) and Linux (CEF). The manual says NW.js exports were retired in r450.

  • Web: the x-publishable-key header causes a CORS preflight. The collector answers it for your project domain, its subdomains and Allowed origins. *.itch.zone is allowed by default, so itch.io uploads work.
  • Preview: Construct previews from https://preview.construct.net. Add preview.construct.net to Allowed origins in your test project only, or every preview request gets 403.
  • Desktop and mobile exports run in a browser engine, so they can send an Origin header too. The collector accepts only an http or https Origin on your project domain or in Allowed origins, and refuses a null Origin or another scheme with 403. Test one real export of each target before launch, and read the Origin of the request in the developer tools.
  • Mixed content: preview and most exports are HTTPS, so an http:// collector URL is blocked. Use https://.
  • Worker mode: when Construct runs the game in a web worker, there is no window or document. fetch(), IndexedDB and timers still work, which is why the code uses globalThis and runtime events.

Sources: Construct 3 manual, Publishing projects, AJAX plugin and Scripting overview; Construct tutorials, Exporting desktop apps; Manalens app events documentation.

What are the Construct 3 gotchas?

Most of these show up in the first preview.

  • The AJAX Set request header action clears its headers after each request. Set Content-Type and x-publishable-key again before every Post to URL.
  • Preview runs on preview.construct.net, which is not your domain. Until you add it to Allowed origins in a test project, every preview send fails with 403.
  • Local Storage and runtime.storage are async. A clear can race with a write, so on consent off wait for the remove calls before you write again, as setConsent() does with await.
  • In worker mode, window is undefined. Use globalThis and runtime.addEventListener() instead of window listeners.
  • Advanced minification can rename properties in script code. Keep string keys, as in the code, or export with simple minification.

Sources: Construct 3 manual, AJAX plugin, Local Storage plugin, Scripting overview and Publishing projects.

How do I check that Construct 3 events arrive?

Send one batch from a development build and read the response status. In the browser developer tools, the OPTIONS preflight should succeed before the POST. Then export once for each target you ship and check one batch from each.

  1. Create a test project in Manalens and copy its Publishable key.
  2. Add preview.construct.net to Allowed origins in a test project and run a preview.
  3. Send game_open and session_start from the Construct 3 build, then check that the response is {"accepted":2}.
  4. Open the activity feed and check that platform, build and engine are set on the events.
  5. Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
  6. Replace the test key with the production Publishable key before you ship.

Sources: Manalens app events documentation.

How do I start?

Manalens is the analytics and growth engine built for games. Add the main script to your Construct project, ask for consent, and compare retention and level fail rates between your web and desktop builds.

Sources: Manalens product documentation.

Frequently asked questions

Should I use the AJAX plugin or fetch in Construct 3?

Either works. The manual says the AJAX object has no script interface because scripts can use the browser Fetch API, so script code uses fetch(). In event sheets, set both request headers before every Post to URL, because the AJAX plugin clears them after each request.

Why does my Construct preview get a 403 response?

Because the preview runs on preview.construct.net, which is not your project domain. The collector accepts browser requests only from your domain, its subdomains and Allowed origins. Add preview.construct.net to Allowed origins in a separate test project, so test data stays out of your real reports.

Where does Construct 3 save the player ID?

In runtime.storage, the key-value store based on IndexedDB that the Local Storage plugin also uses. The manual says it is unique per project, and that desktop and mobile exports keep their own storage. The calls are async, so await them before you read the ID.

Do Construct desktop exports need Allowed origins?

They can. Desktop and mobile exports run in a browser engine, which may send an Origin header. The collector accepts an http or https Origin on your domain or in Allowed origins and refuses a null Origin. Test one real export of each target and check the response.

Sources and implementation