# How to add analytics to a Godot game

> Add the Manalens addon to Godot 4: install, init(), an event table with GDScript, editor runs, errors, consent, and export notes for each platform.

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

Put the addons/manalens folder in your Godot 4 project, enable the plugin in Project Settings, and call Manalens.init() with your Publishable key. The plugin adds an autoload, which Godot always loads, no matter which scene runs (Godot 4.7 documentation). The addon is plain GDScript, so it runs on Windows, macOS, Linux, Android, iOS and Web.

## Key points

- Add the Godot addon by moving addons/manalens into a Godot 4 project, enabling the plugin and calling Manalens.init() once.
- On Godot 4.5 or later, the SDK sends engine and script errors on its own, up to 50 in one session by default.
- An Android export needs the INTERNET permission, and a web export on another host than itch.io needs an entry in Allowed origins.

## What do I need before I start?

You need a Godot 4 project, the addon, the Publishable key of your Manalens project, and your collector endpoint. During early access, the addon is available on request from the contact page. The source will be published at launch.

The Publishable key starts with mana_pk_ and is safe to ship in a game build. Never put a Secret key or an API key in a build. The endpoint is the collector URL without /v0/events.

The addon has no native code. It sends events with Godot's HTTPRequest node, which the Godot class reference describes as a node with the ability to send HTTP(S) requests. So it works on every export target, including the web.

