Event Tracking | GameTribe Dev

Overview

The GameTribe SDK provides comprehensive event tracking with 30+ event types across 7 categories. Events are automatically batched and sent to the backend for analytics, leaderboards, and anti-cheat validation.

Event Categories

Category	Events	Description
Session	3	Session lifecycle events
Gameplay	5	Level and gameplay actions
Score	2	Score submission and leaderboards
Achievement	2	Achievements and progress
Analytics	5	Feature usage and errors
Ad	5	Ad impressions and interactions
Economy	3	Currency and purchases

Event Batching

Events are automatically batched to reduce network calls. By default:

Events are sent when 10 events are queued, OR
Every 30 seconds, whichever comes first

Critical events like score submissions, achievements, and purchases are sent immediately, bypassing the batch queue.

Session Events

csharp

// Track session started (automatic - called by SDK)
PlatformSDK.Instance.Events.TrackSessionStarted();

// Track session heartbeat (automatic - every 30s)
PlatformSDK.Instance.Events.TrackSessionHeartbeat(activeTimeSeconds);

// Track session ended (automatic - on EndSessionAsync)
PlatformSDK.Instance.Events.TrackSessionEnded(durationSeconds);

Session events are tracked automatically by the SDK. You don't need to call these manually.

Gameplay Events

Level Tracking

LevelManager.cs

public class LevelManager : MonoBehaviour
{
    public void StartLevel(string levelId)
    {
        PlatformSDK.Instance.Events.TrackLevelStarted(levelId, new Dictionary<string, object>
        {
            { "difficulty", "hard" },
            { "attemptNumber", 3 }
        });
    }

    public void CompleteLevel(string levelId, int score, int duration)
    {
        PlatformSDK.Instance.Events.TrackLevelCompleted(
            levelId: levelId,
            score: score,
            duration: duration,
            metadata: new Dictionary<string, object>
            {
                { "stars", 3 },
                { "perfectCompletion", true },
                { "enemiesDefeated", 25 }
            }
        );
    }

    public void FailLevel(string levelId, int duration)
    {
        PlatformSDK.Instance.Events.TrackLevelFailed(
            levelId: levelId,
            duration: duration,
            metadata: new Dictionary<string, object>
            {
                { "failureReason", "out_of_time" },
                { "progress", 75 }
            }
        );
    }
}

Checkpoints

csharp

// Track checkpoint reached
PlatformSDK.Instance.Events.TrackCheckpointReached(
    checkpointId: "checkpoint-3",
    levelId: "level-5",
    metadata: new Dictionary<string, object>
    {
        { "timeElapsed", 120 },
        { "healthRemaining", 75 }
    }
);

Gameplay Actions

csharp

// Track specific gameplay actions (useful for anti-cheat)
PlatformSDK.Instance.Events.TrackGameplayAction(
    actionType: "enemy_killed",
    metadata: new Dictionary<string, object>
    {
        { "enemyType", "boss" },
        { "weapon", "sword" },
        { "damage", 150 }
    }
);

Score Events

Score events are critical and sent immediately:

csharp

// Submit score to leaderboard (CRITICAL - immediate send)
PlatformSDK.Instance.Events.SubmitScore(125000, new Dictionary<string, object>
{
    { "levelId", "level-10" },
    { "difficulty", "hard" },
    { "duration", 900 },
    { "perfectCompletion", true }
});

// Track leaderboard viewed
PlatformSDK.Instance.Events.TrackLeaderboardViewed(
    leaderboardType: "global", // or "friends", "daily", "weekly"
    metadata: new Dictionary<string, object>
    {
        { "playerRank", 42 }
    }
);

For leaderboard integration, always use SubmitScore() orEndSessionAsync(). The backend handles the rest.

Achievement Events

Achievement events are critical and sent immediately:

csharp

// Unlock an achievement (CRITICAL - immediate send)
PlatformSDK.Instance.Events.TrackAchievementUnlocked(
    achievementId: "speedrunner",
    metadata: new Dictionary<string, object>
    {
        { "achievementName", "Speedrunner" },
        { "pointsAwarded", 100 },
        { "timeToUnlock", 3600 }
    }
);

// Track achievement progress
PlatformSDK.Instance.Events.TrackAchievementProgress(
    achievementId: "collector",
    currentProgress: 75,
    targetProgress: 100,
    metadata: new Dictionary<string, object>
    {
        { "itemsCollected", 75 },
        { "itemsRequired", 100 }
    }
);

Analytics Events

csharp

