Tracking best practices

None of these rules are complicated. All of them are the difference between data you can trust and data you'll spend an afternoon second-guessing six months from now.

General

• Always include player_id on every event. It's how events tie back to individual players — an event without it is a fact about nobody.
• Use ISO 8601 timestamps with timezone info: "2026-03-11T13:14:58.123Z". The SDKs do this for you; it only comes up if you're on the REST API.
• Keep IDs consistent across events. If a level is "world1_level12" in progression_start, it's the same string in progression_complete. Different spellings of the same thing are two different things to any analytics system.

Economy events

• Don't fire economy_earn on every coin pickup. If the player collects 50 coins during a level, send one event at level end with amount: 50. Your event volume stays sane and the data means the same thing.
• Always include balance_after. It lets us verify economy consistency and catch anomalies — a balance that jumps without a matching earn event is either a bug or an exploit, and you want to know about both.

Progression events

• Send progression_start before progression_complete or progression_fail. The start event establishes the attempt context; completions without starts are answers without questions.
• Use a hierarchical level_id format like "world1_stage3_level12" — it lets you analyse at whichever granularity turns out to matter.

Purchases

• Validate receipts server-side before sending purchase_completed. Never trust the client for revenue data — not because your players are criminals, but because some of them are.
• Set is_first_purchase: true on a player's first purchase. First conversion is one of the most important moments in a player's life, and it's much easier to mark it at the source than to reconstruct it later.

Validation

• Use POST /v1/events/validate during development. It checks events against your tracking plan and returns detailed errors without storing anything. Wire it into CI or your QA pass — schema drift is far cheaper to catch before release than after a week of malformed events.