Skip to content
kumo

Game Events API

Your game posts its events to your studio’s kumo server, and Insights charts them: players and sessions, where they go and die on each level, the frame rate on every machine, and anything else the game records.

There are two ways in. kumo’s own plugin for Unreal, Unity or Godot sends everything for you. Any other engine calls the API below itself.

On Insights, press + and choose Connect your game. It shows two values:

  • Address: where your game posts, for example https://studio.example/hooks/events/<studio>/<project>.
  • Project key: what every build of the game posts with.

The key is not a secret. It ships inside the game and can only add events and bug reports. You need permission to run the project’s builds to see it.

When kumo on your computer has the game’s Unreal, Unity or Godot project open, the panel also offers Add kumo’s plugin to this project. It copies the plugin into the project and writes its settings file with the address and the key:

EngineThe pluginIts settingsWhat is left to do
UnrealPlugins/KumoGameConfig/DefaultKumoGame.iniRebuild the project
UnityPackages/com.kumo.eventsAssets/Resources/KumoEvents.jsonNothing: Unity imports it
Godotaddons/kumo_eventskumo_events_settings.gdEnable kumo events in Project Settings, Plugins
EventWhenValueProps
session_startThe game startsplatform, culture, role
session_endThe game closesSeconds playedrole
map_loadedA level or scene loads
positionEvery few seconds, each player (Unreal, where the game is the authority)
perf / server_perfEvery 15 secondsFrames per secondframe_ms, longest_ms, hitches

Record your own events too, such as a kill, a death, a match’s end or a purchase:

  • Unreal: from Blueprints, use the kumo Events subsystem’s Record, RecordAt (a place in the level) and RecordForPlayer (on the server).
  • Unity: KumoEvents.Record, KumoEvents.RecordAt and KumoEvents.RecordForPlayer. Call KumoEvents.SetPlayer with the player’s online ID once you know it.
  • Godot: KumoEvents.record(), record_at(), record_for_player() and set_player().

By default the plugins do not send from a Shipping or release build. Switch that on in the settings file for a demo, Early Access or a released game.

kumo’s Unreal plugin also has an in-game bug report form. F8 (or both shoulder buttons with the view button on a controller) opens it over the game. Sending it files a bug on the board with a screenshot, the log’s last lines, the build, platform, level, the player’s place and view, and whatever the game added with the kumo Report subsystem’s SetContext. A build recorded as a playtest’s files feedback instead. Its own switch for Shipping builds is in the same settings file.

Without a crash service, Unreal’s own crash reporter can send crashes to the studio’s server too: one bug per crash, counted on every later one, its minidump read with the build’s symbols into the game’s own functions, files and lines (Readable crashes). The panel shows the lines to add to Config/DefaultEngine.ini. Launching a build with -KumoTestCrash crashes it as it starts, to see one arrive; a Blueprint or C++ can call the kumo Events subsystem’s TestCrash instead.

Switching a build’s reports off on the Builds page refuses that build’s events, reports and crashes.

POST /hooks/events/<studio>/<project>
Authorization: Events <project key>
Content-Type: application/json
{
"build": "1.4.2",
"session": "a run of the game",
"player": "who plays, hashed",
"device": "this install, hashed",
"events": [
{
"id": "unique per event",
"name": "death",
"at": "2026-10-12T10:00:00Z",
"map": "/Game/Maps/LV_Docks",
"position": [1200, -340, 90],
"value": 1,
"props": { "weapon": "axe" }
}
]
}

Only name is required in each event:

  • name: letters, digits and _ . : -, starting with a letter or a digit, up to 80 characters.
  • id: send the same id twice and the event is kept once. Give every event one, so a batch you retry after a timeout never counts twice.
  • at: an ISO 8601 time, or seconds since 1970. It defaults to when the server received the event. A time more than 30 days old, or a day ahead, is replaced by the time received.
  • player: names someone other than the batch’s player, such as a kill recorded on a server.

