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:

Event	When to Track	Key Properties
`session_start`	Player opens the game	platform, version, device
`session_end`	Player closes the game	duration_seconds, reason
`tutorial_start`	Tutorial begins	skip_available
`tutorial_complete`	Tutorial finished	duration_seconds, steps_completed
`first_purchase`	First IAP	product_id, amount, currency

Gameplay Events

Track core gameplay actions:

Event	When to Track	Key Properties
`level_start`	Level begins	level, difficulty, mode
`level_complete`	Level finished	level, score, time, stars
`level_fail`	Level failed	level, reason, retry_count
`achievement_unlock`	Achievement earned	achievement_id, name
`item_collect`	Item picked up	item_id, item_type, value

Economy Events

Track virtual and real currency flows:

Event	When to Track	Key Properties
`currency_earn`	Player gains currency	currency_type, amount, source
`currency_spend`	Player spends currency	currency_type, amount, item_id
`purchase_start`	IAP flow begins	product_id, price
`purchase_complete`	IAP successful	product_id, amount, currency
`purchase_fail`	IAP failed	product_id, error_code

Social Events

Track social interactions:

Event	When to Track	Key Properties
`friend_add`	Friend added	friend_id, source
`guild_join`	Joined guild/clan	guild_id, guild_name
`pvp_match`	PvP match completed	opponent_id, result, mode
`share`	Content shared	platform, content_type

Event Properties

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

Property Types

Type	Example	Use Case
String	`"difficulty": "hard"`	Categories, IDs, names
Number	`"score": 12500`	Metrics, counts, amounts
Boolean	`"is_first_win": true`	Flags, 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 Event	Trigger	Configuration
`session_start`	App opens	`autoTrackSessions: true`
`session_end`	App closes/backgrounds	`autoTrackSessions: true`
`app_update`	Version changes	Always enabled
`first_open`	First launch ever	Always 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

SDK Installation — Install the SDK for your platform
Player Identification — Link events to player profiles
Events API Reference — Full API documentation

Creating Your First Project

SDK Installation