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.2.0"
  }
}

#v0.2.0

Setup

Initialize once at startup, then call IdentifyAsync to register the device and start a session. 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 when the app goes to the background, saves the queue on 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):

Copy Text

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. Events tracked before IdentifyAsync completes are buffered and delivered once a session exists. Both must run on the main thread so Unity APIs and the lifecycle hook stay safe after await.

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

Call IdentifyAsync() once at startup. This registers the device and starts a session.

Copy Text

// 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. The event id and timestamp are taken when you call Track. Events tracked before IdentifyAsync() completes are buffered (up to 200 events, for up to one hour) and delivered once a session exists. If more than 200 pile up, the oldest are dropped.

// 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). Events go into a persistent queue and are sent in batches (see Delivery). Failures are logged when LogLevel is enabled and events are retried 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

Track Screens

Use TrackScreen to record a screen view. parameters follow the same rules as Track, and delivery rules are the same (buffered before identify, sent in batches).

PhaseAnalytics.TrackScreen("Shop");

PhaseAnalytics.TrackScreen("Shop", new EventParams
{
    ["tab"] = "coins",
});

Unity has no automatic screen tracking, so call TrackScreen from your own menu or scene code.

Scenes and levels (manual events)

Model scenes and levels with Track (or TrackScreen for screen-like views):

Copy Text

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(),
        });
    }
}

Flush

Data is sent automatically (see Delivery). FlushAsync() sends queued data now and saves whatever could not be delivered, for example before a scripted shutdown.

await PhaseAnalytics.FlushAsync();

Reset

ResetAsync() forgets the current device, for example on logout. It ends the session, tries to deliver queued data, clears the queue and generates a new device ID. Call IdentifyAsync() again to resume tracking.

await PhaseAnalytics.ResetAsync();
await PhaseAnalytics.IdentifyAsync();

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() and TrackScreen():

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 queue when the app goes to the background and saves it to disk on quit
• Resumes session handling when the app returns
• Polls network reachability on the main thread (Update)

Session pings run on a timer while identified. Events tracked before IdentifyAsync succeeds are buffered and delivered once a session exists.

Delivery

Devices, sessions, events and heartbeats go through one persistent queue and are sent in batches:

• When 20 items are queued, every 10 seconds while the queue is not empty, when the app goes to the background, and when connectivity returns
• Items leave the queue only after the server acknowledges them or rejects them permanently. Retryable failures are kept for up to 5 attempts
• Each event gets a unique id when Track is called, stable across retries, so the server can deduplicate
• Changing the API key clears data queued for the previous key

Offline Support

The queue is saved on disk under:

Application.persistentDataPath/phase-analytics-data/

When offline or when requests fail, items stay in the queue and survive app restarts. They are sent when connectivity returns and on lifecycle boundaries. Batches with 25 or more items are gzip-compressed.

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
• Queue writes are debounced (1 s, plus on pause/quit); the queue is capped at 1000 items / 1 MB
• Batches of up to 50 items per request; only the latest heartbeat per session is kept
• Failed requests retry with jittered backoff and honor Retry-After; requests time out after 10 seconds

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.