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.appand nocontext.page. Itschannelisapp. - A web event has
context.page. Itschannelisweb. It can also sendcontext.app: see Browser and Electron games. - An event with neither
context.pagenorcontext.appis refused. - App events are
trackoridentify. Apageevent needs a page; send atrackevent such asscreen_viewfor a game screen. original_timestampcan 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 with400. 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 theanonymous_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 gets400with 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
Originheader, 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 gets403. - Country comes from the request IP, as for the web. The IP and the user agent are never stored.
- Install match. A first
game_opencan get the anonymous ID of a recent website visitor from the same network. The optionalcontext.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 isdesktop, ormobilefor Android and iOS. A web export (platform: web) keeps the device, OS and browser of its browser user agent. A bot user agent keeps thebotlabel. - Channel (acquisition) is
Direct. A game has no referrer. - The per-project ingest limit is the same as for the web.
Identify
Send anidentify 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 anOrigin header. The collector applies the normal origin rule:
- Served from your project domain (for example
play.example.comfor project domainexample.com): accepted. The collector answers the CORS preflight for your domain. Sendcontext.appwithplatform: web, or sendcontext.pageas 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.zoneis in the list by default): accepted, with CORS headers for that origin. Sendcontext.appwithplatform: 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.zoneis saved ashtml-classic.itch.zone, and bothhttpandhttpsmatch. - A wildcard needs at least two labels after
*., so*.comis 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 theOriginheader). Any other page host gets403(Page domain does not match project). So the web SDK works in a portal iframe once the portal host is listed.
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 sendcontext.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 takebreakdown=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 exampleplay.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.
track calls:
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 sendapp_unclean_exit from Electron only:
- At start, save a “running” flag with the session ID and the build (for example in a file in the user data folder).
- At a normal quit, clear the flag.
- At the next start, check the flag. If it is still set, the last run did not quit normally. Send
app_unclean_exitwithprevious_session_idandprevious_build.
Electron main process
Use the web SDK with theapp 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 flattrack 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.