// Track feature usage
PlatformSDK.Instance.Events.TrackFeatureUsed(
    featureName: "power_up_shop",
    metadata: new Dictionary<string, object>
    {
        { "timeSpent", 30 },
        { "itemsViewed", 5 },
        { "purchaseMade", true }
    }
);

csharp

// Track screen navigation
PlatformSDK.Instance.Events.TrackNavigation(
    fromScreen: "main_menu",
    toScreen: "level_select",
    metadata: new Dictionary<string, object>
    {
        { "navigationMethod", "button_click" }
    }
);

csharp

// Track errors for debugging
PlatformSDK.Instance.Events.TrackError(
    errorType: "network_error",
    errorMessage: "Failed to load leaderboard",
    metadata: new Dictionary<string, object>
    {
        { "severity", "warning" },
        { "retryCount", 3 },
        { "stackTrace", System.Environment.StackTrace }
    }
);

csharp

// Track performance metrics
PlatformSDK.Instance.Events.TrackPerformance(new Dictionary<string, object>
{
    { "fps", 60 },
    { "avgFps", 58 },
    { "minFps", 45 },
    { "memoryUsage", System.GC.GetTotalMemory(false) },
    { "frameDrops", 5 }
});

csharp

// Track detailed time breakdown
PlatformSDK.Instance.Events.TrackTimeSpent(
    totalTime: 1800, // 30 minutes total
    breakdown: new Dictionary<string, object>
    {
        { "gameplay", 1200 },
        { "menus", 300 },
        { "loading", 60 },
        { "paused", 240 }
    }
);

Ad Events

csharp

// Track ad impression
PlatformSDK.Instance.Events.TrackAdImpression(
    adId: "ad-123",
    adType: "rewarded", // "interstitial", "rewarded", "banner"
    metadata: new Dictionary<string, object>
    {
        { "placement", "level_complete" }
    }
);

// Track ad click
PlatformSDK.Instance.Events.TrackAdClick(adId: "ad-123", adType: "rewarded");

// Track ad completed (CRITICAL for rewarded ads)
PlatformSDK.Instance.Events.TrackAdCompleted(adId: "ad-123", adType: "rewarded");

// Track ad skipped
PlatformSDK.Instance.Events.TrackAdSkipped(adId: "ad-123", adType: "interstitial");

// Track ad error
PlatformSDK.Instance.Events.TrackAdError(
    adId: "ad-123",
    adType: "rewarded",
    errorType: "load_failed"
);

Economy Events

csharp

// Track currency earned
PlatformSDK.Instance.Events.TrackCurrencyEarned(
    currencyType: "coins",
    amount: 500,
    source: "level_complete",
    metadata: new Dictionary<string, object>
    {
        { "levelId", "level-5" },
        { "bonusMultiplier", 2 }
    }
);

// Track currency spent
PlatformSDK.Instance.Events.TrackCurrencySpent(
    currencyType: "coins",
    amount: 1000,
    itemPurchased: "speed_boost",
    metadata: new Dictionary<string, object>
    {
        { "shopCategory", "power_ups" }
    }
);

// Track item purchased (CRITICAL - immediate send)
PlatformSDK.Instance.Events.TrackItemPurchased(
    itemId: "premium_skin_001",
    itemType: "cosmetic",
    price: new Dictionary<string, object>
    {
        { "currency", "gems" },
        { "amount", 500 }
    }
);

Flushing Events

Force send all queued events immediately:

csharp

// Flush all queued events
await PlatformSDK.Instance.Events.FlushAsync();

// Check queue size
int queuedCount = PlatformSDK.Instance.Events.GetQueuedEventCount();
Debug.Log($"Events in queue: {queuedCount}");

Always call FlushAsync() in OnApplicationQuit()to ensure all events are sent before the game closes.

csharp

void OnApplicationQuit()
{
    // Ensure all events are sent before quitting
    PlatformSDK.Instance.Events.FlushAsync();
}

Legacy API

The original event methods still work for backward compatibility:

csharp

// Legacy methods (still supported)
PlatformSDK.Instance.Events.SendGameStart();
PlatformSDK.Instance.Events.SendGameEnd(score, duration);
PlatformSDK.Instance.Events.SendGamePause();
PlatformSDK.Instance.Events.SendGameResume();
PlatformSDK.Instance.Events.SendLevelComplete(levelId, score, time);
PlatformSDK.Instance.Events.SendLevelFail(levelId, reason);
PlatformSDK.Instance.Events.SendAchievement(achievementId);
PlatformSDK.Instance.Events.SendMilestone(milestoneType, value);
PlatformSDK.Instance.Events.SendCustomEvent(eventName, properties);

We recommend migrating to the new typed event methods for better analytics and type safety.