Unity

Installation

Phase Analytics ships as a Unity Package Manager (UPM) package from the Phase monorepo. There is no .unitypackage download.

{
  "dependencies": {
    "com.phase.analytics": "https://github.com/Phase-Analytics/Phase.git?path=packages/phase-unity#v0.1.9"
  }
}

https://github.com/Phase-Analytics/Phase.git?path=packages/phase-unity#v0.1.9

#v0.1.9

Setup

Initialize once at startup, then call IdentifyAsync before tracking. Call InitializeAsync and IdentifyAsync from the Unity main thread (Start, Awake, or a coroutine started there). With AutoBootstrap enabled (default), the SDK spawns a DontDestroyOnLoad PhaseLifecycleHook that flushes on pause/quit and resumes sessions when the app returns.

Bootstrap scriptPackage sampleEditor / dev

Attach a bootstrap MonoBehaviour to a GameObject in your first scene (or a persistent loader scene):

using Phase.Analytics;
using Phase.Analytics.Config;
using Phase.Analytics.Models;
using UnityEngine;

public sealed class GameBootstrap : MonoBehaviour
{
    [SerializeField] private string apiKey = "phase_xxx";

    private async void Start()
    {
        var ok = await PhaseAnalytics.InitializeAsync(new PhaseConfig
        {
            ApiKey = apiKey,
            LogLevel = LogLevel.Info,
        });

        if (!ok)
        {
            Debug.LogWarning("[Phase] Initialize failed. Check API key and network.");
            return;
        }

        await PhaseAnalytics.IdentifyAsync();
        PhaseAnalytics.Track("app_opened");
    }
}

InitializeAsync is idempotent. IdentifyAsync must succeed before events are sent. Both must run on the main thread so Unity APIs and the lifecycle hook stay safe after await.

Import the bundled sample from Package Manager:

1. Window → Package Manager
2. Select Phase Analytics in the left list
3. Open Samples
4. Import Phase Analytics Sample
5. Add PhaseAnalyticsBootstrap to a scene and set your API key in the Inspector

The sample lives under Samples~/PhaseAnalyticsSample in the package (not copied into your Assets/ until imported).

For day-to-day Editor work without hitting production:

await PhaseAnalytics.InitializeAsync(new PhaseConfig
{
    ApiKey = "phase_xxx",
    DisableInEditor = true,
    DebugData = true,
    LogLevel = LogLevel.Info,
});

DisableInEditor skips network I/O in the Unity Editor (calls still queue logic where applicable).

DebugData sends x-phase-debug-data: 1 so events are marked as debug in the dashboard.

Always validate on a physical device with an IL2CPP Release build before shipping.

Configuration

PhaseConfig is passed to PhaseAnalytics.InitializeAsync():

Platform: on iOS/Android player builds, identify sends platform: "ios" or "android". In the Editor it is null.

Threading and HTTP

Call InitializeAsync and IdentifyAsync from the Unity main thread (Start, Awake, or a coroutine started there). The SDK uses ConfigureAwait(false) internally so continuations often run on the thread pool.

Unity-only APIs (GameObject, Application, UnityWebRequest) are gated to the main thread: lifecycle hook creation, device info snapshot, network reachability polling, and optional UnityWebRequest transport.

Default HTTP is System.Net.Http (SystemNetHttpTransport), which is safe from pool threads. Set UseUnityWebRequestTransport = true only if you need UnityWebRequest; those calls are queued to PhaseLifecycleHook.Update.

Usage

Identify User

Required: Call IdentifyAsync() before Track(). This registers the device and starts a session.

// No PII by default
await PhaseAnalytics.IdentifyAsync();

// Optional properties after login
await PhaseAnalytics.IdentifyAsync(new DeviceProperties
{
    ["user_id"] = "123",
    ["plan"] = "premium",
    ["beta_tester"] = true,
});

Privacy by default:

• No personal data is collected without explicit properties
• Device ID is generated locally (ULID) and stored under Application.persistentDataPath
• Only technical metadata is collected when enabled (OS, model, app version, locale)

Adding custom properties:

You can attach user/device properties. Important: If you add PII (personally identifiable information), ensure you have proper user consent:

