Which route fits a GDevelop game?

A JavaScript code event. The network action has a content type field and no header field, and the collector needs the key in the x-publishable-key header. A JavaScript code event can call the browser fetch(), which sets any header.

The code uses gdjs.evtTools.storage, the same storage that the Storage actions use, so your events can still read the values. Put it under an At the beginning of the scene event in your first scene. A JavaScript code event runs each time the event is reached, so the code guards itself with if (!globalThis.Manalens).

Sources: GDevelop wiki, Network actions reference, JavaScript code events and Storage; GDJS runtime documentation, gdjs.evtTools.storage.

What must every GDevelop 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 GDevelop?

Create a global variable named UA_tmp first: the storage read function writes into a variable. Then add the code below as a JavaScript code event. It saves the ID, the first open time, the consent flag and the queue in a storage named manalens.

JavaScript code event (first scene, At the beginning of the scene)

if (!globalThis.Manalens) {
  const MANALENS_URL = 'https://YOUR_COLLECTOR_ENDPOINT/v0/events';
  const MANALENS_KEY = 'YOUR_PUBLISHABLE_KEY';
  const WEEK_MS = 7 * 24 * 3600 * 1000;
  const ST = gdjs.evtTools.storage;
  const tmp = runtimeScene.getGame().getVariables().get('UA_tmp');
  const read = k => { if (!ST.elementExistsInJSONFile('manalens', k)) return null;
    ST.readStringFromJSONFile('manalens', k, null, tmp); return tmp.getAsString(); };
  const write = (k, v) => ST.writeStringInJSONFile('manalens', k, v);
  const S = { consent: read('consent') === '1', anonId: null, sessionId: null, queue: [], busy: false, backoff: 2000 };

  const 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 = () => write('queue', JSON.stringify(S.queue));

  const 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();
  };

  const flush = async () => {
    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); saveQueue(); S.backoff = 2000;
    if (status >= 200 && status < 300) flush();
  };

  const setConsent = on => {
    S.consent = on;
    write('consent', on ? '1' : '0');
    if (!on) { S.queue = []; S.anonId = null;
      ['anon_id', 'first_open_at', 'queue'].forEach(k => ST.deleteElementFromJSONFile('manalens', k)); return; }
    S.anonId = read('anon_id');
    const first = !S.anonId;
    if (first) { S.anonId = uuid4(); write('anon_id', S.anonId); write('first_open_at', new Date().toISOString()); }
    try { S.queue = JSON.parse(read('queue') || '[]'); } catch (e) { S.queue = []; }
    S.sessionId = uuid4();
    track('game_open', { is_first_open: first, first_open_at: read('first_open_at') });
    track('session_start');
    flush();
  };

  globalThis.Manalens = { track, setConsent, flush };
  if (S.consent) setConsent(true);
  setInterval(flush, 30000);
}

Sources: GDevelop wiki, JavaScript code events; GDJS runtime documentation, gdjs.evtTools.storage, RuntimeGame, VariablesContainer and Variable; MDN, fetch().

How do I track events from my event sheets?

Add a small JavaScript code event under the condition that marks the moment, such as a collision with the goal or a click on the consent button. Use the event conventions, such as level_start, level_complete and resource, so the Game KPIs board reads them.

GDevelop documents no quit or focus loss condition, so this setup sends no session_end. Queued events are saved on every track() call and go out at the next launch.

JavaScript code events

// Condition: Player is in collision with Goal (Trigger once)
// JavaScript code event:
Manalens.track('level_complete', { level: 3, attempt: 1, score: 1200 });
Manalens.flush();

// Condition: Cursor/touch is on ConsentYes, and Left mouse button released
// JavaScript code event:
Manalens.setConsent(true);

Sources: GDevelop wiki, JavaScript code events; GDJS runtime documentation, RuntimeGame; Manalens app events documentation.

What changes for web, desktop and mobile builds?

GDevelop publishes to gd.games, to web portals such as itch.io, Poki and CrazyGames, to Android and iOS, and to Windows, macOS and Linux with Electron.

  • Web: the wiki says browsers block cross domain requests unless the server allows them. The collector answers the CORS preflight for your project domain, its subdomains and Allowed origins. *.itch.zone is allowed by default.
  • gd.games and other portals: add the host that serves the game files to Allowed origins. A host that is not on the list gets 403.
  • Desktop (Electron) and mobile (Cordova) 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.
  • Use an https:// endpoint. The wiki recommends https for requests, and mobile platforms block cleartext HTTP by default.
  • Storage on the web is per browser. A player who clears site data, including on itch.io, gets a new anonymous ID.

Sources: GDevelop wiki, Publishing, Network and Storage; Manalens app events documentation.

What are the GDevelop gotchas?

These come from the GDevelop wiki and from first tests.

  • Send a request to a web page has no header field, so it cannot send the Publishable key. Use the JavaScript code event.
  • That action also defaults to application/x-www-form-urlencoded. If you use it for any JSON API, set the content type to application/json.
  • A JavaScript code event runs every time it is reached, which is every frame in a normal event. Put setup under At the beginning of the scene and keep the globalThis guard, or you start a new session each frame.
  • The network action reports REQUEST_NOT_SENT both when the player is offline and when CORS blocks the request. A 403 from the origin check can look like a lost connection.
  • Preview storage stays after a preview and after GDevelop closes. To test a first open again, clear the storage in the preview developer tools.

Sources: GDevelop wiki, Network actions reference, JavaScript code events and Storage.

How do I check that GDevelop events arrive?

Send one batch from a development build and read the response status. Open the preview developer tools: the OPTIONS preflight should succeed before the POST, and the console should show no CORS error.

  1. Create a test project in Manalens and copy its Publishable key.
  2. Run a preview with localhost in the Allowed origins of a test project, or upload a draft build to itch.io.
  3. Send game_open and session_start from the GDevelop 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 JavaScript code event to your first scene, ask for consent, and use the Game KPIs board to see D1 retention and level fail rates.

Sources: Manalens product documentation.

Frequently asked questions

Can GDevelop send analytics without JavaScript?

Not to this collector. The Send a request to a web page action has fields for the URL, the body, the method and the content type, but no custom headers. The collector needs the Publishable key in the x-publishable-key header, so use a JavaScript code event with fetch() for the send.

Where does GDevelop store the player ID?

In GDevelop storage, which the code reads and writes with gdjs.evtTools.storage. On the web it is the browser LocalStorage. On desktop it sits in the Local Storage folder of the game. The Storage actions in your event sheets can read the same values, for example the consent flag.

Why does my GDevelop request say REQUEST_NOT_SENT?

That value covers both an offline player and a request that the browser blocked. For this collector, a block usually means the game host is not your project domain or in Allowed origins. Add the host that serves your game files, or test on itch.io, which is allowed by default.

Does the code work in GDevelop desktop exports?

It can. Desktop exports use Electron and mobile exports use Cordova, so they run in a browser engine and may send an Origin header. The collector accepts an http or https Origin on your domain or in Allowed origins. Test one real export of each target before launch.

Sources and implementation