feat(audience): auto-include Unity context on game_launch (SDK-147)

Plan §5.1 and the Event Reference require game_launch to ship with
platform, version, buildGuid, unityVersion auto-detected. Until the
Day 4 DeviceCollector lands, game_launch was shipping with only the
studio-supplied distributionPlatform.

- ImmutableAudience gets a new internal seam, LaunchContextProvider,
  that returns a Dictionary<string, object> merged into game_launch
  properties. Core stays pure C# - the provider is installed from the
  Unity layer so no UnityEngine import leaks into Runtime/.
- FireGameLaunch wraps the provider call in try/catch with a clear
  warning. A buggy provider must never prevent the launch event from
  firing - game_launch is the most load-bearing attribution event.
- AudienceUnityHooks installs a default provider that reads
  Application.platform, Application.version, Application.buildGUID,
  Application.unityVersion. DeviceCollector (Day 4) can replace or
  extend this without re-wiring.
- config.DistributionPlatform keeps winning over any provider value:
  studios set it explicitly because Unity cannot auto-detect the
  distribution store, and that value is the one the attribution
  pipeline expects.

Three new tests: provider fields make it onto the event, config
overrides provider for distributionPlatform, and a throwing provider
doesn't skip the event. 154 passing.

Linear: SDK-147

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

Author: ImmutableJeffrey

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -28,6 +28,10 @@ public static class ImmutableAudience
         // PersistentDataPath on the config.
         internal static Func<string> DefaultPersistentDataPathProvider;
 
