Skip to main content
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.
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 in a build.

Send an event

The Godot SDK and the Unity SDK build this envelope for you. For another engine, send it over HTTP:

The app context

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

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

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 (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 can also point to these hosts.
  • 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 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:
  • 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. 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 (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. 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). 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 and short links for traffic attribution. You can also send app events (context.app and no context.page) from the game code, as in 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 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.
The web SDK does not send game events for you. Send them with plain track calls:
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 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. Property values are strings, numbers, booleans or null. Do not send personal data in message or other free text.