Docs/Core Concepts/Player Identification

Player Identification

Learn how to identify and track players across devices and sessions with Ilara player profiles.

7 min read

Overview

Player identification is the foundation of personalized LiveOps. When you identify a player, Ilara creates or updates their profile, enabling segment membership, personalized flags, and churn prediction.

Identify Before Tracking
Always call IdentifyPlayer() before tracking events. Events from unidentified players are stored but cannot be used for segments or personalization.

Identifying Players

Use your game's unique player ID to identify players. Ilara will create a new profile or update an existing one.

Basic Identification
csharp
class=class="code-string">"code-comment">// Identify with just an external ID
var player = await IlaraClient.Instance.IdentifyPlayer(class="code-string">"your_player_id_123");
 
Debug.Log($class="code-string">"Ilara Player ID: {player.Id}");
Debug.Log($class="code-string">"Lifecycle Stage: {player.LifecycleStage}");
Debug.Log($class="code-string">"Session Count: {player.SessionCount}");

With Attributes

Include player attributes for richer profiles and better segmentation:

Identification with Attributes
csharp
var player = await IlaraClient.Instance.IdentifyPlayer(
    externalId: class="code-string">"player_123",
    attributes: new Dictionary<string, object> {
        { class="code-string">"level", 45 },
        { class="code-string">"country", class="code-string">"US" },
        { class="code-string">"language", class="code-string">"en" },
        { class="code-string">"install_source", class="code-string">"google_play" },
        { class="code-string">"is_vip", true },
        { class="code-string">"total_purchases", 3 }
    },
    deviceId: SystemInfo.deviceUniqueIdentifier,
    email: class="code-string">"[email protected]"  class=class="code-string">"code-comment">// Optional, for email campaigns
);

Player Profile Structure

FieldTypeDescription
idUUIDIlara unique identifier
external_idstringYour game's player ID
device_idstringDevice identifier
emailstringPlayer email (optional)
lifecycle_stageenumCurrent lifecycle stage
session_countintegerTotal sessions recorded
first_seen_atdatetimeFirst identification time
last_seen_atdatetimeMost recent activity
total_revenuedecimalLifetime revenue
is_payerbooleanHas made any purchase
attributesobjectCustom attributes

Lifecycle Stages

Ilara automatically tracks players through 6 lifecycle stages based on their engagement patterns:

StageColorDescriptionTypical Criteria
newAccentJust joinedFirst session, < 7 days old
activeAccentRegular engagementSession in last 7 days
engagedAccentHigh activity3+ sessions/week, purchases
at_riskAccentDeclining engagementActivity dropped 50%+
churnedAccentNo recent activityNo session in 14+ days
returnedAccentRe-engaged after churnActive after churned state
Customize lifecycle stage criteria in Dashboard > Settings > Lifecycle

Updating Attributes

Player attributes can be updated at any time. Only changed attributes are sent.

Update Player Attributes
csharp
class=class="code-string">"code-comment">// Update specific attributes
await IlaraClient.Instance.UpdatePlayerAttributes(new {
    level = 46,                    class=class="code-string">"code-comment">// Level up!
    vip_tier = class="code-string">"gold",             class=class="code-string">"code-comment">// VIP upgrade
    last_level_completed = class="code-string">"5-3"   class=class="code-string">"code-comment">// Progress tracking
});
 
class=class="code-string">"code-comment">// Attributes are merged, not replaced
class=class="code-string">"code-comment">// Previous attributes like class="code-string">"country" remain intact

Increment Attributes

Increment Numeric Attributes
csharp
class=class="code-string">"code-comment">// Increment without needing current value
await IlaraClient.Instance.IncrementAttribute(class="code-string">"games_played", 1);
await IlaraClient.Instance.IncrementAttribute(class="code-string">"total_score", 2500);

Multi-Device Identity

Ilara supports players across multiple devices through identity linking.

Device-First Flow

For games where players start anonymously on a device:

Device-First Identification
csharp
class=class="code-string">"code-comment">// On first launch(anonymous)
var player = await IlaraClient.Instance.IdentifyPlayer(
    externalId: null,  class=class="code-string">"code-comment">// No account yet
    deviceId: SystemInfo.deviceUniqueIdentifier
);
class=class="code-string">"code-comment">// player.ExternalId is null, but device events are tracked
 
class=class="code-string">"code-comment">// Later, when player creates account
await IlaraClient.Instance.LinkIdentity(
    externalId: class="code-string">"new_account_123",
    deviceId: SystemInfo.deviceUniqueIdentifier
);
class=class="code-string">"code-comment">// Historical device events are now linked to account

Account-First Flow

For games where players log in first:

Account-First Identification
csharp
class=class="code-string">"code-comment">// Player logs in on new device
var player = await IlaraClient.Instance.IdentifyPlayer(
    externalId: class="code-string">"existing_account_123",
    deviceId: class="code-string">"new_device_456"
);
class=class="code-string">"code-comment">// Player profile merges data from all devices

Anonymous Tracking

For privacy-conscious games or pre-login tracking:

Anonymous Mode
csharp
class=class="code-string">"code-comment">// Track without identification
IlaraClient.Instance.TrackAnonymousEvent(class="code-string">"app_open", new {
    platform = class="code-string">"iOS",
    app_version = class="code-string">"1.2.3"
});
 
class=class="code-string">"code-comment">// Anonymous events use device_id only
class=class="code-string">"code-comment">// Convert to identified when player logs in
await IlaraClient.Instance.IdentifyPlayer(class="code-string">"player_123");
class=class="code-string">"code-comment">// Previous anonymous events are linked
Anonymous Limitations
Anonymous players cannot: receive personalized feature flags, be included in segments, or trigger personalized notifications.

Privacy & GDPR

Ilara provides tools for privacy compliance:

Privacy Operations
csharp
class=class="code-string">"code-comment">// Export player data(GDPR Article 15)
var exportData = await IlaraClient.Instance.ExportPlayerData(class="code-string">"player_123");
 
class=class="code-string">"code-comment">// Delete player data(GDPR Article 17 - Right to Erasure)
await IlaraClient.Instance.DeletePlayer(class="code-string">"player_123");
 
class=class="code-string">"code-comment">// Anonymize player(retain analytics, remove PII)
await IlaraClient.Instance.AnonymizePlayer(class="code-string">"player_123");

Next Steps

Previous
Events & Properties
Next
Segments