Unity Integration

🔗 GitHub Repository

Unity SDK for LoopKit analytics platform. Track events, identify users, and manage sessions with comprehensive analytics support.

Installation

Method 1: Unity Package Manager (Git URL)

This is the recommended installation method for Unity projects.

1. Open your Unity project
2. Go to Window → Package Manager
3. Click the + button in the top-left corner
4. Select Add package from git URL...
5. Enter the following URL:

   git@github.com:loopkitai/unity-sdk.git

Method 2: Manual Package Manager

1. Open your Unity project
2. Navigate to your project's Packages folder
3. Open the manifest.json file in a text editor
4. Add the following line to the dependencies section:

   "com.loopkit.sdk": "git@github.com:loopkitai/unity-sdk.git"

5. Save the file and return to Unity
6. Unity will automatically download and install the package

Method 3: Clone and Import

1. Clone the repository:

   git clone git@github.com:loopkitai/unity-sdk.git

2. In Unity, go to Window → Package Manager

3. Click the + button and select Add package from disk...

4. Navigate to the cloned repository and select the package.json file in the root of the repository.

Requirements

• Unity Version: 2020.3 or later
• Platform Support: All Unity-supported platforms

Quick Start

The easiest way to get started with LoopKit is using the LoopKitManager component:

Simple Setup (Recommended)

1. Add the Package (follow installation steps above)
2. Create a GameObject: In your scene, create a new empty GameObject (right-click in Hierarchy → Create Empty)
3. Add LoopKitManager Component: With the GameObject selected, click "Add Component" and search for "LoopKitManager"
4. Paste Your API Key: In the LoopKitManager component, paste your API key from your LoopKit dashboard
5. Done! LoopKit will automatically initialize and start tracking

What You Get Automatically

Just by adding the LoopKitManager component, you automatically get these metrics tracked:

Lifecycle Events

• loopkit_initialized - When the SDK starts up
• app_paused - When the app goes to background
• app_resumed - When the app returns to foreground

Application Focus Events

• application_focus_gained - When the app gains focus
• application_focus_lost - When the app loses focus
• application_start - When the application starts
• application_quit - When the application is quitting

Session Management

• session_start - When a new session begins
• session_end - When a session ends (timeout or manual)
• Automatic session tracking with 30-minute timeout
• Cross-scene session persistence

Scene Tracking (if enabled)

• scene_loaded - When a new scene loads
• scene_unloaded - When a scene is unloaded
• Scene metadata (name, build index, load mode)

Error Tracking (if enabled)

• error - Automatic Unity error and exception tracking
• Error details with stack traces and scene context

Performance Tracking (if enabled)

• fps_report - Automatic FPS performance reports with statistics
• Includes average, min, max, median FPS and low FPS percentage
• Configurable sampling and reporting intervals

Memory Tracking (if enabled)

• low_memory_warning - When device memory is running low
• memory_status - Initial memory status on startup
• Includes system memory, graphics memory, and available memory

Network Tracking (if enabled)

• network_connection_lost - When internet connection is lost
• network_connection_restored - When internet connection is restored
• network_status - Initial network status on startup
• Includes connection type (wifi, cellular, none) and reachability status

System Context (included with all events)

• Platform information (iOS, Android, etc.)
• Device details (model, memory, graphics)
• App version and Unity version
• Screen resolution and device type

Manual Usage

If you need more control, you can also use the SDK programmatically:

using LoopKit;

public class GameManager : MonoBehaviour
{
    void Start()
    {
        // Get the manager instance (if using LoopKitManager component)
        LoopKitManager.Instance.Track("game_started");

        // Or use the static API directly
        LoopKitAPI.Track("level_completed", new Dictionary<string, object>
        {
            ["level"] = 1,
            ["score"] = 1000,
            ["time"] = 45.2f
        });
    }
}

Configuration Options

The LoopKitManager component provides these configuration options:

Basic Settings

• API Key: Your LoopKit API key (required)
• Auto Initialize: Initialize automatically on Awake (default: true)
• Persist Across Scenes: Keep the GameObject alive when loading new scenes (default: true)

Advanced Settings

• Debug Mode: Enable debug logging (default: false)
• Batch Size: Number of events to batch before sending (default: 50)
• Flush Interval: How often to send events in seconds (default: 5)
• Session Tracking: Enable automatic session management (default: true)
• Scene Tracking: Track scene changes automatically (default: true)
• Error Tracking: Track Unity errors automatically (default: true)
• FPS Tracking: Track performance metrics automatically (default: true)
• Memory Tracking: Track memory warnings automatically (default: true)
• Network Tracking: Track connectivity changes automatically (default: true)

Privacy & Tracking Permissions

⚠️ Important for GDPR/CCPA Compliance: LoopKit provides built-in privacy controls to help you comply with data protection regulations.

Managing Tracking State

// Check current state
bool isEnabled = LoopKit.Instance.IsTrackingEnabled();

