Game events

Game events are ordinary events with agreed names. Send them with track() from any SDK and the Game report fills itself in: where players get stuck, how long they play, and what crashes. They also work in every other report, like funnels and retention.

Levels#

// The same "level" on every event of one attempt
analytics.track("level_start", { level: 3 });

// ...the player wins
analytics.track("level_complete", { level: 3, duration: 74, score: 1200 });

// ...or loses
analytics.track("level_fail", { level: 3, duration: 41, reason: "died" });

• Use the same level value on the start and the end of an attempt, or they won't line up.
• level can be a number or a name. Numbers sort naturally (1, 2, 10), and names come after them, so "boss" follows your numbered levels.
• Send duration in seconds. The report shows the median time to complete each level.
• reason is up to you ("died", "timeout", "quit"). Break level_fail down by it in Insights to see why players lose.

Errors and crashes#

analytics.track("$exception", {
  $exception_type: "NullReferenceException",
  $exception_message: "Object reference not set",
  fatal: false, // true counts as a crash
});

fatal: true marks a crash. Errors are grouped by type and message (the first 300 characters), so keep changing details like ids or file paths out of the message.

You often don't need to send these yourself. The Unity and Godot SDKs report unhandled errors as non-fatal $exception events, and the iOS and Android SDKs record uncaught exceptions as crashes. Each can be turned off; see the page for your engine.

Sessions, platforms and versions#

Nothing to send here. The SDKs start a session on the first event and a new one after 30 minutes without any, and they add the platform and your app_version to every event. The engine and mobile SDKs read the version from your project settings, and each lets you override it. See Context.

What the Game report shows#

The Game page is in the sidebar of projects set up as a game. You can filter the whole report to one platform or app version.

• Headline numbers: players, sessions, median and average session length, level completion rate with the hardest level, and crash-free sessions with the error rate.
• Activity chart: players, sessions and sessions with errors over time.
• Levels: for each level, starts, completions and fails (as a share of starts), the median completion time, how many players reached it, and where players are right now (the level they started most recently).
• Sessions: session count, players, length, and error and crash rates per platform or per app version, so a bad build stands out.
• Errors and crashes: the most frequent errors with how many players hit them, how many were fatal, when they were last seen and which version reported them most.

How the numbers are counted

• The hardest level is the one with the highest fail rate among levels started at least 10 times.
• Crash-free sessions are sessions without a fatal error.
• The error rate is the share of sessions with any error.
• A session's platform and version are those of its first event, so a session that updates mid-way still counts once.

Economy, ads and purchases#

The Game report reads only the events above, but any event works in Insights. These names are a good start for the rest of your game:

analytics.track("resource_earned", { resource: "gold", amount: 50, source: "quest" });
analytics.track("resource_spent", { resource: "gold", amount: 30, item: "sword" });
analytics.track("ad_watched", { placement: "extra_life", reward: true });
analytics.track("purchase_completed", { item: "gem_pack_s", revenue: 4.99, currency: "USD" });

A revenue property on any event counts as money in your reports. See Revenue.