feat(audience-unity): add Unity integration layer for context, lifecycle, and performance (SDK-146)

AudienceUnityHooks installs on SubsystemRegistration and wires:

- DefaultPersistentDataPathProvider from Application.persistentDataPath
- LaunchContextProvider with DeviceCollector's one-shot game_launch
  fields (platform, version, buildGuid, unityVersion, osFamily,
  deviceModel, gpu*, cpu*, ramMb, screenDpi)
- ContextProvider with userAgent / locale / timezone / screen, merged
  into every outgoing message.context
- PerformanceSnapshotProvider returns the fpsAvg / fpsMin /
  memoryUsedMb / memoryReservedMb accumulated since the last read;
  Session.OnHeartbeat reads and merges it
- Application.quitting -> ImmutableAudience.Shutdown
- UnityLifecycleBridge forwards OnApplicationPause / OnApplicationFocus
  to ImmutableAudience.OnPause / OnResume

New Unity-layer files (Runtime/Unity/):

- DeviceCollector.cs — IL2CPP-safe SystemInfo / Screen / Application
  readers. Strings capped at 256 chars to mirror the Web SDK identifier
  cap (core/src/validation.ts MAX_STRING_LENGTH)
- PerformanceCollector.cs — per-frame fps + memory accumulator read
  off the main thread via SnapshotAndReset
- UnityLifecycleBridge.cs — lifecycle forwarder + per-frame tick

Core changes in ImmutableAudience:

- LaunchContextProvider / ContextProvider typed as
  Func<IReadOnlyDictionary<string, object>>? so the cached snapshot
  cannot be mutated by any downstream reader
- PerformanceSnapshotProvider added with the same one-shot-capture
  contract
- All three Session constructor sites (Init, Reset-creates-session,
  None -> Anonymous/Full upgrade in SetConsent) pass
  PerformanceSnapshotProvider as the second arg
- MergeUnityContext merges ContextProvider output into every outgoing
  message.context before EnqueueChecked; throws and null returns are
  swallowed so a misbehaving layer cannot drop events

Build and test infrastructure:

- Directory.Build.props redirects bin/obj to repo-root artifacts/ so
  dotnet output doesn't leak into Unity's asset importer scan path
- ConstantsTests walks up from the test binary to find the package
  root so the Directory.Build.props redirect doesn't break it
- com.immutable.audience / .unity asmdefs updated
- link.xml preserves Unity hooks from IL2CPP stripping
- .gitignore adds artifacts/

Tests:

- ContextProvider_Set / _Throwing / _ReturnsNull pin the merge +
  swallow behaviour
- PerformanceSnapshotProvider_ReachesHeartbeat variants pin Init,
  consent upgrade, and Reset ctor sites — dropping the provider from
  any single site fails a distinct test

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: ImmutableJeffrey

.gitignore

@@ -10,6 +10,16 @@
 [Ll]ogs/
 [Uu]ser[Ss]ettings/
 
+# dotnet build outputs redirected here via Directory.Build.props files
+# so bin/obj don't sit inside Unity package folders and get scanned.
+/artifacts/
+
+# IDE and MSBuild extensibility sidecars Unity emits .meta for when the
+# files land inside the package root.
+*.DotSettings.user.meta
+Directory.Build.props.meta
+Directory.Build.targets.meta
+
 # MemoryCaptures can get excessive in size.
 # They also could contain extremely sensitive data
 /[Mm]emoryCaptures/

src/Packages/Audience/Directory.Build.props

