Docs/Core Concepts/Events & Properties

Events & Properties

Track custom events with rich properties to understand player behavior, measure engagement, and power your LiveOps automation.

10 min read

Anatomy of an Event

Every event in Ilara consists of required fields and optional properties that provide context.

Field	Type	Required	Description
`event_name`	string	Yes	Unique identifier for this event type
`player_id`	UUID	Yes	Ilara player UUID
`timestamp`	ISO 8601	Auto	When the event occurred
`properties`	object	No	Custom key-value pairs
`session_id`	string	No	Link events to a session

Complete Event Example

json

{
  class="code-string">"event_name": class="code-string">"item_purchase",
  class="code-string">"player_id": class="code-string">"550e8400-e29b-41d4-a716-446655440000",
  class="code-string">"timestamp": class="code-string">"2025-01-25T14:30:00.000Z",
  class="code-string">"session_id": class="code-string">"session_abc123",
  class="code-string">"properties": {
    class="code-string">"item_id": class="code-string">"sword_legendary_001",
    class="code-string">"item_name": class="code-string">"Dragon Slayer",
    class="code-string">"item_rarity": class="code-string">"legendary",
    class="code-string">"price": 5000,
    class="code-string">"currency": class="code-string">"gold",
    class="code-string">"player_level": 45,
    class="code-string">"shop_location": class="code-string">"main_city"
  }
}

Property Types

Ilara supports multiple property types with automatic type inference.

Scalar Types

Type	Example	Notes
String	`"region": "north_america"`	Max 1000 characters
Number (Integer)	`"level": 42`	64-bit signed integer
Number (Float)	`"completion_rate": 0.847`	64-bit double precision
Boolean	`"is_premium": true`	true or false
Null	`"referrer": null`	Explicitly absent value

Complex Types

Type	Example	Notes
Array	`"tags": ["pvp", "ranked"]`	Max 100 elements
Object	`"location": {"x": 10, "y": 20}`	Max 3 levels deep

Mixed Property Types

csharp

IlaraClient.Instance.TrackEvent(class="code-string">"match_complete", new {
    class=class="code-string">"code-comment">// Strings
    mode = class="code-string">"ranked",
    map_name = class="code-string">"Ancient Ruins",
 
    class=class="code-string">"code-comment">// Numbers
    score = 2450,
    match_duration = 847.5,
    kills = 12,
    deaths = 3,
 
    class=class="code-string">"code-comment">// Boolean
    is_victory = true,
    used_power_ups = false,
 
    class=class="code-string">"code-comment">// Arrays
    loadout = new[] { class="code-string">"rifle", class="code-string">"pistol", class="code-string">"grenade" },
    teammates = new[] { class="code-string">"player_456", class="code-string">"player_789" },
 
    class=class="code-string">"code-comment">// Nested object
    performance = new {
        accuracy = 0.68,
        headshot_rate = 0.24,
        damage_dealt = 4200
    }
});

Naming Conventions

Event Names

Use snake_case: level_complete not levelComplete
Be verb-first: purchase_complete, tutorial_skip
Be specific: chest_open_gold not open
Use past tense for completed actions: item_purchased
Use present for ongoing: session_active

Property Names

Use snake_case: player_level
Be descriptive: gold_coins_spent not amount
Include units when ambiguous: duration_seconds, distance_meters
Prefix booleans: is_, has_, can_

Reserved Property Names

Avoid these reserved names: id, _id, timestamp, player_id, event_name, tenant_id

Schema Management

Ilara automatically infers and validates event schemas based on the first occurrence of each event type.

Schema Inference

When you track an event for the first time, Ilara creates a schema:

Inferred Schema Example

json

{
  class="code-string">"event_name": class="code-string">"level_complete",
  class="code-string">"properties": {
    class="code-string">"level": { class="code-string">"type": class="code-string">"integer", class="code-string">"required": true },
    class="code-string">"score": { class="code-string">"type": class="code-string">"integer", class="code-string">"required": true },
    class="code-string">"time_seconds": { class="code-string">"type": class="code-string">"number", class="code-string">"required": false },
    class="code-string">"stars_earned": { class="code-string">"type": class="code-string">"integer", class="code-string">"required": false }
  }
}

Schema Validation

Subsequent events are validated against the schema:

Validation	Behavior
Type mismatch	Warning logged, event still tracked
New property	Schema auto-extended
Missing required property	Warning logged, event still tracked
Invalid property name	Property ignored, event tracked

Schema Versioning

View schema history in Dashboard > Events > Schema. You can lock schemas to prevent auto-extension in production.

Event Volume & Sampling

High-frequency events can be sampled to reduce costs while maintaining statistical accuracy.

When to Sample

Frame-by-frame position updates (sample at 1Hz instead of 60Hz)
UI interaction events (clicks, scrolls)
Debug/diagnostic events

Never Sample

Purchases and revenue events
Level/milestone completions
Error and crash events
First-time events (first_open, first_purchase)

Sampling Implementation

csharp

class=class="code-string">"code-comment">// Sample position updates at 10% rate
private float sampleRate = 0.1f;
 
void TrackPosition()
{
    if (Random.value < sampleRate)
    {
        IlaraClient.Instance.TrackEvent(class="code-string">"player_position", new {
            x = transform.position.x,
            y = transform.position.y,
            z = transform.position.z,
            sample_rate = sampleRate  class=class="code-string">"code-comment">// Include for analysis
        });
    }
}

Super Properties

Super properties are automatically attached to every event, reducing redundancy.

Setting Super Properties

csharp

class=class="code-string">"code-comment">// Set once, included in all future events
IlaraClient.Instance.SetSuperProperties(new {
    app_version = class="code-string">"1.2.3",
    platform = class="code-string">"iOS",
    device_model = SystemInfo.deviceModel,
    player_level = 45,  class=class="code-string">"code-comment">// Update when level changes
    is_premium = true
});
 
class=class="code-string">"code-comment">// These properties are now auto-included
IlaraClient.Instance.TrackEvent(class="code-string">"level_start", new {
    level = 10
});
class=class="code-string">"code-comment">// Actual event sent includes: level, app_version, platform, device_model, player_level, is_premium

Super properties can be overridden per-event by including the same property name in the event's properties.

Next Steps

Player Identification — Link events to player profiles
Segments — Group players by behavior
Events API — Full API reference

SDK Installation

Player Identification