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.- Copy
sdks/godot/addons/untitled_analyticsfrom the ManaLens repository into your project’saddons/folder. - Open Project > Project Settings > Plugins and enable ManaLens. This adds the
UntitledAnalyticsautoload. - 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
Open your website from the game
Uselink_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
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: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 withsession_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.jsonand sent every 10 seconds, at 20 queued events, on focus loss and on quit. - After a network error or a
5xx,408or429response, the SDK keeps the batch and waits about 2, 4, 8 … seconds (with jitter), at most 5 minutes. Other4xxresponses drop the batch: it is not sent again, and the warning in the log has the reason of the collector (for exampleINVALID_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 sendssession_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:
Consent
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 carriesanonymous_id (a UUID kept in user://untitled_analytics.cfg), session_id, user_id after identify(), and context.app:
platformfromOS.get_name():windows,macos,linux,android,ios,weborother.engine:godot.app_version,buildandstorefrontfrominit().
Web export
A web export runs in a browser, so its requests carry anOrigin 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 insdks/godot/test_project. With the local stack running (Supabase, SQS and the worker, Tinybird Local), run:
raw_events. Set UA_PROJECT_ID, UA_API_URL, UA_API_PORT, GODOT or ANALYTICS_TB_WORKSPACE_PATH to change the defaults.