@@ -0,0 +1,21 @@
+<Project>
+  <!--
+    Redirect dotnet build outputs to a repo-root artifacts/ folder so they
+    don't leak into the Unity package directory. When the package is
+    referenced from a Unity project via a `file:` path, Unity scans every
+    folder under the package root. Finding bin/obj/*.dll trips
+    "Multiple precompiled assemblies" errors and the locale-specific
+    resource DLLs also confuse Unity's asset importer.
+
+    Targets:
+      artifacts/Audience.Runtime/bin|obj/
+      artifacts/Audience.Tests/bin|obj/
+
+    $(MSBuildThisFileDirectory) here = src/Packages/Audience/
+    ../../../artifacts/ = <repo-root>/artifacts/
+  -->
+  <PropertyGroup>
+    <BaseOutputPath>$(MSBuildThisFileDirectory)../../../artifacts/$(MSBuildProjectName)/bin/</BaseOutputPath>
+    <BaseIntermediateOutputPath>$(MSBuildThisFileDirectory)../../../artifacts/$(MSBuildProjectName)/obj/</BaseIntermediateOutputPath>
+  </PropertyGroup>
+</Project>

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -38,12 +38,14 @@ public static class ImmutableAudience
         // Gate against overlapping timer ticks (Timer callbacks run on independent ThreadPool threads).
         private static int _sendInFlight;
 
-        // AudienceUnityHooks sets these at SubsystemRegistration.
-        // DefaultPersistentDataPathProvider fills PersistentDataPath from
-        // Application.persistentDataPath. LaunchContextProvider supplies
-        // Unity context for game_launch without Core referencing UnityEngine.
-        internal static Func<string>? DefaultPersistentDataPathProvider;
-        internal static Func<Dictionary<string, object>>? LaunchContextProvider;
+        // volatile: assigned on the Unity main thread at SubsystemRegistration,
+        // read from the drain thread in Track / Identify / heartbeat paths.
+        // The assignments happen before any event can fire in practice, but
+        // volatile documents the cross-thread publish contract explicitly.
+        internal static volatile Func<string>? DefaultPersistentDataPathProvider;
+        internal static volatile Func<IReadOnlyDictionary<string, object>>? LaunchContextProvider;
+        internal static volatile Func<IReadOnlyDictionary<string, object>>? ContextProvider;
+        internal static volatile Func<Dictionary<string, object>>? PerformanceSnapshotProvider;
 
         // Active session. Created at Init (or on upgrade from None) and disposed
         // on Shutdown or SetConsent(None). Volatile so OnPause/OnResume see
@@ -100,7 +102,7 @@ public static void Init(AudienceConfig config)
                 // Session created under the lock; Start() deferred until after
                 // release because session_start → Track takes its own locks.
                 if (initialLevel.CanTrack())
-                    _session = new Session(Track);
+                    _session = new Session(Track, PerformanceSnapshotProvider);
 
                 // Captured reference: a later SetConsent(None) may dispose this
                 // Session (Start then no-ops on _disposed). Either way no duplicate
@@ -300,7 +302,7 @@ public static void Reset()
 
                 // Swap under the lock so racing SetConsent/OnPause/OnResume see
                 // either the old, the new, or null — never a torn reference.
-                _session = _state.Level.CanTrack() ? new Session(Track) : null;
+                _session = _state.Level.CanTrack() ? new Session(Track, PerformanceSnapshotProvider) : null;
                 newSession = _session;
             }
 
@@ -454,7 +456,7 @@ public static void SetConsent(ConsentLevel level)
                     // Upgrade from None: allocate + publish the new Session under
                     // the lock so a concurrent SetConsent / Init sees the new
                     // reference and the double-allocation guard above fires.
-                    newSession = new Session(Track);
+                    newSession = new Session(Track, PerformanceSnapshotProvider);
                     _session = newSession;
                 }
             }
@@ -701,9 +703,7 @@ public static void Shutdown()
         // Internal — shared with tests and AudienceUnityHooks
         // -----------------------------------------------------------------
 
-        // Shuts down (if initialised) and clears per-session state. Used on
-        // test teardown and Unity SubsystemRegistration to survive "disable
-        // domain reload". LaunchContextProvider is re-assigned by AudienceUnityHooks.
+        // Providers reassigned by SubsystemRegistration.
         internal static void ResetState()
         {
             // Shutdown manages its own serialisation and releases _initLock before
@@ -743,6 +743,7 @@ internal static void ResetState()
         // Anonymous the userId is stripped.
         private static void EnqueueTrack(Dictionary<string, object>? msg)
         {
+            MergeUnityContext(msg);
             _queue?.EnqueueChecked(msg, m =>
             {
                 var state = _state;
@@ -756,10 +757,41 @@ private static void EnqueueTrack(Dictionary<string, object>? msg)
         // Identify / Alias require Full; drop if consent has downgraded.
         private static void EnqueueIdentity(Dictionary<string, object>? msg)
         {
+            MergeUnityContext(msg);
             _queue?.EnqueueChecked(msg, m =>
                 _state.Level == ConsentLevel.Full ? m : null);
         }
 
+        private static void MergeUnityContext(Dictionary<string, object>? msg)
+        {
+            if (msg == null) return;
+
+            var provider = ContextProvider;
+            if (provider == null) return;
+
+            IReadOnlyDictionary<string, object>? extra;
+            try
+            {
+                extra = provider();
+            }
+            catch (Exception ex)
+            {
+                Log.Warn($"ContextProvider threw {ex.GetType().Name}: {ex.Message}. " +
+                         "Event ships with base context only.");
+                return;
+            }
+            if (extra == null) return;
+
+            if (!(msg.TryGetValue("context", out var ctxObj) && ctxObj is Dictionary<string, object> ctx))
+            {
+                ctx = new Dictionary<string, object>();
+                msg["context"] = ctx;
+            }
+
+            foreach (var kv in extra)
+                ctx[kv.Key] = kv.Value;
+        }
+
         private static void SendBatch()
         {
             // If a previous send is still running, skip this one. That send
@@ -825,7 +857,7 @@ private static void FireGameLaunch(AudienceConfig config, ConsentLevel consentAt
             var provider = LaunchContextProvider;
             if (provider != null)
             {
-                Dictionary<string, object>? unityContext = null;
+                IReadOnlyDictionary<string, object>? unityContext = null;
                 try { unityContext = provider(); }
                 catch (Exception ex)
                 {

src/Packages/Audience/Runtime/Unity/AudienceUnityHooks.cs

@@ -1,35 +1,40 @@
 #nullable enable
 
 using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using UnityEngine;
 
 namespace Immutable.Audience.Unity
 {
     internal static class AudienceUnityHooks
     {
+        private static PerformanceCollector? _perf;
+
         [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
         private static void Install()
         {
-            // Clear surviving statics before re-wiring in case "disable domain reload" kept them alive.
             ImmutableAudience.ResetState();
 
-            // -= then += so repeat SubsystemRegistration cycles don't stack subscriptions.
+            // Avoid stacked subscriptions on reload.
             Application.quitting -= ImmutableAudience.Shutdown;
             Application.quitting += ImmutableAudience.Shutdown;
 
             ImmutableAudience.DefaultPersistentDataPathProvider = () => Application.persistentDataPath;
-            ImmutableAudience.LaunchContextProvider = BuildLaunchContext;
+
+            // Captured once on main thread; ReadOnlyDictionary blocks downstream mutation.
+            IReadOnlyDictionary<string, object> launchProps =
+                new ReadOnlyDictionary<string, object>(DeviceCollector.CollectGameLaunchProperties());
+            IReadOnlyDictionary<string, object> contextProps =
+                new ReadOnlyDictionary<string, object>(DeviceCollector.CollectContext());
+            ImmutableAudience.LaunchContextProvider = () => launchProps;
+            ImmutableAudience.ContextProvider = () => contextProps;
+
+            UnityLifecycleBridge.EnsureExists();
+            _perf = new PerformanceCollector();
+            UnityLifecycleBridge.SetPerformanceCollector(_perf);
+            ImmutableAudience.PerformanceSnapshotProvider = _perf.SnapshotAndReset;
 
             if (Log.Writer == null) Log.Writer = Debug.Log;
         }
-
-        private static Dictionary<string, object> BuildLaunchContext() =>
-            new Dictionary<string, object>
-            {
-                ["platform"] = Application.platform.ToString(),
-                ["version"] = Application.version,
-                ["buildGuid"] = Application.buildGUID,
-                ["unityVersion"] = Application.unityVersion,
-            };
     }
 }

src/Packages/Audience/Runtime/Unity/DeviceCollector.cs

@@ -0,0 +1,102 @@
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using System.Globalization;
+using UnityEngine;
+
+namespace Immutable.Audience.Unity
+{
+    internal static class DeviceCollector
+    {
+        internal static Dictionary<string, object> CollectContext()
+        {
+            // 256-char cap mirrors Web SDK's identifier truncation.
+            var ctx = new Dictionary<string, object>
+            {
+                ["userAgent"] = Truncate(SystemInfo.operatingSystem, 256),
+            };
+
+            var timezone = SafeTimezone();
+            if (timezone != null) ctx["timezone"] = Truncate(timezone, 256);
+
+            var locale = LocaleString();
+            if (locale != null) ctx["locale"] = Truncate(locale, 256);
+
+            var screen = TryResolveScreenString();
+            if (screen != null) ctx["screen"] = Truncate(screen, 256);
+
+            return ctx;
+        }
+
+        private static string? TryResolveScreenString()
+        {
+            var resolution = Screen.currentResolution;
+            int width = resolution.width;
+            int height = resolution.height;
+
+            if (width <= 0 || height <= 0)
+            {
+                width = Screen.width;
+                height = Screen.height;
+            }
+
+            if (width <= 0 || height <= 0) return null;
+            return $"{width}x{height}";
+        }
+
+        internal static Dictionary<string, object> CollectGameLaunchProperties()
+        {
+            var props = new Dictionary<string, object>
+            {
+                ["platform"] = Application.platform.ToString(),
+                ["version"] = Truncate(Application.version, 256),
+                ["buildGuid"] = Truncate(Application.buildGUID, 256),
+                ["unityVersion"] = Truncate(Application.unityVersion, 256),
+                ["osFamily"] = SystemInfo.operatingSystemFamily.ToString(),
+                ["deviceModel"] = Truncate(SystemInfo.deviceModel, 256),
+                ["gpu"] = Truncate(SystemInfo.graphicsDeviceName, 256),
+                ["gpuVendor"] = Truncate(SystemInfo.graphicsDeviceVendor, 256),
+                ["cpu"] = Truncate(SystemInfo.processorType, 256),
+                ["cpuCores"] = SystemInfo.processorCount,
+                ["ramMb"] = SystemInfo.systemMemorySize,
+            };
+
+            // Screen.dpi can be 0 on some Linux WMs.
+            var dpi = (int)Screen.dpi;
+            if (dpi > 0) props["screenDpi"] = dpi;
+
+            return props;
+        }
+
+        private static string? LocaleString()
+        {
+            var culture = CultureInfo.CurrentCulture;
+            if (!string.IsNullOrEmpty(culture?.Name))
+                return culture.Name;
+            return null;
+        }
+
+        private static string? SafeTimezone()
+        {
+            try
+            {
+                return TimeZoneInfo.Local.Id;
+            }
+            catch (Exception)
+            {
+                return null;
+            }
+        }
+
+        private static string Truncate(string s, int max)
+        {
+            if (string.IsNullOrEmpty(s) || s.Length <= max) return s;
+            // Step back one if the cut would split a surrogate pair — leaving
+            // a lone high-surrogate produces invalid UTF-16 on the wire.
+            var cut = max;
+            if (char.IsHighSurrogate(s[cut - 1])) cut--;
+            return s.Substring(0, cut);
+        }
+    }
+}

src/Packages/Audience/Runtime/Unity/PerformanceCollector.cs

@@ -0,0 +1,84 @@
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+using UnityEngine;
+using UnityEngine.Profiling;
+
+namespace Immutable.Audience.Unity
+{
+    // fps + memory for session_heartbeat. RecordFrame: main thread, SnapshotAndReset: thread-safe.
+    internal sealed class PerformanceCollector
+    {
+        private readonly object _lock = new object();
+
+        private int _frameCount;
+        private float _elapsed;
+        private float _fpsMin = float.MaxValue;
+        private long _memUsedMb;
+        private long _memReservedMb;
+
+        private bool _memorySampleRequested = true;
+
+        internal void RecordFrame()
+        {
+            lock (_lock)
+            {
+                var dt = Time.unscaledDeltaTime;
+                _frameCount++;
+                _elapsed += dt;
+
+                if (dt > 0f)
+                {
+                    var instantFps = 1f / dt;
+                    if (instantFps < _fpsMin) _fpsMin = instantFps;
+                }
+
+                if (_memorySampleRequested)
+                {
+                    _memUsedMb = Profiler.GetTotalAllocatedMemoryLong() / (1024L * 1024L);
+                    _memReservedMb = Profiler.GetTotalReservedMemoryLong() / (1024L * 1024L);
+                    _memorySampleRequested = false;
+                }
+            }
+        }
+
+        internal Dictionary<string, object> SnapshotAndReset()
+        {
+            int frames;
+            float elapsed;
+            float fpsMin;
+            long memUsed;
+            long memReserved;
+
+            lock (_lock)
+            {
+                frames = _frameCount;
+                elapsed = _elapsed;
+                fpsMin = _fpsMin;
+                memUsed = _memUsedMb;
+                memReserved = _memReservedMb;
+
+                _frameCount = 0;
+                _elapsed = 0f;
+                _fpsMin = float.MaxValue;
+                _memorySampleRequested = true;
+            }
+
+            // Memory is a point-in-time reading — always meaningful. fps
+            // fields only ship when at least one frame was recorded, so the
+            // backend can tell "no sample" (fields absent) apart from
+            // "framerate dropped to zero" (fields present with value 0).
+            var result = new Dictionary<string, object>
+            {
+                ["memoryUsedMb"] = memUsed,
+                ["memoryReservedMb"] = memReserved,
+            };
+            if (frames > 0 && elapsed > 0f)
+                result["fpsAvg"] = Math.Round(frames / elapsed, 1);
+            if (fpsMin != float.MaxValue)
+                result["fpsMin"] = Math.Round(fpsMin, 1);
+            return result;
+        }
+    }
+}