Skip to main content
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 to the normal events endpoint with your project’s Publishable key.

Install

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

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

Track events

Property values are strings, numbers, booleans or null. The SDK drops other values. Use the 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():
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; 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.

Errors and crashes

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 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:
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

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 (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).

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

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