> ## Documentation Index
> Fetch the complete documentation index at: https://docs.manalens.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Godot SDK

> Track sessions, launches and game events from Godot 4 on desktop, mobile and web.

The Godot SDK is a Godot 4 addon in plain GDScript. It needs no native code, so it works on every export target: Windows, macOS, Linux, Android, iOS and Web. It sends [app events](https://docs.manalens.dev/sdks/app-events.md) to the normal events endpoint with your project's [Publishable key](https://docs.manalens.dev/api/authentication.md#publishable-key).

## Install

> [!NOTE]
>
> **Early access.** The Godot addon is available on request during early access. The repository is private until launch, so the steps below work only after you have access. To ask for it, use the Contact page of the ManaLens website (`/contact`) and tell us your engine and platform. The source will be published at launch.

1. Copy `sdks/godot/addons/untitled_analytics` from the ManaLens repository into your project's `addons/` folder.
2. Open **Project > Project Settings > Plugins** and enable **ManaLens**. This adds the `UntitledAnalytics` autoload.
3. Copy the **Publishable key** from your project's **Settings**. It starts with `ua_pk_` (older projects: `ua_`). It is safe to ship in a game build. Never put a Secret key or an API key in a build.

## Start the SDK

```gdscript theme={null}
func _ready() -> void:
    UntitledAnalytics.init({
        "publishable_key": "YOUR_PUBLISHABLE_KEY",
        "endpoint": "https://YOUR_COLLECTOR_ENDPOINT",
        "app_version": "1.4.0",
        "build": "571",
        "storefront": "steam",
    })
```

`init()` sends `session_start` and `game_open` with `is_first_open` and `first_open_at`.

| Option | Default | Meaning |
| - | - | - |
| `publishable_key` | required | The project's Publishable key. |
| `endpoint` | required | The collector URL, without `/v0/events`. |
| `app_version` | none | Up to 32 characters, for example `1.4.0`. |
| `build` | none | Up to 64 characters, for example a build number. |
| `storefront` | none | `steam`, `itch`, `epic`, `gog`, `app_store`, `play` or `other`. |
| `enabled` | `true` | `false`: the SDK sends nothing, writes no files and keeps no ID. See [Editor and test runs](#editor-and-test-runs). |
| `consent_required` | `false` | No events and no stored ID until `set_consent(true)`. |
| `flush_interval_s` | `10` | Seconds between sends. |
| `flush_at` | `20` | Send when this many events are queued. Also the batch size. |
| `max_queue` | `1000` | Most events kept on disk. The oldest are dropped first. |
| `handle_quit` | `true` | Delay the window close to send `session_end` and flush. |
| `quit_timeout_s` | `2` | Longest wait on quit. |
| `capture_engine_errors` | `true` | Godot 4.5+: send engine and script errors as `error` events. |
| `capture_warnings` | `false` | Also send engine warnings. |
| `max_auto_errors_per_session` | `50` | Most engine errors in one session. |
| `debug` | `false` | Print each queued event and each failed send. |

## Track events

```gdscript theme={null}
UntitledAnalytics.track("level_complete", {"level": 3, "attempt": 1, "score": 1200})
UntitledAnalytics.track("resource", {"flow": "sink", "currency": "gold", "amount": 50, "item": "sword"})
UntitledAnalytics.identify("player_42", {"plan": "supporter"})
UntitledAnalytics.reset()  # on sign out
```

Property values are strings, numbers, booleans or null. The SDK drops other values. Use the [event conventions](https://docs.manalens.dev/sdks/app-events.md#event-conventions) so that reports and funnels line up across games.

## Open your website from the game

Use `link_url()` when the game opens a page on your website (wiki, store, newsletter, Discord page). The website then joins this player, without `identify()`:

```gdscript theme={null}
OS.shell_open(UntitledAnalytics.link_url("https://example.com/wiki"))
```

`link_url()` adds `ua_hid=<anonymous ID>.<unix seconds>` to the URL and keeps the query and the `#` part. The website needs the [Web SDK](https://docs.manalens.dev/sdks/web.md#players-who-come-from-your-game); it removes the parameter from the address bar. The link works for 10 minutes. Before consent, `link_url()` returns the URL unchanged. See [one player on the website and in the game](https://docs.manalens.dev/guides/identify-users.md#one-player-on-the-website-and-in-the-game).

## Errors and crashes

```gdscript theme={null}
UntitledAnalytics.track_error("Save failed", {"error_type": "SaveFailed", "severity": "critical", "handled": false})
UntitledAnalytics.set_before_send(func(props): return props)  # return null to drop
```

On Godot 4.5+, engine and script errors are sent automatically. When a run crashes, the next launch sends `app_unclean_exit` in the crashed session. See [Errors and crashes](https://docs.manalens.dev/features/error-tracking.md) for the properties, the limits and the **Game health** board.

## Editor and test runs

By default the SDK sends events from every run, also when you press Play in the editor. Test sessions, crashes and errors then mix into your real reports (crash-free sessions, errors by build, retention). Turn the SDK off in the editor:

```gdscript theme={null}
UntitledAnalytics.init({
    "publishable_key": "YOUR_PUBLISHABLE_KEY",
    "endpoint": "https://YOUR_COLLECTOR_ENDPOINT",
    "enabled": not OS.has_feature("editor"),
})
```

With `enabled: false`, every call (`track`, `identify`, `set_consent`, `flush`) does nothing. To test the SDK in the editor, use a separate test project and its own publishable key.

## Signals

| Signal | When |
| - | - |
| `flushed(sent: int, ok: bool)` | After each send. `ok` is `false` for a network error or a `5xx`, `408` or `429` response; those events stay queued. |
| `send_failed(status: int, dropped: int)` | Events were dropped and will never be sent. `status` is the HTTP status when the collector refused a batch (another `4xx`), or `0` when the SDK dropped events itself (the queue was over `max_queue`, or events were older than 7 days). |

```gdscript theme={null}
UntitledAnalytics.send_failed.connect(func(status, dropped): push_warning("Analytics dropped %d events (%d)" % [dropped, status]))
```

## Sessions

A session continues while the game has focus. After 30 minutes without focus or events, the next activity ends the old session with `session_end` (`duration_s`) and starts a new one. A session is also at most **24 hours** old: a game that stays open gets a `session_end` and a `session_start` every 24 hours. Earlier builds of the SDK kept one session for as long as the game had focus. If the game crashes or is killed, the next launch ends the old session at its last activity and sends `app_unclean_exit`. Pause and focus notifications (`NOTIFICATION_APPLICATION_FOCUS_OUT`, `NOTIFICATION_APPLICATION_PAUSED`) save the state and send the queue.

`get_session_id()` returns the current session ID, and `get_anonymous_id()` the player ID. Send the two to your backend to put a [server event](https://docs.manalens.dev/sdks/server.md#session-id-of-the-client) (for example a purchase) in the player's session.

Every event has a session ID that is not the anonymous ID. The collector refuses other events (`SESSION_ID_REQUIRED`, `SESSION_ID_IS_ANONYMOUS_ID`: see [the session ID contract](https://docs.manalens.dev/api/events.md#the-session-id-contract)).

## Offline queue and retries

* Events are saved in `user://untitled_analytics_queue.json` and sent every 10 seconds, at 20 queued events, on focus loss and on quit.
* After a network error or a `5xx`, `408` or `429` response, the SDK keeps the batch and waits about 2, 4, 8 ... seconds (with jitter), at most 5 minutes. Other `4xx` responses drop the batch: it is not sent again, and the warning in the log has the reason of the collector (for example `INVALID_EVENT ... (SESSION_ID_REQUIRED)`).
* Events keep their original time. The collector accepts app events up to 7 days old, so the SDK drops queued events older than that.
* Each event has a `message_id`, so a retry never counts twice.

## Quit

By default the SDK handles the window close request. It sends `session_end`, flushes for at most `quit_timeout_s` seconds, then quits. Events that could not be sent stay on disk for the next launch.

If your game handles the close request itself, for example with a confirmation dialog, set `handle_quit` to `false` and call:

```gdscript theme={null}
await UntitledAnalytics.shutdown()
get_tree().quit()
```

## Consent

```gdscript theme={null}
UntitledAnalytics.init({"publishable_key": "ua_pk_...", "endpoint": "https://...", "consent_required": true})
# Later, from your consent screen:
UntitledAnalytics.set_consent(true)   # starts tracking; sends game_open
UntitledAnalytics.set_consent(false)  # deletes the ID, the session and the queue
```

With `consent_required`, the SDK records no events and writes no ID before consent. It saves the choice, so the next launch uses it. An `identify()` call before consent is sent after consent.

An opt-out fails closed. `set_consent(false)` also writes a marker file (`user://untitled_analytics_optout`), and the SDK records nothing while it exists, even if the config file is lost. If the config file exists but cannot be read, the SDK records nothing in that run, keeps a copy (`.unreadable`) and does not overwrite the file, until `set_consent(true)`. The SDK writes its files to a temporary file first, then renames it.

## Data the SDK sends

Each event carries `anonymous_id` (a UUID kept in `user://untitled_analytics.cfg`), `session_id`, `user_id` after `identify()`, and `context.app`:

* `platform` from `OS.get_name()`: `windows`, `macos`, `linux`, `android`, `ios`, `web` or `other`.
* `engine`: `godot`.
* `app_version`, `build` and `storefront` from `init()`.

The SDK sends no device ID, no hardware details and no IP. The collector derives the country from the request IP and does not store the IP.

## Web export

A web export runs in a browser, so its requests carry an `Origin` header and a CORS preflight. The collector accepts them from your project domain and its subdomains, for example `play.example.com`.

**itch.io works by default.** Every project allows `*.itch.zone`, which covers the hosts itch.io serves HTML5 builds from, such as `html-classic.itch.zone` and `html.itch.zone`.

For another game portal, add its hosts to **Project settings > Allowed origins** (owner or admin, with MFA). A build on a host that is not in the list is refused with `403`. To refuse itch.io builds, remove `*.itch.zone` from the list. See [Web exports and CORS](https://docs.manalens.dev/sdks/app-events.md#web-exports-and-cors).

## Test locally

The repository has a headless test project in `sdks/godot/test_project`. With the local stack running (Supabase, SQS and the worker, Tinybird Local), run:

```bash theme={null}
pnpm test:godot:local
```

The script starts this checkout's API on port 3291, runs the test project four times (offline then online, consent, crash recovery, errors) with a local project's Publishable key, and checks the events in Tinybird `raw_events`. Set `UA_PROJECT_ID`, `UA_API_URL`, `UA_API_PORT`, `GODOT` or `ANALYTICS_TB_WORKSPACE_PATH` to change the defaults.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.