- [Request the Godot addon](https://manalens.dev/contact)
- [GodotSteam achievements and stats: a Godot 4 guide](https://manalens.dev/blog/godotsteam-achievements-and-stats)

Sources: Manalens Godot SDK documentation; Godot documentation, HTTPRequest.

## How do I install the addon?

Move the folder into your project and enable the plugin. Godot's own plugin guide uses the same two steps for any addon: move the addons/ folder into your project folder, then click Enable in the Plugins tab of Project Settings. You do not need to restart the editor.

1. Request the addon from the contact page and extract it.
2. Move addons/manalens into the addons/ folder of your project. If the project has no addons/ folder, move the whole addons/ folder.
3. Open Project, Project Settings, Plugins, and enable Manalens. The plugin adds the Manalens autoload.
4. Copy the Publishable key from your project Settings in Manalens.
5. Call Manalens.init() in the _ready() of your first scene, as in the next section.
6. Run an exported build and check that game_open and session_start appear in the activity feed.

Sources: Manalens Godot SDK documentation; Godot documentation, Installing plugins and Singletons (Autoload).

## How do I start the SDK?

Call init() once, in the _ready() of your first scene. Godot adds autoloaded nodes to the root before it loads any other scene, so Manalens is ready when your scene starts, and it stays loaded when you change scenes. init() sends session_start and game_open, with is_first_open and first_open_at.

Set app_version, build and storefront here. app_version takes up to 32 characters and build up to 64. Storefront takes steam, itch, epic, gog, app_store, play or other. These values go on every event and are filters in every report, for example Build is 571.

The script below is a complete first scene script. It also connects the two signals of the SDK, so that you see each send and each dropped batch in the output while you test.

``` GDScript
# main.gd: the script of your first scene.
extends Node

func _ready() -> void:
    Manalens.flushed.connect(_on_flushed)
    Manalens.send_failed.connect(_on_send_failed)
    Manalens.init({
        "publishable_key": "YOUR_PUBLISHABLE_KEY",
        "endpoint": "https://YOUR_COLLECTOR_ENDPOINT",  # without /v0/events
        "app_version": "1.4.0",
        "build": "571",
        "storefront": "steam",
        "enabled": not OS.has_feature("editor"),
    })

func _on_flushed(sent: int, ok: bool) -> void:
    print("Analytics sent %d events, ok: %s" % [sent, ok])

func _on_send_failed(status: int, dropped: int) -> void:
    push_warning("Analytics dropped %d events (%d)" % [dropped, status])
```

Sources: Manalens Godot SDK documentation; Godot documentation, Singletons (Autoload) and Feature tags.

## Which events should a Godot game send?

The SDK sends five events for you: game_open, session_start, session_end, error and app_unclean_exit. Your code sends the events about play. The table lists the event conventions with the GDScript call for each one. The Game KPIs board reads these names without setup.

A session continues while the game has focus. After 30 minutes without focus or events, the next activity ends the old session and starts a new one. A session is also at most 24 hours old.

- [Game tracking plan generator](https://manalens.dev/tools/game-tracking-plan-generator)
- [Event](https://manalens.dev/glossary/event)
- [Session](https://manalens.dev/glossary/session)

*Events for a Godot game: who sends each one, and the GDScript call.*

| Event | When | Sent by | GDScript |
| --- | --- | --- | --- |
| game_open | Each launch | The SDK | None. Properties: is_first_open, first_open_at. |
| session_start | A session starts | The SDK | None |
| session_end | A session ends: at quit, or after 30 minutes idle | The SDK | None. Property: duration_s. |
| level_start | The player starts a level | Your code | track("level_start", {"level": 3, "attempt": 1}) |
| level_complete | The player completes a level | Your code | track("level_complete", {"level": 3, "attempt": 1, "score": 1200}) |
| level_fail | The player fails a level | Your code | track("level_fail", {"level": 3, "attempt": 1, "score": 300}) |
| resource | The player gains (source) or spends (sink) an in-game resource | Your code | track("resource", {"flow": "sink", "currency": "gold", "amount": 50, "item": "sword"}) |
| purchase | A real-money purchase | Your code | track("purchase", {"amount_cents": 499, "currency": "USD", "store": "steam"}) |
| error | A game error | The SDK (Godot 4.5 or later) and your code | track_error("Save failed", {"error_type": "SaveFailed"}) |
| app_unclean_exit | The launch after a crash | The SDK | None |
| game_updated | The first launch after an update | Your code | track("game_updated", {"previous_version": "1.3.0", "previous_build": "560"}) |

Sources: Manalens Godot SDK and app events documentation.

## How do I track levels and other game events?

Call track() with a snake_case name and a dictionary of flat properties. Values are strings, numbers, booleans or null; the SDK drops other values. Because Manalens is an autoload, you can call it from any script.

The script below is a complete level script. It keeps the level and the attempt in two variables, so that every event has the same properties. Put the level number in a property, not in the event name.

Call identify() when a player signs in to your own account system, and reset() when the player signs out.

- [How to move from GameAnalytics to Manalens](https://manalens.dev/blog/migrate-from-gameanalytics)

``` GDScript
# level.gd: attach it to the root node of a level scene.
extends Node

@export var level: int = 1
var attempt: int = 1

func start_level() -> void:
    Manalens.track("level_start", {"level": level, "attempt": attempt})

func complete_level(score: int) -> void:
    Manalens.track("level_complete", {"level": level, "attempt": attempt, "score": score})

func fail_level(score: int) -> void:
    Manalens.track("level_fail", {"level": level, "attempt": attempt, "score": score})
    attempt += 1

func spend_gold(amount: int, item: String) -> void:
    Manalens.track("resource", {"flow": "sink", "currency": "gold", "amount": amount, "item": item})

# Your own account system:
func on_signed_in(player_id: String) -> void:
    Manalens.identify(player_id, {"plan": "supporter"})

func on_signed_out() -> void:
    Manalens.reset()
```

Sources: Manalens Godot SDK and app events documentation.

## How do I keep editor runs out of my data?

Set enabled to not OS.has_feature("editor"), as in the init() example above. Godot defines the editor feature tag as running on an editor build, so the value is false when you press Play in the editor and true in an exported game.

By default the SDK sends events from every run. Test sessions, crashes and errors then mix into crash-free sessions, errors by build and retention. With enabled set to false, every call does nothing: no events, no files and no stored ID. To test the SDK itself, use a separate test project with its own Publishable key.

Sources: Manalens Godot SDK documentation; Godot documentation, Feature tags.

## How do errors and crashes reach the dashboard?

On Godot 4.5 or later, the SDK sends engine and script errors as error events, up to 50 in one session by default. It registers a custom logger with OS.add_logger(), which the Godot class reference describes as the way to receive messages from the internal error and warning stream. On an earlier Godot 4 version, call track_error() yourself.

When a run crashes, the next launch sends app_unclean_exit in the crashed session. This works on every Godot 4 version. The Game health board then shows crash-free sessions, crash-free players, errors per session by build and the top errors. Use set_before_send() to remove anything private from an error before it leaves the game.

- [Where to find game crash logs, by engine](https://manalens.dev/blog/game-crash-logs-by-engine)
- [What is crash-free rate?](https://manalens.dev/glossary/crash-free-rate)

``` GDScript
# Call it where your own save code reports a failure.
func report_save_failed(slot: int, level: int) -> void:
    Manalens.track_error("Save failed for slot %d" % slot, {
        "error_type": "SaveFailed",
        "severity": "critical",
        "handled": false,
        "properties": {"level": level},
    })

# Once, after init(): change or drop error events before they are queued.
func _scrub_errors() -> void:
    Manalens.set_before_send(func(props): return props)  # return null to drop
```

Sources: Manalens Godot SDK and error tracking documentation; Godot documentation, Logger.

## What happens offline and when the player quits?

Events wait on disk in user://manalens_queue.json. Godot creates the user:// folder automatically and guarantees that it is writable, also in an exported project. The SDK sends events every 10 seconds, at 20 queued events, on focus loss and on quit. After a network error or a 5xx, 408 or 429 response, it keeps the batch and waits longer before each retry, up to 5 minutes. Each event has a message_id, so a retry never counts twice.

Events keep their original time. The collector accepts app events up to 7 days old, so the SDK drops older queued events. On the window close request, the SDK sends session_end and flushes for at most 2 seconds. If your game shows its own quit dialog, set handle_quit to false in init() and use the function below.

- [Offline event queue](https://manalens.dev/glossary/offline-event-queue)

``` GDScript
# With "handle_quit": false in init(). Connect it to the confirmed signal of your quit dialog.
func _on_quit_dialog_confirmed() -> void:
    await Manalens.shutdown()  # session_end, then a flush
    get_tree().quit()
```

Sources: Manalens Godot SDK documentation; Godot documentation, File paths in Godot projects and Handling quit requests.

## How do I ask for consent?

Start with consent_required set to true, then call set_consent() from your consent screen. Until consent, the SDK records no events and writes no ID. It saves the choice, so the next launch uses it. set_consent(false) deletes the ID, the session and the queue, and writes an opt-out marker file.

Whether your game needs consent is a decision for you and your legal advisers. The option gives you the technical control.

- [GDPR consent in games](https://manalens.dev/glossary/gdpr-consent-games)

``` GDScript
Manalens.init({"publishable_key": "mana_pk_...", "endpoint": "https://...", "consent_required": true})

# Later, from your consent screen:
Manalens.set_consent(true)   # starts tracking; sends game_open
Manalens.set_consent(false)  # deletes the ID, the session and the queue
```

Sources: Manalens Godot SDK documentation.

## What changes for each export platform?

The GDScript stays the same on every platform. The table lists only what the Manalens and Godot documentation state. Where a cell says "Not documented", we found no statement and we do not guess.

In a web export on another site than itch.io, add the hosts of the portal under Project settings, Allowed origins. To join a player in the game with the same person on your website, open your site with link_url(). It adds a short-lived parameter that the web SDK reads, so the website visit and the game install count as one player.

- [Track an itch.io game](https://manalens.dev/integrations/itch-io)

*Export notes for each Godot platform, as far as the documentation goes.*

| Export | Platform value on events | Network | Quit and background |
| --- | --- | --- | --- |
| Windows, macOS, Linux | windows, macos, linux | No Origin header, so no origin rule applies | The SDK handles the window close request: session_end, then a flush of at most 2 seconds |
| Android | android | Enable the INTERNET permission in the Android export preset. Without it, Android blocks all network communication (Godot documentation). | Godot has no close request on mobile. The SDK saves the state and sends the queue when the app loses focus or is paused. |
| iOS | ios | Not documented | As on Android. Godot says that iOS gives about 5 seconds to finish a task that starts when the app is paused. |
| Web | web | The browser sends an Origin header and a CORS preflight. Your project domain, its subdomains and *.itch.zone are accepted; another host gets 403 until you add it to Allowed origins. | Godot sends the close request notification on desktop and web platforms |
| Other platforms | other | Not documented | Not documented |

``` GDScript
OS.shell_open(Manalens.link_url("https://example.com/wiki"))
```

Sources: Manalens Godot SDK and app events documentation; Godot documentation, HTTPRequest, Handling quit requests and Exporting for the Web.

## How do I check that events arrive?

Run an exported build with the debug option on and read the activity feed. With debug set to true, the SDK prints each queued event and each failed send. The flushed signal tells you the result of each send, and send_failed tells you when events were dropped: status is the HTTP status of a refused batch, or 0 when the SDK dropped the events itself.

1. Create a test project in Manalens and use its Publishable key.
2. Add "debug": true to init(), export the game and run it.
3. Open the activity feed. Check that session_start and game_open arrive, and that the event detail shows platform, storefront, app version, build and engine.
4. Play one level and close the window. Check level_start, level_complete and session_end with duration_s.
5. Switch off the network, play for a minute, switch it on, and check that the queued events arrive once.
6. A status of 403 from a web export means that the host is not an allowed origin. A status of 400 means that the collector refused the batch; the warning in the log has the reason.
7. Replace the test key with the production Publishable key and remove the debug option.

Sources: Manalens Godot SDK documentation.

## What will I see after the first players launch the game?

You see launches, sessions and errors in the activity feed within minutes. After one day you can read D1 retention. Create the Game KPIs board from the dashboard templates to get DAU, MAU, stickiness, D1, D7 and D30 retention, sessions per DAU, session length, a Levels table and a level funnel.

Create the Game health board as well. Use the App filter group, for example Build is 571, to compare a patch with the build before it. If players come from your website, install attribution links the first game_open to a recent website visit on the same network, and the Attribution page shows it on the Installs tab.

- [D1 retention](https://manalens.dev/glossary/d1-retention)

Sources: Manalens metrics, error tracking and install attribution documentation.

## What if my game uses another engine?

Send the same events over HTTP. The guides below show the HTTP code for each engine, with a saved player ID, an offline queue, a consent flag and notes for web, desktop and mobile builds.

- [How to add analytics to a GameMaker game](https://manalens.dev/blog/gamemaker-analytics)
- [How to add analytics to a Construct 3 game](https://manalens.dev/blog/construct-3-analytics)
- [How to add analytics to a Defold game](https://manalens.dev/blog/defold-analytics)
- [How to add analytics to a Bevy game](https://manalens.dev/blog/bevy-analytics)
- [How to add analytics to a Phaser game](https://manalens.dev/blog/phaser-analytics)
- [How to add analytics to a LÖVE (Love2D) game](https://manalens.dev/blog/love2d-analytics)
- [How to add analytics to an RPG Maker MZ game](https://manalens.dev/blog/rpg-maker-mz-analytics)
- [How to add analytics to a Ren'Py game](https://manalens.dev/blog/renpy-analytics)
- [How to add analytics to a Pico-8 game](https://manalens.dev/blog/pico-8-analytics)
- [How to add analytics to a GDevelop game](https://manalens.dev/blog/gdevelop-analytics)
- [How to add analytics to a MonoGame game](https://manalens.dev/blog/monogame-analytics)
- [How to add analytics to a Raylib game](https://manalens.dev/blog/raylib-analytics)
- [How to add analytics to a HaxeFlixel game](https://manalens.dev/blog/haxeflixel-analytics)
- [How to add analytics to a Stride game](https://manalens.dev/blog/stride-analytics)

Sources: Manalens app events documentation.

## How do I start?

Manalens is the analytics and growth engine built for games. Add the Godot addon, call init() once, and open the Game KPIs board to see retention, sessions and level fail rates from your first build.

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

Sources: Manalens product documentation.

## Frequently asked questions

### Which Godot versions does the addon support?

Godot 4. The addon is plain GDScript with no native code, so it runs on Windows, macOS, Linux, Android, iOS and Web exports. Automatic capture of engine and script errors needs Godot 4.5 or later; on earlier 4.x versions, send errors with track_error().

### Is the Godot addon in the Godot Asset Library?

Not yet. During early access, the addon is available on request from the contact page, and the source will be published at launch. You install it as any other addon: move the addons/manalens folder into your project and enable the plugin in Project Settings.

### Does the Godot addon collect personal data?

It sends a random anonymous ID, the session ID, your user ID after identify(), and the app context: platform, engine, version, build and storefront. It sends no device ID, no hardware details and no IP address. The collector derives the country and does not store the IP.

### Does the Godot addon work offline?

Yes. Events wait on disk and the SDK sends them every 10 seconds, at 20 queued events, on focus loss and on quit. After a network error it retries with longer waits, up to 5 minutes. The collector accepts events up to 7 days old, so older queued events are dropped.

### Does an Android export need a special setting?

Yes. The Godot documentation says to enable the INTERNET permission in the Android export preset before you export or use one-click deploy. Without it, Android blocks network communication of any kind, so no event leaves the device. The events then wait in the queue on disk.

## Sources

- [Godot documentation 4.7: Installing plugins (read 19 November 2026)](https://docs.godotengine.org/en/stable/tutorials/plugins/editor/installing_plugins.html)
- [Godot documentation 4.7: Singletons (Autoload) (read 19 November 2026)](https://docs.godotengine.org/en/stable/tutorials/scripting/singletons_autoload.html)
- [Godot documentation 4.7: HTTPRequest (read 19 November 2026)](https://docs.godotengine.org/en/stable/classes/class_httprequest.html)
- [Godot documentation 4.7: Feature tags (read 19 November 2026)](https://docs.godotengine.org/en/stable/tutorials/export/feature_tags.html)
- [Godot documentation 4.7: Logger (read 19 November 2026)](https://docs.godotengine.org/en/stable/classes/class_logger.html)
- [Godot documentation 4.7: File paths in Godot projects (read 19 November 2026)](https://docs.godotengine.org/en/stable/tutorials/io/data_paths.html)
- [Godot documentation 4.7: Handling quit requests (read 19 November 2026)](https://docs.godotengine.org/en/stable/tutorials/inputs/handling_quit_requests.html)
- [Godot documentation 4.7: Exporting for the Web (read 19 November 2026)](https://docs.godotengine.org/en/stable/tutorials/export/exporting_for_web.html)

## Related guides

- [Game marketing measurement guide](https://manalens.dev/blog/game-marketing-measurement-guide)
- [What events to track first in your game](https://manalens.dev/blog/game-tracking-plan-first-events)
- [Engine analytics compared: Unreal, Godot, GameMaker, Construct, Phaser](https://manalens.dev/blog/game-engine-analytics-compared)
- [D1, D7 and D30 retention benchmarks for PC and indie games](https://manalens.dev/blog/pc-indie-game-retention-benchmarks)
- [Track an itch.io game](https://manalens.dev/integrations/itch-io)
- [Best analytics tools for Godot games in 2026](https://manalens.dev/blog/best-godot-analytics-tools)
- [Game tracking plan generator](https://manalens.dev/tools/game-tracking-plan-generator)
- [Player analytics guides](https://manalens.dev/blog/topic/player-analytics)
- [Game metrics every indie developer should track](https://manalens.dev/blog/game-metrics-indie-developers)
- [How to add analytics to a Unity game](https://manalens.dev/blog/unity-analytics-without-gameanalytics)
- [PostHog, Mixpanel or Amplitude for games?](https://manalens.dev/blog/posthog-mixpanel-amplitude-for-games)
- [Game analytics dashboards: which charts matter](https://manalens.dev/blog/game-analytics-dashboard-charts)