// After user login and consent
await PhaseAnalytics.IdentifyAsync(new DeviceProperties
{
    ["user_id"] = accountId,
    ["plan"] = "premium",
});

// If adding PII, get consent first
if (userHasConsentedToAnalytics)
{
    await PhaseAnalytics.IdentifyAsync(new DeviceProperties
    {
        ["email"] = user.Email,
        ["display_name"] = user.DisplayName,
    });
}

Properties must be flat primitives: string, number, bool, or null.

Track Events

Track custom events with optional parameters. Note: IdentifyAsync() must complete successfully first.

// Event without parameters
PhaseAnalytics.Track("app_opened");

// Event with parameters
PhaseAnalytics.Track("purchase_completed", new EventParams
{
    ["amount"] = 99.99,
    ["currency"] = "USD",
    ["product_id"] = "premium_plan",
});

// Level / gameplay
PhaseAnalytics.Track("level_complete", new EventParams
{
    ["level"] = 5,
    ["score"] = 1200,
    ["duration_sec"] = 42.5,
});

Track is non-blocking (fire-and-forget). Failures are logged when LogLevel is enabled and events are queued for retry when appropriate.

Event naming rules:

• Alphanumeric characters, underscores (_), hyphens (-), periods (.), forward slashes (/), and spaces
• 1–256 characters
• Examples: purchase, user.signup, payment/success, Button Clicked

Event parameters:

• Flat primitive object only
• Values must be string, number, bool, or null
• Max 32 keys
• Key max 32 characters
• String value max 256 characters
• Serialized payload max 8 KB
• Empty objects are normalized away

Scenes and levels (manual events)

Model scenes and levels with Track:

using Phase.Analytics;
using Phase.Analytics.Models;
using UnityEngine;
using UnityEngine.SceneManagement;

public sealed class SceneAnalytics : MonoBehaviour
{
    private void OnEnable() => SceneManager.sceneLoaded += OnSceneLoaded;
    private void OnDisable() => SceneManager.sceneLoaded -= OnSceneLoaded;

    private void OnSceneLoaded(Scene scene, LoadSceneMode mode)
    {
        PhaseAnalytics.Track("scene_loaded", new EventParams
        {
            ["scene"] = scene.name,
            ["mode"] = mode.ToString(),
        });
    }
}

Clear local data

Wipes persisted SDK storage on device (GDPR-style). Does not delete server-side data.

await PhaseAnalytics.ClearLocalDataAsync();

// Re-initialize before tracking again
await PhaseAnalytics.InitializeAsync(new PhaseConfig { ApiKey = "phase_xxx" });
await PhaseAnalytics.IdentifyAsync();

API reference

Type Reference

DeviceProperties

Custom user/device attributes passed to IdentifyAsync():

EventParams

Event parameters passed to Track():

How It Works

Lifecycle and sessions

When AutoBootstrap is true, PhaseLifecycleHook is created at the start of InitializeAsync (before async I/O):

• Listens for OnApplicationPause / focus changes
• Flushes the offline queue when the app backgrounds or quits
• Resumes session handling when the app returns
• Polls network reachability on the main thread (Update)

Session pings run on a timer while identified. Events sent without a valid session are rejected client-side until IdentifyAsync succeeds.

Offline Support

Events are stored under:

Application.persistentDataPath/phase-analytics-data/

When offline or when requests fail, items stay in the queue. The SDK flushes after IdentifyAsync when the network is available and on lifecycle boundaries. Large backlogs use gzip batch upload (100+ queued items).

Privacy

• No personal data is collected by default
• Device IDs are generated locally and stored persistently
• Geolocation is resolved server-side from IP when UserLocale is enabled
• No IDFA or advertising identifiers in v1
• All metadata collection is optional via DeviceInfo / UserLocale

Performance

• Track does not block the game thread
• Rate limit: 15 events per second
• 50 ms deduplication window for identical event name + parameters
• Offline queue capped at 1000 items; batches up to 1000 items per request
• Failed requests retry with exponential backoff (HTTP layer)

Production builds (IL2CPP)

Editor Play Mode is not enough to validate analytics. Ship only after a device smoke test.

Troubleshooting

Package import (git UPM)

Runtime

IL2CPP / release

Differences from other SDKs

For the same event schema and dashboard, keep event names and parameter keys aligned across your mobile clients.