Client event reference
Every client-side PlayGenus event — sessions, screens, tutorials, ads, crashes, performance — with full property schemas and examples.
These events are recommended for the Client SDK. Some are collected
automatically; the rest need a track() call at the right moment in your
game code. If your tracking plan includes them, your generated SDK has a
typed method for each — no string-typing event names.
Wondering which of these apply to your game at all? That's decided by your progression model.
Session events
Collected automatically. No code needed.
| Event | When it fires | What it tells you |
|---|---|---|
session_start | Player opens your game | A new session began, with device info attached |
session_end | Player closes or backgrounds your game | How long they played, how many events in the session |
session_foreground | Player returns from background | How long they were away |
Properties — session_start:
| Property | Type | Required | Example |
|---|---|---|---|
device_model | string | No | "iPhone 14 Pro" |
os_name | string | No | "iOS" |
os_version | string | No | "17.2" |
app_version | string | Yes | "1.2.3" |
screen_width | int | No | 1170 |
screen_height | int | No | 2532 |
locale | string | No | "en_US" |
timezone | string | No | "America/New_York" |
connection_type | string | No | "wifi", "cellular", or "offline" |
Properties — session_end:
| Property | Type | Required | Example |
|---|---|---|---|
session_duration_seconds | int | Yes | 342 |
events_in_session | int | No | 47 |
Properties — session_foreground:
| Property | Type | Required | Example |
|---|---|---|---|
background_duration_seconds | int | Yes | 120 |
UI & engagement events
You call these — the SDK can't know which screen counts as "the shop".
screen_view
Track when the player moves between screens. This is how you learn where players actually spend their time (and where they wander off).
| Property | Type | Required | Example |
|---|---|---|---|
screen_name | string | Yes | "main_menu", "shop", "level_select" |
previous_screen | string | No | "main_menu" |
time_on_previous_seconds | int | No | 15 |
ui_click
Specific button taps, for detailed UX analysis. Optional — track the interactions you care about, not every tap.
| Property | Type | Required | Example |
|---|---|---|---|
element_id | string | Yes | "btn_play", "btn_shop_gems" |
element_type | string | No | "button", "toggle", "tab" |
screen_name | string | No | "main_menu" |
tutorial_step
Each milestone in your tutorial flow. Tutorial drop-off is one of the biggest early-churn signals there is, so this one earns its place.
| Property | Type | Required | Example |
|---|---|---|---|
step_id | string | Yes | "welcome", "first_match", "first_purchase" |
step_name | string | No | "Welcome Screen" |
step_index | int | Yes | 1 |
total_steps | int | No | 8 |
tutorial_complete
| Property | Type | Required | Example |
|---|---|---|---|
total_duration_seconds | int | Yes | 180 |
steps_completed | int | Yes | 8 |
steps_skipped | int | No | 0 |
feature_unlocked
The player discovered or unlocked a new game feature.
| Property | Type | Required | Example |
|---|---|---|---|
feature_id | string | Yes | "daily_challenges", "clan_wars" |
feature_name | string | No | "Daily Challenges" |
unlock_method | string | No | "level_reached", "iap", "tutorial" |
social_share
The player shared something outside the game.
| Property | Type | Required | Example |
|---|---|---|---|
share_target | string | Yes | "twitter", "facebook", "instagram", "clipboard" |
content_type | string | No | "score", "screenshot", "replay" |
Ad events
Call these from your ad SDK's callbacks — when ironSource, AppLovin, or AdMob fires an event, mirror it to PlayGenus.
ad_requested
| Property | Type | Required | Example |
|---|---|---|---|
ad_type | string | Yes | "rewarded", "interstitial", "banner" |
ad_network | string | No | "ironsource", "applovin", "admob" |
placement_id | string | No | "level_complete_reward" |
ad_shown
| Property | Type | Required | Example |
|---|---|---|---|
ad_type | string | Yes | "rewarded" |
ad_network | string | No | "ironsource" |
placement_id | string | No | "level_complete_reward" |
screen_name | string | No | "level_complete" |
ad_clicked
| Property | Type | Required | Example |
|---|---|---|---|
ad_type | string | Yes | "interstitial" |
ad_network | string | No | "admob" |
placement_id | string | No | "between_levels" |
ad_completed
Fires when a rewarded ad is watched to the end.
| Property | Type | Required | Example |
|---|---|---|---|
ad_type | string | Yes | "rewarded" |
ad_network | string | No | "applovin" |
placement_id | string | No | "extra_life" |
reward_type | string | No | "coins", "life", "booster" |
reward_amount | int | No | 50 |
ad_failed
| Property | Type | Required | Example |
|---|---|---|---|
ad_type | string | Yes | "rewarded" |
ad_network | string | No | "ironsource" |
placement_id | string | No | "extra_life" |
error_code | string | No | "NO_FILL" |
error_message | string | No | "No ad available" |
Performance & error events
app_crash
Collected automatically — the Unity SDK hooks the engine's log callback and reports any unhandled managed exception, including its stack trace (truncated to 1 KB) and the last screen the player saw.
Scope: this covers unhandled managed (C#) exceptions. Native crashes — engine or plugin segfaults that kill the process outright — aren't visible to this hook. If you need those, run a dedicated native crash reporter alongside PlayGenus.
| Property | Type | Required | Example |
|---|---|---|---|
exception_type | string | Yes | "NullPointerException" |
exception_message | string | No | "Object reference not set" |
stack_trace | string | No | (truncated to 1 KB) |
screen_name | string | No | "gameplay" |
error
Report errors explicitly, when you want them.
| Property | Type | Required | Example |
|---|---|---|---|
severity | string | Yes | "debug", "info", "warning", "error", "critical" |
message | string | Yes | "Failed to load level assets" |
context | string | No | "level_loader" |
performance_sample
You sample and send this yourself — the SDK generates a typed method but doesn't collect it automatically, so you stay in control of the profiling cost. Every 60 seconds from your game loop is a reasonable default.
| Property | Type | Required | Example |
|---|---|---|---|
fps_avg | float | Yes | 58.3 |
fps_min | float | No | 24.1 |
memory_used_mb | float | No | 312.5 |
scene_name | string | No | "gameplay" |
Device context
Not a separate event — a block of properties automatically attached to every event the Client SDK sends:
| Property | Type | Example |
|---|---|---|
device_model | string | "Samsung Galaxy S24" |
os_name | string | "Android" |
os_version | string | "14" |
app_version | string | "1.2.3" |
sdk_version | string | "0.1.0" |
screen_width | int | 1080 |
screen_height | int | 2340 |
locale | string | "de_DE" |
timezone | string | "Europe/Berlin" |
connection_type | string | "wifi" |
Progression models
PlayGenus tags every game with one of four progression models — discrete levels, match-based, soft progression, or open world — and that tag decides which analytics events your game should track.
Server event reference
Server-side PlayGenus events — purchases, subscriptions, progression, economy, player lifecycle, matchmaking, guilds, LiveOps, moderation — with full property schemas.