In-game events#

Report what happens inside your game — a boss killed, a chapter finished, a flower picked up — and read it back as counts, trends and funnels. Events are arbitrary strings you choose; we never need to know what they mean in advance.

The same events also power in-game event quests: an admin picks an event and a count ("kill 5 monsters") and the quest validates itself from what you already send. No verification endpoint, no extra call.

Concepts#

Event: A lowercase name (killed_boss, world:boss.killed) plus optional properties. New names are discovered automatically the first time you send them, up to 500 per project.
Actor: Who did it. Send a partner_user_id (your own user id) when you know it, or a device_id when the player is not signed in. One of the two is required.
Identity resolution: Events sent for a device_id or an unlinked partner_user_id are kept and attributed retroactively the moment that player links their Gamearly account. Nothing collected before linking is lost.
count: One report standing in for N occurrences. count: 5 is exactly equivalent to five separate events for every purpose, including quest progress.
Timed events: Start a stopwatch, stop it later, get a duration on the event.
Tags and traits: What you know about the player rather than the moment. See Player tags & traits — they are what lets every chart be split by cohort.
Test mode: Add "test": true to any write call and nothing you send can reach a real player or a real chart. See Test mode. Start here when integrating.

Authentication and scopes#

Your project has two keys, and events are where the difference matters most. See Authentication for the full picture.

Scope	Grants	Public key
`events:write`	Ingest events, timers, device identification, player tags and traits	✅
`events:read`	Counts, trends, funnels, event search, per-player lookups	opt-in
`events:trusted`	Mark ingested events as trusted (see below)	private only
`events:import`	Bulk historical backfill with arbitrary timestamps	private only
`events:wipe`	Delete your project's test data	private only

Send telemetry with the public key (gak_pub_…) from inside your game. Everything else on this page assumes that.

Trust#

The one thing to get right.

The key inside your game build is not a secret

Anyone who owns your game can extract it and post whatever they like for whatever partner_user_id they like. No request signature fixes that, because the signing material would ship too.

So we do not pretend otherwise. Instead:

Events sent with your public key are recorded as untrusted. They count in every chart and every total — untrusted is the normal case, not an error state.
Events sent with your private key are recorded as trusted, because that key holds events:trusted and never leaves your server.
A project can set "require trusted events for quests", after which only trusted events advance quest progress.

The recommended integration follows directly: telemetry from the client with the public key, quest-critical events from your server with the private key. The key in the build cannot buy anything.

Turning on 'require trusted events' before your server sends anything

The setting makes quest progress count trusted_count instead of the total. If your game is still reporting everything with the public key, that number is zero — quests simply stop advancing, with no error anywhere. It is the quietest way to break your own integration.

So the dashboard will not let you enable it until your private key has been used at least once. If the toggle is disabled, send one event from your server first.

Even without any of that, the structural limit still holds: quest progress is clamped to the task's target, so a client flooding a million events earns exactly one completion.