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.
Connect your game
Section titled “Connect your game”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:
| Engine | The plugin | Its settings | What is left to do |
|---|---|---|---|
| Unreal | Plugins/KumoGame | Config/DefaultKumoGame.ini | Rebuild the project |
| Unity | Packages/com.kumo.events | Assets/Resources/KumoEvents.json | Nothing: Unity imports it |
| Godot | addons/kumo_events | kumo_events_settings.gd | Enable kumo events in Project Settings, Plugins |
What the plugins record by themselves
Section titled “What the plugins record by themselves”| Event | When | Value | Props |
|---|---|---|---|
session_start | The game starts | platform, culture, role | |
session_end | The game closes | Seconds played | role |
map_loaded | A level or scene loads | ||
position | Every few seconds, each player (Unreal, where the game is the authority) | ||
perf / server_perf | Every 15 seconds | Frames per second | frame_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) andRecordForPlayer(on the server). - Unity:
KumoEvents.Record,KumoEvents.RecordAtandKumoEvents.RecordForPlayer. CallKumoEvents.SetPlayerwith the player’s online ID once you know it. - Godot:
KumoEvents.record(),record_at(),record_for_player()andset_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.
Bug reports and crashes from Unreal
Section titled “Bug reports and crashes from Unreal”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.
The events API
Section titled “The events API”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 sameidtwice 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.
mapandpositionplace 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.
Answers
Section titled “Answers”| Status | Meaning | What to do |
|---|---|---|
202 | Taken: {"accepted": n}, with "dropped": n for the events the install’s consent left out | Forget the batch |
400 | Not a batch of this shape, or a build label with other characters | Fix it; never resend it |
401 | No key of this project | Check the key; never resend it |
403 | That build’s reports are switched off | Never resend it |
413 | Too large | Send smaller batches |
429 | Over the rate: 600 batches a minute per build, 6000 per project | Keep it and send it later |
503 | Busy for now; Retry-After says how many seconds to wait | Keep it and send it after that |
| Anything else | The server could not take it | Keep 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
Section titled “Remote config”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.
Keys and rules
Section titled “Keys and rules”- 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,xboxorswitch. The plugins send these names. A game that asks itself may also send an engine’s own name, such asWin64,macOSorPS5; - 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.
- build: a pattern, such as
- 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.
In the game
Section titled “In the game”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.
| Engine | Read a value | Told of a change |
|---|---|---|
| Unreal | GetGameInstance()->GetSubsystem<UKumoConfigSubsystem>()->GetBool(TEXT("event.halloween"), false), and GetNumber, GetString, GetJson (also in Blueprints, under kumo, Config) | OnChanged |
| Unity | KumoConfig.GetBool("event.halloween", false), and GetNumber, GetString, GetJson | KumoConfig.Changed |
| Godot | KumoEvents.config.get_bool("event.halloween", false), and get_number, get_string, get_value | KumoEvents.config.changed |
Any other engine
Section titled “Any other engine”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": "..."}.
playeris 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
etagback. The answer is304while nothing changed for that player. - Keep the last values, and use them whenever the answer is anything but
200or304. - The server reads a change within 15 seconds.
Terms and consent
Section titled “Terms and consent”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.
In the game
Section titled “In the game”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.
| Engine | Documents | Consent | Link to the player’s account |
|---|---|---|---|
| Unreal | UKumoConsentSubsystem: GetDocuments, MustAccept, AcceptDocuments | IsConsentAsked, SetAnalyticsConsent, SetCrashReportConsent, GetAnalyticsConsent | SetSession |
| Unity | KumoConsent.Documents, MustAccept, AcceptDocuments() | IsConsentAsked, SetAnalyticsConsent, SetCrashReportConsent, Analytics | SetSession |
| Godot | KumoEvents.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.
Any other engine
Section titled “Any other engine”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
deviceis 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
GETanswers. - A crash from Unreal says the player’s choice in its context, as
<KumoCrashConsent>false</KumoCrashConsent>.
The bug reports API
Section titled “The bug reports API”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.