On the batch, device is the install the game runs on, hashed as players are. It is what consent is kept by (see Terms and consent). A batch from the studio’s own game server says "role": "server": it is no player’s install, and its events are taken whatever consent says.

  • map and position place the event in Insights’ level maps.
  • value: the figure that charts sum or average.
  • props: up to 30 more numbers, flags or short texts.

Name players with a hash, never with an account, a name or an address. kumo’s plugins send the first 16 hexadecimal digits of the SHA-1 of kumo:<game>:<online id>.

build is your own label for the build: the project’s version, or your pipeline’s build number. When it names a build kumo has recorded, the event links to that build. If that build’s reports are switched off in QA, its events are refused.

A batch holds at most 2000 events and 4 MB. Send one every few seconds, not one per event. A batch may be sent gzip-compressed with Content-Encoding: gzip; the 4 MB is counted once it is unpacked.

202 means the events are stored: the server answers once they are on disk, never before, so a batch it took is never lost.

StatusMeaningWhat to do
202Taken: {"accepted": n}, with "dropped": n for the events the install’s consent left outForget the batch
400Not a batch of this shape, or a build label with other charactersFix it; never resend it
401No key of this projectCheck the key; never resend it
403That build’s reports are switched offNever resend it
413Too largeSend smaller batches
429Over the rate: 600 batches a minute per build, 6000 per projectKeep it and send it later
503Busy for now; Retry-After says how many seconds to waitKeep it and send it after that
Anything elseThe server could not take itKeep it and send it later

Switching a build’s reports off is refused everywhere within half a minute.

The events are kept on the studio’s server for 400 days. Only the people of the project can read them. Insights charts every event of the period you choose, however many there are.

Remote config holds values the game reads as it plays, which you change without shipping a new build: a discount, an event switched on, a difficulty tuned. Edit them in Insights, under Remote config.

  • Each key has a kind: on or off, a number, text or JSON. It also has the value everyone gets.
  • A rule gives some players another value. It can match by:
    • build: a pattern, such as 1.4.*;
    • platform: windows, mac, linux, android, ios, web, playstation, xbox or switch. The plugins send these names. A game that asks itself may also send an engine’s own name, such as Win64, macOS or PS5;
    • a share of players: for example 10%. A player stays in the same share on every launch, and two 10% rollouts of different keys reach different players.
  • The first rule that matches a player wins.
  • Every change is kept. Put back as it was undoes one.
  • Changing remote config needs the Change the game’s remote config permission, which Producers and Leads have.

The plugins ask for the config at launch and every 15 minutes, in release builds too. They keep the last answer on disk, so a game that starts offline still has the last values it heard. Until it has any, each getter answers the default you pass.

EngineRead a valueTold of a change
UnrealGetGameInstance()->GetSubsystem<UKumoConfigSubsystem>()->GetBool(TEXT("event.halloween"), false), and GetNumber, GetString, GetJson (also in Blueprints, under kumo, Config)OnChanged
UnityKumoConfig.GetBool("event.halloween", false), and GetNumber, GetString, GetJsonKumoConfig.Changed
GodotKumoEvents.config.get_bool("event.halloween", false), and get_number, get_string, get_valueKumoEvents.config.changed

Ask with the project key, as the events are sent:

GET /hooks/config/<studio>/<project>?build=1.4.2&platform=windows&player=<player id>
Authorization: Events <project key>
If-None-Match: "<the etag of the last answer>"

The answer is {"values": {"event.halloween": true, "shop.discount": 0.2}, "etag": "..."}.

  • player is any stable id for the player, such as the hash the events use. Without it, the player is in no partial rollout.
  • Send the last etag back. The answer is 304 while nothing changed for that player.
  • Keep the last values, and use them whenever the answer is anything but 200 or 304.
  • The server reads a change within 15 seconds.

