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

# App and game events

> Send events from a game or app build to the normal events endpoint with context.app and the publishable key.

A game or app build (Godot, Unity, Unreal, a desktop or mobile app) sends events to the same endpoint as your website: `POST /v0/events` with the project **publishable key**. The event envelope is the same as the web SDK's. The only difference is the context: an app event has `context.app` where a web event has `context.page`.

One endpoint keeps one user across your website and your game in one project. Website visits, store clicks and in-game events share reports, filters and funnels.

> [!NOTE]
>
> The publishable key is safe to ship in a page or a game build. It sends website and game events. It cannot read data. Never ship the [secret key](https://docs.manalens.dev/sdks/server.md) in a build.

## Send an event

The [Godot SDK](https://docs.manalens.dev/sdks/godot.md) and the [Unity SDK](https://docs.manalens.dev/sdks/unity.md) build this envelope for you. For another engine, send it over HTTP:

```bash theme={null}
curl -sS https://YOUR_COLLECTOR_ENDPOINT/v0/events \
  -H 'x-publishable-key: YOUR_PUBLISHABLE_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "events": [{
      "type": "track",
      "event": "level_complete",
      "channel": "app",
      "version": "0.1.0",
      "message_id": "6a0f8e9c-2c36-4c55-9a43-6a5d0f3c2b11",
      "anonymous_id": "3f0c5c1e-8a8e-4c1b-9d7e-2b1f4e6a9c10",
      "session_id": "1762689600000",
      "original_timestamp": "2026-11-09T10:00:00.000Z",
      "context": {
        "app": { "platform": "windows", "storefront": "steam", "app_version": "1.4.0", "build": "571", "engine": "godot" },
        "locale": "en",
        "library_name": "my-game",
        "library_version": "1.4.0"
      },
      "properties": { "level": 3, "score": 1200 }
    }]
  }'
# {"accepted":1}
```

## The app context

| Field | Required | Values |
| - | - | - |
| `platform` | Yes | `windows`, `macos`, `linux`, `web`, `android`, `ios`, `other` |
| `storefront` | No | `steam`, `itch`, `epic`, `gog`, `app_store`, `play`, `other` |
| `app_version` | No | Up to 32 characters: letters, digits, space and `. _ + -` |
| `build` | No | Up to 64 characters: letters, digits, space and `. _ + -` |
| `engine` | No | `godot`, `unity`, `unreal`, `other` |

Rules:

* An app event has `context.app` and no `context.page`. Its `channel` is `app`.
* A web event has `context.page`. Its `channel` is `web`. It can also send `context.app`: see [Browser and Electron games](#browser-and-electron-games).
* An event with neither `context.page` nor `context.app` is refused.
* App events are `track` or `identify`. A `page` event needs a page; send a `track` event such as `screen_view` for a game screen.
* `original_timestamp` can be up to **7 days** old, so an offline queue can send later. Older events, or events more than 10 minutes in the future, refuse the batch with `400`. Website events keep their current rules.
* Up to 50 events in one request, as for the web SDK.
* Every event has a `session_id`, and it is not the `anonymous_id`. Make a new ID when the game starts, after 30 minutes without events, and when the session is 24 hours old. A batch that breaks this gets `400` with a reason for each refused event (`SESSION_ID_REQUIRED`, `SESSION_ID_IS_ANONYMOUS_ID`): see [the session ID contract](https://docs.manalens.dev/api/events.md#the-session-id-contract).

## What the collector does

* **No page domain check and no Origin needed.** A native build has no page URL and its HTTP client sends no Origin header. The collector accepts the event with the publishable key, like Formono's events gateway.
* **The Origin rule still applies.** When a request has an `Origin` header, it must be your project domain, one of its subdomains, or a host in the project's [allowed origins](#allowed-origins). A browser on any other site cannot send app events (or web events) to your project: the request gets `403`.
* **Country** comes from the request IP, as for the web. The IP and the user agent are never stored.
* **Install match.** A first `game_open` can get the anonymous ID of a recent website visitor from the same network. The optional `context.utc_offset` (minutes from UTC, -720 to 840) helps the match and is not stored. See [install attribution](https://docs.manalens.dev/attribution/installs.md).
* **Device and OS.** For a native build, the OS comes from `context.app.platform` (`windows`, `macos`, `linux`, `android`, `ios`), and the device is `desktop`, or `mobile` for Android and iOS. A web export (`platform: web`) keeps the device, OS and browser of its browser user agent. A bot user agent keeps the `bot` label.
* **Channel** (acquisition) is `Direct`. A game has no referrer.
* The per-project ingest limit is the same as for the web.

## Identify

Send an `identify` event through `/v0/events` with `context.app` (recommended). The older `POST /v0/identify` body also takes `app` in place of `page_url`:

```json theme={null}
{ "user_id": "player_42", "traits": { "name": "Ana" }, "anonymous_id": "3f0c5c1e-8a8e-4c1b-9d7e-2b1f4e6a9c10", "app": { "platform": "linux", "engine": "godot" } }
```

## Web exports and CORS

A game exported to the web runs in a browser, and the browser sends an `Origin` header. The collector applies the normal origin rule:

* **Served from your project domain** (for example `play.example.com` for project domain `example.com`): accepted. The collector answers the CORS preflight for your domain. Send `context.app` with `platform: web`, or send `context.page` as a website does.
* **Served from a host in the project's allowed origins** (for example an itch.io HTML5 page on `html-classic.itch.zone`; `*.itch.zone` is in the list by default): accepted, with CORS headers for that origin. Send `context.app` with `platform: web`, or use the [web SDK](https://docs.manalens.dev/sdks/web.md#game-portals) (web events with a page URL on that host).
* **Served from any other domain:** refused with `403`, because a browser on another site must not write to your project.

### Allowed origins

**Project settings > Allowed origins** shows the project domain and its subdomains (always allowed, not in the list) and the list of extra hosts. A new project starts with `*.itch.zone`, so itch.io HTML5 builds work without setup. One-click presets add the host of a game portal: **itch.io** (`*.itch.zone`) and **CrazyGames** (`*.crazygames.com`). Poki has no preset, because its developer docs do not name the host of game builds. Only an owner or admin with an MFA session can change the list, and each change is in the audit log. [Short links](https://docs.manalens.dev/features/short-links.md) can also point to these hosts.

| Entry | Matches | Does not match |
| - | - | - |
| `html-classic.itch.zone` | `html-classic.itch.zone` only | `a.html-classic.itch.zone`, `html-classic.itch.zone.evil.com` |
| `*.itch.zone` | any subdomain, such as `html.itch.zone` | `itch.zone`, `evilitch.zone`, `itch.zone.evil.com` |
| `localhost` | a local test server, such as the Godot editor's `http://localhost:8060` | |

* Up to **20** entries. The scheme and port are ignored: `https://html-classic.itch.zone` is saved as `html-classic.itch.zone`, and both `http` and `https` match.
* A wildcard needs at least two labels after `*.`, so `*.com` is refused. IP addresses, paths and `*` alone are refused.
* itch.io (`*.itch.zone`) is in the list by default. Remove it to refuse itch.io builds; **Restore default** puts it back.
* **Web events too.** A web event (`context.page`) passes when its page URL is on the project domain, a subdomain, or a host in this list (the same matching as the `Origin` header). Any other page host gets `403` (`Page domain does not match project`). So the [web SDK](https://docs.manalens.dev/sdks/web.md#game-portals) works in a portal iframe once the portal host is listed.

With the API, owners and admins call `PUT /v0/projects/:projectId/allowed-origins` with `{ "allowed_origins": ["*.itch.zone", "html-classic.itch.zone"] }`. The response has the saved, normalized list.

## Reports

App fields are filters and breakdowns in every report. They work for app events, for web events that send `context.app` (browser and Electron games), and for server events that send `context.app`:

| Report field | Reads |
| - | - |
| `app_platform` | `context.app.platform` |
| `app_storefront` | `context.app.storefront` |
| `app_version` | `context.app.app_version` |
| `app_build` | `context.app.build` |
| `app_engine` | `context.app.engine` |

* **Filters:** the filter menu has an **App** group. With the API, use `filters=[{"field":"app_build","op":"eq","value":"571"}]`.
* **Breakdowns:** the Overview chart and the Activity chart have an **App** breakdown group (`split_by=app_platform`). Funnels, top events and retention take `breakdown=app_platform` (or any app field).
* **Activity:** the event detail shows platform, storefront, app version, build and engine.

## Browser and Electron games

A game that runs in a browser on your own domain (for example `play.example.com`) or in Electron can use the [web SDK](https://docs.manalens.dev/sdks/web.md). Set the `app` option. Then every event is a web event (`channel: 'web'`, with `context.page`) that also carries `context.app`. The App filters and breakdowns (build, version, platform, storefront, engine) and errors by build work for the game. The Game KPIs and Game health dashboard templates count these events with the app events of native builds, so send the [event conventions](#event-conventions) (`game_open`, `session_start`, `session_end`) with `track`.

The device, OS and browser of a web event still come from the browser user agent. The page, domain and Origin rules of web events still apply: the page URL must be on your project domain, a subdomain, or a host in the project's [allowed origins](#allowed-origins). So the web SDK works in an itch.io HTML5 iframe (an `itch.zone` host, in the list by default) and on another game portal once you add its host (see [Game portals](https://docs.manalens.dev/sdks/web.md#game-portals)). Inside the iframe the SDK sees the portal host, not the portal page around it, so the UTM tags and referrer of that page are not visible; use the [itch.io integration](https://docs.manalens.dev/integrations/itch.md) and [short links](https://docs.manalens.dev/features/short-links.md) for traffic attribution. You can also send app events (`context.app` and no `context.page`) from the game code, as in [Send an event](#send-an-event), or use the Unity or Godot SDK in a WebGL or web build. An Electron page loaded from `file://` has no page URL on your domain, so its events get `403`. Serve the renderer from an `https://` URL on your project domain, for example with Electron's `protocol.handle` (see the `with-electron` example), or send events from the main process with the [Node SDK](https://docs.manalens.dev/sdks/node.md) in app mode. An app object that is not valid refuses the event with `400`. The web SDK drops it before it sends and logs a debug warning.

```ts theme={null}
import { createAnalytics } from '@untitled-analytics/web';

const analytics = createAnalytics({
  publishableKey: 'YOUR_PUBLISHABLE_KEY',
  endpoint: 'https://api.your-domain.com',
  app: { platform: 'web', storefront: 'other', app_version: '1.4.0', build: '571', engine: 'other' },
});
```

The web SDK does not send game events for you. Send them with plain `track` calls:

| Event | Properties | When |
| - | - | - |
| `game_open` | `is_first_open`, `first_open_at` | Each launch |
| `session_start` | none | A session starts |
| `session_end` | `duration_s` | A session ends: at quit, or after 30 minutes idle |
| `error` | `severity`, `message`, `error_type`, `handled`, `fingerprint` | A game error. See [Errors and crashes](https://docs.manalens.dev/features/error-tracking.md). |
| `app_unclean_exit` | `previous_session_id`, `previous_build` | Electron only: the last run did not quit normally |
| `game_updated` | `previous_version`, `previous_build` | The first launch after an update |

```ts theme={null}
const build = '571';
const firstOpenAt = localStorage.getItem('first_open_at');
if (!firstOpenAt) localStorage.setItem('first_open_at', new Date().toISOString());
analytics.track('game_open', {
  is_first_open: !firstOpenAt,
  first_open_at: firstOpenAt ?? localStorage.getItem('first_open_at'),
});

const sessionStart = Date.now();
analytics.track('session_start');
window.addEventListener('pagehide', () => {
  analytics.track('session_end', { duration_s: Math.round((Date.now() - sessionStart) / 1000) });
});

window.addEventListener('error', (event) => {
  analytics.track('error', { severity: 'error', message: event.message, error_type: 'uncaught', handled: false });
});
```

For a session that ends after 30 minutes idle, keep a timer that you reset on player input. When it fires, send `session_end`, and send `session_start` at the next input.

### Unclean exits in Electron

A browser tab cannot tell a crash from a closed tab, so send `app_unclean_exit` from Electron only:

1. At start, save a "running" flag with the session ID and the build (for example in a file in the user data folder).
2. At a normal quit, clear the flag.
3. At the next start, check the flag. If it is still set, the last run did not quit normally. Send `app_unclean_exit` with `previous_session_id` and `previous_build`.

### Electron main process

Use the web SDK with the `app` option in the renderer. Most games need nothing else.

If the main process must send events (app start, quit, updates), use the [Node SDK in app mode](https://docs.manalens.dev/sdks/node.md#app-mode-electron-main-process) with the publishable key and the same `anonymous_id` as the renderer. Never ship the secret key in the app build.

## Event conventions

Use flat `track` events with snake\_case names and properties. The names follow the GameAnalytics event model, without its colon-joined IDs.

| Event | Properties | When |
| - | - | - |
| `game_open` | `is_first_open` (bool), `first_open_at` (ISO time) | Each launch. The Godot and Unity SDKs send it for you. |
| `session_start` | none | A new session starts (launch, or return after 30 minutes idle). Automatic in the Godot and Unity SDKs. |
| `session_end` | `duration_s` (number) | The session ends (quit, or 30 minutes idle). Automatic in the Godot and Unity SDKs. |
| `level_start` | `level`, `attempt` | The player starts a level. |
| `level_complete` | `level`, `attempt`, `score` | The player completes a level. |
| `level_fail` | `level`, `attempt`, `score` | The player fails a level. |
| `resource` | `flow` (`source` or `sink`), `currency`, `amount`, `item` | The player gains (`source`) or spends (`sink`) an in-game resource. |
| `purchase` | `amount_cents`, `currency`, `store` | A real-money purchase. |
| `error` | `severity`, `message`, `error_type`, `handled`, `fingerprint` | A game error. See [Errors and crashes](https://docs.manalens.dev/features/error-tracking.md). |
| `app_unclean_exit` | `previous_session_id`, `previous_build` | The last run crashed. Send it at the next launch, in the crashed session. Automatic in the Godot and Unity SDKs. |
| `game_updated` | `previous_version`, `previous_build` | The first launch after the player updates the game. |

Property values are strings, numbers, booleans or null. Do not send personal data in `message` or other free text.


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