Docs/Getting Started/Understanding Events

Understanding Events

Learn the core concepts of event tracking in Ilara — how events work, why they matter, and how to design your event schema.

8 min read

What Are Events?

Events are discrete actions or occurrences in your game that you want to track. Each event has a name and optional properties that provide context.

Event Structure
json
{
  class="code-string">"event_name": class="code-string">"level_complete",
  class="code-string">"player_id": class="code-string">"uuid-123-456",
  class="code-string">"timestamp": class="code-string">"2025-01-25T10:30:00Z",
  class="code-string">"properties": {
    class="code-string">"level": 5,
    class="code-string">"score": 12500,
    class="code-string">"time_seconds": 180,
    class="code-string">"stars_earned": 3,
    class="code-string">"items_collected": [class="code-string">"coin", class="code-string">"gem", class="code-string">"key"]
  }
}
Event Ingestion
Events are processed in real-time with <100ms P99 latency. They're immediately available for queries, segments, and AI analysis.

Types of Events

Lifecycle Events

Track major player journey milestones:

EventWhen to TrackKey Properties
session_startPlayer opens the gameplatform, version, device
session_endPlayer closes the gameduration_seconds, reason
tutorial_startTutorial beginsskip_available
tutorial_completeTutorial finishedduration_seconds, steps_completed
first_purchaseFirst IAPproduct_id, amount, currency

Gameplay Events

Track core gameplay actions:

EventWhen to TrackKey Properties
level_startLevel beginslevel, difficulty, mode
level_completeLevel finishedlevel, score, time, stars
level_failLevel failedlevel, reason, retry_count
achievement_unlockAchievement earnedachievement_id, name
item_collectItem picked upitem_id, item_type, value

Economy Events

Track virtual and real currency flows:

EventWhen to TrackKey Properties
currency_earnPlayer gains currencycurrency_type, amount, source
currency_spendPlayer spends currencycurrency_type, amount, item_id
purchase_startIAP flow beginsproduct_id, price
purchase_completeIAP successfulproduct_id, amount, currency
purchase_failIAP failedproduct_id, error_code

Social Events

Track social interactions:

EventWhen to TrackKey Properties
friend_addFriend addedfriend_id, source
guild_joinJoined guild/clanguild_id, guild_name
pvp_matchPvP match completedopponent_id, result, mode
shareContent sharedplatform, content_type

Event Properties

Properties add context to events. Use them to answer "who, what, where, when, why" questions about each action.

Property Types

TypeExampleUse Case
String"difficulty": "hard"Categories, IDs, names
Number"score": 12500Metrics, counts, amounts
Boolean"is_first_win": trueFlags, conditions
Array"items": ["sword", "shield"]Lists of related values

Best Practices

  • Use consistent naming: snake_case for all property names
  • Be specific: gold_coins not currency
  • Include context: Track level with level events
  • Avoid PII: Don't include email, real names, or addresses in properties
  • Keep values clean: Avoid special characters in string values
Good vs Bad Properties
csharp
class=class="code-string">"code-comment">// ✅ Good: Specific, typed, contextual
IlaraClient.Instance.TrackEvent(class="code-string">"purchase_complete", new {
    product_id = class="code-string">"gem_pack_500",
    amount = 9.99,
    currency = class="code-string">"USD",
    payment_method = class="code-string">"apple_pay",
    is_first_purchase = false,
    session_number = 12
});
 
class=class="code-string">"code-comment">// ❌ Bad: Vague, inconsistent, contains PII
IlaraClient.Instance.TrackEvent(class="code-string">"purchase", new {
    item = class="code-string">"gems",           class=class="code-string">"code-comment">// Too vague
    Price = class="code-string">"$9.99",         class=class="code-string">"code-comment">// String instead of number, wrong case
    userEmail = class="code-string">"...",       class=class="code-string">"code-comment">// PII - never include!
    data = class="code-string">"misc stuff"      class=class="code-string">"code-comment">// What does this even mean?
});

Event Batching

The SDK automatically batches events to optimize network usage and battery life. Events are sent when:

  • The batch reaches a size threshold (default: 10 events)
  • A time interval passes (default: 30 seconds)
  • The app goes to background or closes
  • You manually call FlushEvents()
Configure Batching
csharp
class=class="code-string">"code-comment">// Adjust batch settings in your config
var config = new IlaraConfig {
    EventBatchSize = 20,        class=class="code-string">"code-comment">// Events per batch
    EventFlushInterval = 60,    class=class="code-string">"code-comment">// Seconds between auto-flush
};
 
class=class="code-string">"code-comment">// Or force immediate send for critical events
IlaraClient.Instance.TrackEvent(class="code-string">"purchase_complete", data);
IlaraClient.Instance.FlushEvents(); class=class="code-string">"code-comment">// Send immediately

Automatic Event Tracking

Ilara can automatically track common events without additional code:

Auto EventTriggerConfiguration
session_startApp opensautoTrackSessions: true
session_endApp closes/backgroundsautoTrackSessions: true
app_updateVersion changesAlways enabled
first_openFirst launch everAlways enabled
Auto-tracked events appear with an _auto suffix in the dashboard. You can disable auto-tracking if you prefer manual control.

Event Schema

Ilara automatically detects and validates event schemas. Once an event is tracked, its schema is inferred and subsequent events are validated against it.

Schema Consistency
Keep event properties consistent across tracks. Changing a property from number to string will trigger a schema warning in the dashboard.

View and manage schemas in Dashboard > Events > Schema.

Next Steps

Previous
Creating Your First Project
Next
SDK Installation