Analytics Events API

Track player behavior, game events, and custom metrics to understand how players interact with your game

Overview

Analytics System Features

Track any custom events with flexible properties to understand player behavior

📊 Core Features

  • • Track any custom events (level_complete, item_purchased, etc.)
  • • Flexible event properties with nested objects
  • • Automatic batching and offline queuing
  • • Real-time dashboard analytics
  • • Player segmentation and retention metrics
  • • JSON data with UTF-8 encoding
  • • Automatic compression during transfer

Send Analytics Events

POST /v1/player/events

Send one or more analytics events with custom properties

POST

Single Event Request

Batch Events Request

Response Format

Event Structure

Event Fields and Properties

Understanding event structure and property limitations

Required Fields

  • event - Event name (string, max 50 chars)
  • timestamp - When event occurred (ISO 8601)

Optional Fields

  • properties - Custom data (object, max 512B)
  • session_id - Group related events (string)

Event Properties Examples

Event Batching

Optimizing Event Delivery

Best practices for sending events efficiently

✅ Best Practices

  • • Batch events: send up to 100 events per request
  • • Queue events locally during offline periods
  • • Use session IDs to group related events
  • • Implement exponential backoff for retries

❌ Common Mistakes

  • • Sending each event in separate requests
  • • Missing error handling for failed events
  • • Tracking too many granular events

SDK Integration Examples

Track Events with StatPotion SDKs

Simple integration examples for Unity and Godot

Complete Event Tracking Examples

Common Event Types

Recommended Events for Games

Standard events that provide valuable player insights

🎮 Gameplay Events

  • level_start - Player begins a level
  • level_complete - Player finishes a level
  • level_fail - Player fails/quits a level
  • game_over - Game session ends
  • achievement_unlock - Player earns achievement

💰 Monetization Events

  • item_purchase - Player buys in-game item
  • currency_earn - Player gains currency
  • currency_spend - Player spends currency
  • ad_view - Player watches advertisement
  • shop_visit - Player visits shop

📊 Engagement Events

  • session_start - Player starts game session
  • session_end - Player ends game session
  • tutorial_step - Player progresses in tutorial
  • settings_change - Player modifies settings
  • social_share - Player shares content

🔧 Technical Events

  • error_occurred - Game error or crash
  • performance_metric - FPS, load times
  • feature_usage - Player uses specific feature
  • device_info - Device/platform information
  • app_install - First time app launch

Troubleshooting Analytics Issues

Problem: Events not appearing in dashboard

Solution: Check that events are being sent successfully.