Publish the game’s EULA, terms, privacy policy and community guidelines in Legal, under Compliance. Each version has its own address that never changes. When you publish one, say whether players must accept it again before they play: tick this for a material change. Any other new version is only shown to players as changed.

Where the law asks consent before any analytics, as in the EEA, the United Kingdom, Switzerland, Brazil, China, South Korea and Turkey, no event is sent until the player allows it. A country the server cannot tell counts as one that asks. Elsewhere analytics are on until the player turns them off. Crash reports are on until the player turns them off, everywhere.

The plugins hold events in memory while consent is pending, send them once the player allows it, and drop them, with every batch kept on disk, once they refuse. The server enforces it too: it drops the events of an install that has not allowed them, and a crash whose player turned crash reports off.

At launch, the plugins ask for the documents and the consent the player gave before. They keep what the player says on disk and send it when online.

EngineDocumentsConsentLink to the player’s account
UnrealUKumoConsentSubsystem: GetDocuments, MustAccept, AcceptDocumentsIsConsentAsked, SetAnalyticsConsent, SetCrashReportConsent, GetAnalyticsConsentSetSession
UnityKumoConsent.Documents, MustAccept, AcceptDocuments()IsConsentAsked, SetAnalyticsConsent, SetCrashReportConsent, AnalyticsSetSession
GodotKumoEvents.consent.documents, must_accept(), accept_documents()is_consent_asked(), set_analytics_consent(), set_crash_report_consent(), analytics()set_session()

Show the documents when MustAccept is true, each with its own address, and call AcceptDocuments once the player accepts them. Ask for consent when IsConsentAsked is true. Once the player signs in, pass their Nakama session token to SetSession. The server checks the session with your game backend, then reads what this install accepted as that player’s.

Players can also accept the documents on the game’s portal, under Terms and policies. The portal takes no vote, idea or request for help from a player who has not accepted what they must. The player console shows what each player accepted and allowed. A privacy request exports it, and a deletion removes it.

Ask with the project key, as the events are sent:

GET /hooks/consent/<studio>/<project>?device=<install id>
Authorization: Events <project key>

The answer lists each document and where the install stands:

{
"documents": [{"slug": "eula", "kind": "eula", "title": "EULA", "version": 3, "sha256": "...",
"url": "https://.../hooks/terms/<studio>/eula/3", "accepted": 2,
"must_accept": true, "changed": false}],
"consent": {"required": true, "country": "IT", "analytics": null, "crashes": true},
"etag": "..."
}

Send what the player said:

POST /hooks/consent/<studio>/<project>
Authorization: Events <project key>
Content-Type: application/json
{"device": "<install id>", "accept": [{"slug": "eula", "version": 3, "sha256": "..."}],
"analytics": true, "crashes": true, "session": "<the player's Nakama session token>"}
  • Every field but device is optional. Send only what the player said.
  • A version is accepted only as it is published now, with its hash. The player accepts what they were shown.
  • The answer is where the install stands afterwards, as the GET answers.
  • A crash from Unreal says the player’s choice in its context, as <KumoCrashConsent>false</KumoCrashConsent>.

A game of any engine can file bug reports with the same key:

POST /hooks/report/<studio>/<project>
Authorization: Report <project key>
Content-Type: application/json
{
"build": "1.4.2",
"kind": "bug",
"title": "Fell through the dock",
"text": "Jumped off the crane and kept falling.",
"severity": "S2 Critical",
"platform": "Windows",
"map": "/Game/Maps/LV_Docks",
"position": [1200, -340, 90],
"context": { "quest": "ferry" },
"screenshot": "<a JPEG, base64>"
}

Every field is optional. kind is bug or feedback. log takes the log’s last lines, hardware the machine, culture the language, and rotation the view as [pitch, yaw, roll].

It answers 201 with {"task": "T-42"} once filed, and like the events API otherwise, at 30 reports a minute per build and 120 per project. A report is at most 8 MB, its screenshot included. Keep a report you could not send, and send it again later, unless it was refused with 400, 401, 403 or 413.