track and identify events to POST /v0/events. It batches events, sends them on a timer, and retries failed requests. It has two modes:
In app mode the SDK sends the Publishable key in the
x-publishable-key header. Older publishable keys that start with ua_ (without pk_) still work in app mode. API keys (ua_api_, or older ua_mcp_) read data and cannot send events: the SDK refuses them in both modes. The SDK also checks the length and checksum of a ua_pk_ or ua_sk_ key, so a typo fails at startup.
Install
Early access. The Node.js package 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.The package is not on npm yet. Until it is, install the package archive that you received, or build it from
sdks/node in the repository when you have access (pnpm --filter @untitled-analytics/node build). It needs Node.js 20.3 or newer and has no dependencies.Server mode
Create the secret key in your project settings first: see Create the secret key. Keep it in an environment variable on your backend.userId, anonymousId (a UUID, for example the one the web or game SDK made), or both. With both, the event links that device to the user. See Join server events to players.
Send the player’s IP and user agent
A backend’s own IP and user agent are not the player’s. When an event comes from a player’s request, pass theirs incontext. The collector uses the IP only to look up the country, in memory, and never stores it. It uses the user agent for device, OS and browser.
Express
sessionId (and the anonymousId) of the client is in the visitor’s session, also when your backend sends it late. A server event without a sessionId is valid: it joins the session of the same anonymousId that is active at that time, if there is one. sessionId is an option of each track() and identify() call. See server events.
Other context fields for server events: country (two letters), locale, device (desktop, mobile, tablet), os, browser, page (path, title, url) and app (see below). A dedicated game server can set the app option once, and every event gets context.app. When context.app has a native platform, it sets the OS and device; the browser still comes from the user agent.
The SDK adds context.library_name (@untitled-analytics/node) and context.library_version to every event in both modes.
App mode (Electron main process)
In Electron, use the web SDK in the renderer. Use this SDK in the main process only for events the renderer cannot see, such as app start, updates or crashes of a window.main.ts
app.platformis required:windows,macos,linux,web,android,iosorother. Optional:storefront(steam,itch,epic,gog,app_store,play,other),app_version(up to 32 characters),build(up to 64),engine(godot,unity,unreal,other).- Every event has an
anonymous_id. The SDK uses theanonymousIdoption, or a new UUID for each process. Keep one UUID per player on disk and pass it, or each launch counts as a new player. Use the same ID as the renderer’s web SDK to join the two. - The SDK makes a
session_id. It starts a new session after 30 minutes without events, and when the session is 24 hours old.getSessionId()returns the session ID of the next event. Pass thesessionIdoption to set your own; the SDK then never changes it, and you must keep a session under 24 hours. - Every app event needs a
session_idthat is not theanonymous_id. The SDK drops an event that breaks this (the collector refuses it withSESSION_ID_REQUIREDorSESSION_ID_IS_ANONYMOUS_ID). - The collector refuses app events more than 7 days old, so the SDK drops them.
Options
Track and identify
null. Trait names have 1 to 100 characters.
track() and identify() never throw for a bad event. The SDK drops the event and, with debug: true, logs why. The collector refuses a whole batch when one event is bad, so the SDK checks each event first with the same rules.
Delivery and retries
- Every event has a
message_id. A retry sends the same batch with the same IDs, so reports count each event once. - The SDK retries network errors, timeouts,
5xx,408and429. It waits for theRetry-Afterheader when the collector sends one, else 1, 2, 4 seconds with jitter. - Other
4xxresponses (a wrong key, an invalid batch) are not retried. The SDK drops the batch and, in debug mode, logs the status and the response of the collector, which has the reason code of each refused event (for exampleSESSION_ID_REQUIRED).
Flush and shut down
flush() sends every queued event now. shutdown(timeoutMs = 5000) sends every queued event for at most timeoutMs, then stops the timer. Calls after shutdown() are dropped.
The SDK adds no process exit hooks. Call shutdown() yourself before the process exits: