feat(audience-unity): add Unity integration layer for context and lifecycle (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
- 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)
- UnityLifecycleBridge.cs — lifecycle forwarder

Core changes in ImmutableAudience:

- LaunchContextProvider / ContextProvider typed as
  Func<IReadOnlyDictionary<string, object>>? so the cached snapshot
  cannot be mutated by any downstream reader
- 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

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/Core/Session.cs

@@ -29,7 +29,6 @@ internal sealed class Session : IDisposable
         internal const int PauseTimeoutMs = 30_000;
 
         private readonly TrackDelegate _track;
-        private readonly Func<Dictionary<string, object>>? _performanceSnapshot;
         private readonly Func<DateTime> _getUtcNow;
         private readonly int _heartbeatIntervalMs;
         private readonly object _lock = new object();
@@ -48,16 +47,13 @@ internal string? SessionId
             get { lock (_lock) return _sessionId; }
         }
 
-        // track: fires session events. performanceSnapshot: merges fps/memory
-        // into heartbeats (null on non-Unity). getUtcNow/heartbeatIntervalMs: test seams.
+        // track: fires session events. getUtcNow/heartbeatIntervalMs: test seams.
         internal Session(
             TrackDelegate track,
-            Func<Dictionary<string, object>>? performanceSnapshot = null,
             Func<DateTime>? getUtcNow = null,
             int heartbeatIntervalMs = HeartbeatIntervalMs)
         {
             _track = track ?? throw new ArgumentNullException(nameof(track));
-            _performanceSnapshot = performanceSnapshot;
             _getUtcNow = getUtcNow ?? (() => DateTime.UtcNow);
             _heartbeatIntervalMs = heartbeatIntervalMs;
         }
@@ -252,24 +248,13 @@ internal void OnHeartbeat()
                 duration = ComputeEngagedSecondsLocked();
             }
 
-            // Build outside _lock so snapshot + track don't re-enter.
+            // Build outside _lock so track doesn't re-enter.
             var properties = new Dictionary<string, object>
             {
                 ["sessionId"] = sessionId,
                 ["durationSec"] = duration
             };
 
-            var perf = SafePerformanceSnapshot();
-            if (perf != null)
-            {
-                foreach (var kv in perf)
-                {
-                    // Don't let the provider clobber core fields.
-                    if (properties.ContainsKey(kv.Key)) continue;
-                    properties[kv.Key] = kv.Value;
-                }
-            }
-
             SafeTrack("session_heartbeat", properties);
         }
 
@@ -289,22 +274,6 @@ private void SafeTrack(string eventName, Dictionary<string, object> properties)
             }
         }
 
-        // Stops exceptions from the studio-supplied snapshot callback from
-        // reaching the background timer.
-        private Dictionary<string, object>? SafePerformanceSnapshot()
-        {
-            if (_performanceSnapshot == null) return null;
-            try
-            {
-                return _performanceSnapshot();
-            }
-            catch (Exception ex)
-            {
-                Log.Warn($"Session: performance snapshot threw {ex.GetType().Name}. Heartbeat ships without performance fields.");
-                return null;
-            }
-        }
-
         // Stops the timer and waits for the in-flight callback. Runs outside
         // _lock (OnHeartbeat re-enters). 1s budget (quits must not hang). Warns on timeout.
         private void DrainHeartbeatTimer()

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -38,12 +38,13 @@ 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 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;
 
         // Active session. Created at Init (or on upgrade from None) and disposed
         // on Shutdown or SetConsent(None). Volatile so OnPause/OnResume see
@@ -701,9 +702,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 +742,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 +756,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 +856,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,6 +1,7 @@
 #nullable enable
 
 using System.Collections.Generic;
+using System.Collections.ObjectModel;
 using UnityEngine;
 
 namespace Immutable.Audience.Unity
@@ -10,26 +11,25 @@ internal static class AudienceUnityHooks
         [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();
 
             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);
+        }
+    }
+}