# How to add analytics to a GDevelop game

> Add analytics to a GDevelop game with a JavaScript code event: fetch with the key header, a saved player ID, a storage queue, consent and export notes.

By Yos Riady. Updated 2026-11-18. Published 2026-11-18. Canonical URL: https://manalens.dev/blog/gdevelop-analytics

Use a JavaScript code event with fetch() to post events to /v0/events, up to 50 per request. The GDevelop action Send a request to a web page takes a URL, a body, a method and a content type, but no custom headers (GDevelop wiki), so it cannot send your Publishable key. Keep the ID and queue in GDevelop storage.

## Key points

- The GDevelop action Send a request to a web page has no header field, so use a JavaScript code event with fetch() to send the Publishable key.
- Put the GDevelop analytics code under At the beginning of the scene and keep the globalThis guard, or each frame starts a new session.
- A GDevelop REQUEST_NOT_SENT result can mean an offline player or a CORS block, so add the host of your game files to Allowed origins.

## 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.

## How do the player ID, the offline queue and consent work?

The manalens storage keeps consent, anon_id, first_open_at and the queue as text. The GDevelop wiki says storage on the web is the browser LocalStorage, and that desktop builds keep it in the Local Storage folder of the game, such as %USERPROFILE%\AppData\Roaming plus the game name on Windows.

Keep the batch and wait longer before each retry after a network error or a 5xx, 408 or 429 response. Drop it after any other 4xx, because the collector refused the data and a retry gets the same answer. The flush also drops events older than 7 days, because one old event refuses the whole batch with 400.

Until consent is 1, track() does nothing and no ID is written. setConsent(false) deletes the ID, the first open time and the queue. Whether your game needs consent is a decision for you and your legal advisers.

Sources: GDevelop wiki, Storage; GDJS runtime documentation, gdjs.evtTools.storage; 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.

- [All installation options](https://manalens.dev/docs/install)

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

- [GDevelop wiki: Network (read 18 November 2026)](https://wiki.gdevelop.io/gdevelop5/all-features/network/)
- [GDevelop wiki: Network actions reference (read 18 November 2026)](https://wiki.gdevelop.io/gdevelop5/all-features/network/reference/)
- [GDevelop wiki: JavaScript code events (read 18 November 2026)](https://wiki.gdevelop.io/gdevelop5/events/js-code/)
- [GDevelop wiki: Storage (read 18 November 2026)](https://wiki.gdevelop.io/gdevelop5/all-features/storage/)
- [GDevelop wiki: Publishing (read 18 November 2026)](https://wiki.gdevelop.io/gdevelop5/publishing/)
- [GDJS runtime documentation: gdjs.evtTools.storage (read 18 November 2026)](https://docs.gdevelop.io/GDJS%20Runtime%20Documentation/modules/gdjs.evtTools.storage.html)
- [GDJS runtime documentation: RuntimeGame (read 18 November 2026)](https://docs.gdevelop.io/GDJS%20Runtime%20Documentation/classes/gdjs.RuntimeGame.html)

## Related guides

- [Game marketing measurement guide](https://manalens.dev/blog/game-marketing-measurement-guide)
- [Engine analytics compared: Unreal, Godot, GameMaker, Construct, Phaser](https://manalens.dev/blog/game-engine-analytics-compared)
- [How to add analytics to a Construct 3 game](https://manalens.dev/blog/construct-3-analytics)
- [How to add analytics to a Phaser game](https://manalens.dev/blog/phaser-analytics)
- [Track an itch.io game](https://manalens.dev/integrations/itch-io)
- [Player analytics guides](https://manalens.dev/blog/topic/player-analytics)
- [How to add analytics to a GameMaker game](https://manalens.dev/blog/gamemaker-analytics)
- [How to move from GameAnalytics to Manalens](https://manalens.dev/blog/migrate-from-gameanalytics)
- [How to add analytics to a Ren'Py game](https://manalens.dev/blog/renpy-analytics)
- [How to add analytics to an Unreal Engine game](https://manalens.dev/blog/unreal-engine-analytics)
