Analytics Events and Sinks

Event shape

trackEvent sends a bounded analytics event for the published game. Creators can see rollups such as event count, unique players, retained players, top event names, and top sources.

Use event names as stable identifiers. Use stage for the current level, mission, room, wave, biome, or tutorial step. Use source for where something came from, such as tutorial, shop, reward, spawn, referral, or enemy type.

• name: required, max 64 characters.
• stage: optional, max 80 characters.
• source: optional, max 80 characters.
• value: optional finite number.
• metadata: optional object, max 12 primitive keys.
• metadata string values: max 120 characters.

await QubizSDK.requestPermissions(["analytics:events"]);

await QubizSDK.trackEvent({
  name: "level_reached",
  stage: "world-2-room-4",
  source: "main-path",
  value: 2,
  metadata: {
    difficulty: "normal",
    deaths: 3,
    usedAssist: false
  }
});

Recommended event names

Use a small vocabulary of stable event names. Stable names make dashboards useful; random or overly specific names fragment your data.

• game_started - player reached the playable game loop.
• tutorial_step - player completed or failed a tutorial step.
• level_started - player entered a level, stage, room, or wave.
• level_reached - player reached a milestone inside the progression.
• level_completed - player completed a level or mission.
• run_failed - player lost a run; stage can show where.
• currency_earned - player earned coins, gems, XP, or points.
• currency_spent - player spent a resource; source can show the sink.
• item_acquired - player received an item, skin, ability, or card.
• source_seen - player arrived from a menu, referral, portal, reward, or spawn source.

Funnels and retention

Retention in the creator dashboard is currently calculated from real event days: a retained player is a player with events on more than one day. That is simple but source-backed.

For useful funnels, send events at the same grain: one event per meaningful step, not every frame. For example, game_started, tutorial_step, level_started, level_completed, run_failed.

await QubizSDK.trackEvent({
  name: "currency_earned",
  source: "daily_reward",
  value: 100,
  metadata: {
    rewardType: "coins",
    streakDay: 5
  }
});