+        // AudienceUnityHooks sets this so game_launch can auto-include
+        // Unity context without the core referencing UnityEngine.
+        internal static Func<Dictionary<string, object>> LaunchContextProvider;
+
         // Starts the SDK. Call once at launch.
         public static void Init(AudienceConfig config)
         {
@@ -460,6 +464,8 @@ public static void Shutdown()
         // Shuts down (if initialised) and clears per-session state so a
         // fresh Init starts clean. Used on test teardown and by Unity
         // SubsystemRegistration to survive "disable domain reload".
+        // LaunchContextProvider is not cleared: AudienceUnityHooks
+        // re-assigns it on the same SubsystemRegistration call.
         internal static void ResetState()
         {
             if (_initialized)
@@ -549,10 +555,32 @@ private static void FireGameLaunch(AudienceConfig config, ConsentLevel consentAt
 
             var properties = new Dictionary<string, object>();
 
+            // Unity-side auto-detected context (platform, version, buildGuid,
+            // unityVersion) from AudienceUnityHooks. Core stays pure C#; the
+            // Unity layer fills these via LaunchContextProvider.
+            var provider = LaunchContextProvider;
+            if (provider != null)
+            {
+                Dictionary<string, object> unityContext = null;
+                try { unityContext = provider(); }
+                catch (Exception ex)
+                {
+                    Log.Warn($"LaunchContextProvider threw {ex.GetType().Name}: {ex.Message}. " +
+                             "game_launch will ship without auto-detected Unity context.");
+                }
+
+                if (unityContext != null)
+                {
+                    foreach (var kvp in unityContext)
+                        properties[kvp.Key] = kvp.Value;
+                }
+            }
+
+            // Config-supplied distributionPlatform wins over any provider value;
+            // studios set it explicitly because Unity cannot auto-detect the store.
             if (config.DistributionPlatform != null)
                 properties["distributionPlatform"] = config.DistributionPlatform;
 
-            // Device-derived fields (platform, version, buildGuid, unityVersion) land with DeviceCollector.
             Track("game_launch", properties.Count > 0 ? properties : null);
         }
     }

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

@@ -1,3 +1,4 @@
+using System.Collections.Generic;
 using UnityEngine;
 
 namespace Immutable.Audience.Unity
@@ -15,8 +16,18 @@ private static void Install()
             Application.quitting += ImmutableAudience.Shutdown;
 
             ImmutableAudience.DefaultPersistentDataPathProvider = () => Application.persistentDataPath;
+            ImmutableAudience.LaunchContextProvider = BuildLaunchContext;
 
             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/Tests/Runtime/ImmutableAudienceTests.cs

@@ -26,6 +26,7 @@ public void SetUp()
         public void TearDown()
         {
             ImmutableAudience.ResetState();
+            ImmutableAudience.LaunchContextProvider = null;
             ImmutableAudience.DefaultPersistentDataPathProvider = null;
             Identity.Reset(_testDir);
             if (Directory.Exists(_testDir))
@@ -659,6 +660,69 @@ public void Init_ConsentNone_DoesNotFireGameLaunch()
             Assert.IsFalse(contents.Any(c => c.Contains("\"game_launch\"")));
         }
 
+        [Test]
+        public void Init_GameLaunch_IncludesLaunchContextProviderFields()
+        {
+            ImmutableAudience.LaunchContextProvider = () => new Dictionary<string, object>
+            {
+                ["platform"] = "WindowsPlayer",
+                ["version"] = "1.2.3",
+                ["buildGuid"] = "a1b2c3d4e5f6",
+                ["unityVersion"] = "2022.3.20f1",
+            };
+
+            ImmutableAudience.Init(MakeConfig());
+            ImmutableAudience.Shutdown();
+
+            var queueDir = AudiencePaths.QueueDir(_testDir);
+            var launchFile = Directory.GetFiles(queueDir, "*.json")
+                .Select(File.ReadAllText)
+                .FirstOrDefault(c => c.Contains("\"game_launch\""));
+            Assert.IsNotNull(launchFile, "game_launch should have been enqueued");
+            StringAssert.Contains("\"platform\":\"WindowsPlayer\"", launchFile);
+            StringAssert.Contains("\"version\":\"1.2.3\"", launchFile);
+            StringAssert.Contains("\"buildGuid\":\"a1b2c3d4e5f6\"", launchFile);
+            StringAssert.Contains("\"unityVersion\":\"2022.3.20f1\"", launchFile);
+        }
+
+        [Test]
+        public void Init_GameLaunch_ConfigDistributionPlatformOverridesProvider()
+        {
+            ImmutableAudience.LaunchContextProvider = () => new Dictionary<string, object>
+            {
+                ["distributionPlatform"] = "provider_value",
+            };
+
+            var config = MakeConfig();
+            config.DistributionPlatform = DistributionPlatforms.Steam;
+            ImmutableAudience.Init(config);
+            ImmutableAudience.Shutdown();
+
+            var queueDir = AudiencePaths.QueueDir(_testDir);
+            var launchFile = Directory.GetFiles(queueDir, "*.json")
+                .Select(File.ReadAllText)
+                .First(c => c.Contains("\"game_launch\""));
+            StringAssert.Contains("\"distributionPlatform\":\"steam\"", launchFile);
+            Assert.IsFalse(launchFile.Contains("provider_value"),
+                "config.DistributionPlatform should win over the provider's value");
+        }
+
+        [Test]
+        public void Init_GameLaunch_ProviderThrows_StillFiresEvent()
+        {
+            ImmutableAudience.LaunchContextProvider = () =>
+                throw new InvalidOperationException("provider exploded");
+
+            Assert.DoesNotThrow(() => ImmutableAudience.Init(MakeConfig()));
+            ImmutableAudience.Shutdown();
+
+            var queueDir = AudiencePaths.QueueDir(_testDir);
+            var contents = Directory.GetFiles(queueDir, "*.json")
+                .Select(File.ReadAllText).ToList();
+            Assert.IsTrue(contents.Any(c => c.Contains("\"game_launch\"")),
+                "game_launch must still ship when the context provider throws");
+        }
+
         // -----------------------------------------------------------------
         // Shutdown
         // -----------------------------------------------------------------