// Disable tracking (e.g., for privacy compliance)
LoopKit.Instance.DisableTracking();

// Re-enable tracking
LoopKit.Instance.EnableTracking();

// Or use static API
LoopKitAPI.DisableTracking();
bool enabled = LoopKitAPI.IsTrackingEnabled();

Privacy-First Setup

For GDPR/CCPA compliance, consider starting with tracking disabled by default:

using LoopKit;

public class ComplianceSetup : MonoBehaviour
{
    void Start()
    {
        // Initialize LoopKit but disable tracking until user consents
        LoopKit.Instance.DisableTracking();

        // Show privacy consent dialog
        ShowPrivacyConsentDialog();
    }

    void ShowPrivacyConsentDialog()
    {
        // Your privacy dialog implementation
        // If user accepts, call: LoopKit.Instance.EnableTracking();
        // If user declines, tracking remains disabled
    }
}

Key Privacy Features

• Disabled by Default: You can start with tracking disabled and only enable after user consent
• Complete Control: Enable/disable tracking at any time during gameplay
• Persistent Settings: Tracking preferences are remembered across app sessions
• No Data Loss: Events are queued when disabled and sent when re-enabled (if desired)
• Real-time Changes: Tracking state changes take effect immediately

Best Practices

1. Check tracking state before collecting sensitive data
2. Disable tracking by default in privacy-sensitive regions (EU, CA)
3. Provide clear opt-in/opt-out controls in your game settings
4. Respect user choices and don't re-enable without explicit consent
5. Test your privacy flows to ensure compliance with local regulations

Common Game Events

Here are some examples of common game events you might want to track:

Player Actions

using LoopKit;
using UnityEngine;

public class PlayerController : MonoBehaviour
{
    void OnLevelStart()
    {
        LoopKitManager.Instance.Track("level_started", new {
            level = currentLevel,
            player_id = playerId,
            difficulty = selectedDifficulty
        });
    }

    void OnLevelComplete()
    {
        LoopKitManager.Instance.Track("level_completed", new {
            level = currentLevel,
            time_seconds = completionTime,
            score = finalScore,
            deaths = deathCount
        });
    }
}

Game Economy

using LoopKit;
using UnityEngine;

public class ShopManager : MonoBehaviour
{
    public void OnPurchase(Item item, Currency currency)
    {
        LoopKitManager.Instance.Track("item_purchased", new {
            item_id = item.id,
            item_name = item.name,
            cost = item.cost,
            currency_type = currency.type,
            player_level = playerStats.level
        });
    }
}

User Identification

using LoopKit;
using UnityEngine;

public class AuthManager : MonoBehaviour
{
    public void OnPlayerLogin(string playerId, PlayerData playerData)
    {
        // Identify the user with their unique ID and traits
        LoopKitManager.Instance.Identify(playerId, new {
            username = playerData.username,
            email = playerData.email,
            level = playerData.level,
            subscription_tier = playerData.subscriptionTier,
            signup_date = playerData.signupDate,
            platform = Application.platform.ToString()
        });

        // Track the login event
        LoopKitManager.Instance.Track("player_login", new {
            login_method = "email",
            returning_player = playerData.loginCount > 1
        });
    }

    public void OnGuestLogin(string guestId)
    {
        // Identify guest users too
        LoopKitManager.Instance.Identify(guestId, new {
            user_type = "guest",
            platform = Application.platform.ToString()
        });

        LoopKitManager.Instance.Track("guest_login");
    }
}

Group Management

using LoopKit;
using UnityEngine;

public class GuildManager : MonoBehaviour
{
    public void OnPlayerJoinGuild(string playerId, GuildData guildData)
    {
        // Associate the player with their guild/team
        LoopKitManager.Instance.Group(guildData.id, new {
            guild_name = guildData.name,
            guild_level = guildData.level,
            member_count = guildData.memberCount,
            guild_type = guildData.type,
            created_date = guildData.createdDate
        });

        // Track the join event
        LoopKitManager.Instance.Track("guild_joined", new {
            guild_id = guildData.id,
            guild_name = guildData.name,
            player_role = "member"
        });
    }

    public void OnGuildActivity(string guildId, string activityType)
    {
        // Track guild-level events
        LoopKitManager.Instance.Track("guild_activity", new {
            activity_type = activityType,
            guild_id = guildId
        });
    }
}

Samples

The SDK includes sample scenes demonstrating various features:

• SuperBasicExample: Simple event tracking with LoopKitManager
• BasicUsageExample: Comprehensive examples of all SDK features
• ManagerExample: Advanced LoopKitManager usage patterns

To import samples:

1. Open Package Manager
2. Find LoopKit Unity SDK in the list
3. Expand the Samples section
4. Click Import next to the desired sample

Documentation

For detailed usage instructions and API reference, visit: LoopKit Unity Documentation

Support

• Email: support@loopkit.ai
• Documentation: https://docs.loopkit.ai
• Website: https://loopkit.ai

Need help? Join our Discord or contact support