Gaming Event Spec

This page defines all standard gaming events for Datafly Signal — covering web, mobile, and desktop games. The events span the full player lifecycle: discovery and acquisition, sessions, progression, in-game economy, social play, and retention. Implement these events to enable accurate server-side delivery to advertising and analytics platforms.

All events are sent via datafly.track(). Properties are passed as a flat object in the second argument. Use stable identifiers for game_id, level_id, item_id, and achievement_id — these are used as join keys in your data warehouse, so avoid changing them once live. Never put raw PII (email, phone, name) in track() properties.

Acquisition Events

Events tracking how players discover, evaluate, and sign up for the game.

view_promotion

Fired when a promotional banner, featured-game tile, or store creative is visible to the player.

datafly.track('view_promotion', {
  promotion_id: 'LAUNCH_S3',
  promotion_name: 'Season 3 Launch',
  creative_name: 'season3-hero-v2.mp4',
  creative_slot: 'store-featured'
})

select_promotion

Fired when a player clicks a promotional banner, featured tile, or store creative.

datafly.track('select_promotion', {
  promotion_id: 'LAUNCH_S3',
  promotion_name: 'Season 3 Launch',
  creative_name: 'season3-hero-v2.mp4',
  creative_slot: 'store-featured'
})

search

Fired when a player submits a search query (for games, items, players, or guides).

datafly.track('search', {
  search_term: 'battle royale co-op'
})

generate_lead

Fired when a prospective player submits interest before a full account exists — e.g. a beta waitlist, pre-registration, or newsletter opt-in. Never pass raw email or phone here; the contact PII is hashed server-side via Signal’s identity blueprint.

datafly.track('generate_lead', {
  lead_type: 'pre_registration',
  game_id: 'dungeon_quest',
  value: 0,
  currency: 'GBP'
})

sign_up

Fired when a player completes account registration.

datafly.track('sign_up', {
  method: 'email'
})

login

Fired when a player signs in to their account.

datafly.track('login', {
  method: 'steam'
})

Session Events

Events tracking game sessions from launch to close.

game_started

Fired when a player has launched the game and begun a session.

datafly.track('game_started', {
  game_id: 'dungeon_quest',
  game_version: '2.4.1',
  platform: 'mobile',
  mode: 'single_player'
})

game_ended

Fired when a player’s session has ended.

datafly.track('game_ended', {
  game_id: 'dungeon_quest',
  session_duration_seconds: 1842,
  reason: 'quit'
})

Progression Events

Events tracking player advancement through levels, tutorials, and achievements.

tutorial_started

Fired when a player has entered a tutorial sequence.

datafly.track('tutorial_started', {
  tutorial_id: 'tut_basic_controls'
})

tutorial_completed

Fired when a player has finished a tutorial sequence.

datafly.track('tutorial_completed', {
  tutorial_id: 'tut_basic_controls',
  duration_seconds: 95,
  skipped_steps: 0
})

tutorial_skipped

Fired when a player has opted to skip a tutorial.

datafly.track('tutorial_skipped', {
  tutorial_id: 'tut_advanced_crafting',
  at_step: 3
})

level_started

Fired when a player has begun a level or stage.

datafly.track('level_started', {
  level_id: 'world_2_level_4',
  level_name: 'The Dark Cavern',
  attempt: 1
})

level_completed

Fired when a player successfully finishes a level. For failures, send the dedicated level_failed event below.

datafly.track('level_completed', {
  level_id: 'world_2_level_4',
  level_name: 'The Dark Cavern',
  score: 48200,
  stars: 3,
  duration_seconds: 147,
  attempt: 2
})

level_failed

Fired when a player has failed a level.

datafly.track('level_failed', {
  level_id: 'world_2_level_4',
  level_name: 'The Dark Cavern',
  score: 12400,
  duration_seconds: 63,
  attempt: 1,
  failure_reason: 'no_lives'
})

achievement_unlocked

Fired when a player has unlocked an achievement or badge.

datafly.track('achievement_unlocked', {
  achievement_id: 'ach_speed_runner',
  achievement_name: 'Speed Runner',
  achievement_type: 'speed',
  points: 50
})

Economy Events

Events tracking real-money purchases, virtual-currency flows, and in-game item usage.

item_purchased

Fired when a real-money (IAP or store) purchase of an item, bundle, or currency pack completes successfully. This is the most important monetisation event — ensure it fires reliably and carries a unique transaction_id for deduplication.

datafly.track('item_purchased', {
  transaction_id: 'IAP-10042',
  value: 9.99,
  currency: 'GBP',
  items: [
    {
      item_id: 'pack_gems_1200',
      item_name: '1,200 Gems Pack',
      item_category: 'currency_pack',
      price: 9.99,
      quantity: 1,
      currency: 'GBP'
    }
  ]
})

currency_earned

Fired when a player receives virtual currency.

datafly.track('currency_earned', {
  virtual_currency_name: 'coins',
  value: 500,
  source: 'level_complete'
})

currency_spent

Fired when a player spends virtual currency.

datafly.track('currency_spent', {
  virtual_currency_name: 'gems',
  value: 200,
  item_id: 'powerup_shield_x3',
  item_name: 'Shield Pack x3'
})

item_equipped

Fired when a player equips an item to their character or loadout.

datafly.track('item_equipped', {
  item_id: 'skin_dragon_red',
  item_name: 'Red Dragon Skin',
  slot: 'character_skin'
})

Social Events

Events tracking multiplayer activity, friend interactions, and community features.

friend_invited

Fired when a player sends a friend or referral invitation, or shares a clip, score, or achievement to a social channel.

datafly.track('friend_invited', {
  invitation_method: 'link_share',
  content_type: 'invite'
})

match_started

Fired when a multiplayer match has begun.

datafly.track('match_started', {
  match_id: 'match_9f3a2c1e',
  match_type: 'ranked',
  player_count: 10,
  game_mode: 'battle_royale'
})

match_completed

Fired when a multiplayer match has ended.

datafly.track('match_completed', {
  match_id: 'match_9f3a2c1e',
  outcome: 'win',
  score: 2840,
  duration_seconds: 624,
  rank_change: 18
})

leaderboard_viewed

Fired when a player opens a leaderboard or posts a score to a scoreboard.

datafly.track('leaderboard_viewed', {
  leaderboard_id: 'ldr_season_3_ranked',
  scope: 'friends',
  score: 48200
})

Retention & Monetisation Events

Events tracking returning players, ad engagement, and re-engagement.

ad_impression

Fired when an in-game ad (rewarded, interstitial, or banner) is shown to the player.

datafly.track('ad_impression', {
  ad_platform: 'admob',
  ad_format: 'rewarded',
  ad_unit_name: 'extra_life_reward',
  value: 0.012,
  currency: 'USD'
})

Items Array Schema

Vendor Mapping

The table below shows how Datafly Signal maps gaming events to the native event names expected by each vendor’s server-side API. Signal uses its own established snake_case event names as the canonical format (left column), and blueprints handle the transformation to vendor-specific payloads. Where GA4 has a native gaming event, that native name appears in the GA4 column; Signal’s event name does not change.