feat(audience-env): explicit environment selection (dev / sandbox / production)

Replaces key-prefix URL derivation with an explicit AudienceEnvironment
enum. Studios pick Dev / Sandbox / Production via
AudienceConfig.Environment; default is Sandbox so a misconfigured
integration cannot accidentally send production traffic — Production
is opt-in.

API changes:

- AudienceEnvironment enum: Dev / Sandbox / Production.
- AudienceConfig.Environment field, default Sandbox.
- Constants.DevBaseUrl added; Constants.BaseUrl / MessagesUrl /
  ConsentUrl / DataUrl now take an AudienceEnvironment (the old
  publishable-key parameter is gone).
- HttpTransport constructor accepts AudienceEnvironment (default
  Sandbox); removes the old key-prefix URL logic.
- ImmutableAudience.Init wires config.Environment into HttpTransport;
  DeleteData and SetConsent thread it through to their control-plane
  URLs.
- ImmutableAudience.CurrentEnvironment public getter returns the
  last Init's env. Survives Shutdown so a diagnostic HUD does not
  flicker to Sandbox on teardown; pre-Init returns Sandbox;
  ResetState restores the Sandbox default.

Behavior change worth flagging: integrations using a production-
prefixed key that left Environment unset previously hit production
via the key-prefix path; they now hit Sandbox until Environment =
Production is set explicitly. Test-key integrations already got
Sandbox and are unaffected.

Tests cover every env → URL mapping, HttpTransport honoring
explicit Dev / Production over the Sandbox default, and
CurrentEnvironment pre-Init / post-Shutdown / default-Sandbox
behaviour.

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

Author: ImmutableJeffrey

src/Packages/Audience/Runtime/AudienceConfig.cs

@@ -10,6 +10,10 @@ public class AudienceConfig
         // Studio API key. Required — Init throws if null.
         public string? PublishableKey { get; set; }
 
+        // Target backend. Sandbox default prevents accidental production
+        // traffic; pin to Production explicitly when shipping to players.
+        public AudienceEnvironment Environment { get; set; } = AudienceEnvironment.Sandbox;
+
         // Initial consent level.
         public ConsentLevel Consent { get; set; } = ConsentLevel.None;
 

src/Packages/Audience/Runtime/AudienceEnvironment.cs

@@ -0,0 +1,12 @@
+#nullable enable
+
+namespace Immutable.Audience
+{
+    public enum AudienceEnvironment
+    {
+        // Immutable-internal development backend; not intended for studios.
+        Dev,
+        Sandbox,
+        Production,
+    }
+}

src/Packages/Audience/Runtime/Core/Constants.cs

@@ -4,7 +4,7 @@ namespace Immutable.Audience
 {
     internal static class Constants
     {
-        internal const string TestKeyPrefix = "pk_imapik-test-";
+        internal const string DevBaseUrl = "https://api.dev.immutable.com";
         internal const string SandboxBaseUrl = "https://api.sandbox.immutable.com";
         internal const string ProductionBaseUrl = "https://api.immutable.com";
 
@@ -26,14 +26,21 @@ internal static class Constants
 
         internal const string PublishableKeyHeader = "x-immutable-publishable-key";
 
-        internal static string MessagesUrl(string? publishableKey) => BaseUrl(publishableKey) + MessagesPath;
-        internal static string ConsentUrl(string? publishableKey) => BaseUrl(publishableKey) + ConsentPath;
-        internal static string DataUrl(string? publishableKey) => BaseUrl(publishableKey) + DataPath;
+        internal static string MessagesUrl(AudienceEnvironment environment) => BaseUrl(environment) + MessagesPath;
+        internal static string ConsentUrl(AudienceEnvironment environment) => BaseUrl(environment) + ConsentPath;
+        internal static string DataUrl(AudienceEnvironment environment) => BaseUrl(environment) + DataPath;
 
-        internal static string BaseUrl(string? publishableKey) =>
-            publishableKey != null && publishableKey.StartsWith(TestKeyPrefix)
-                ? SandboxBaseUrl
-                : ProductionBaseUrl;
+        internal static string BaseUrl(AudienceEnvironment environment) =>
+            environment switch
+            {
+                AudienceEnvironment.Dev => DevBaseUrl,
+                AudienceEnvironment.Sandbox => SandboxBaseUrl,
+                AudienceEnvironment.Production => ProductionBaseUrl,
+                // Defensive: a future enum addition we forget to wire up
+                // falls back to Sandbox so accidental production traffic
+                // is impossible without explicit opt-in.
+                _ => SandboxBaseUrl,
+            };
     }
 
     // Message type values written to (and read back from) the "type" field.

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -62,6 +62,11 @@ public static class ImmutableAudience
         // a prior session changed it.
         public static ConsentLevel CurrentConsent => _state.Level;
 
+        // Caches the last Init's env so a diagnostic HUD does not flicker
+        // to the Sandbox default when Shutdown clears _config.
+        public static AudienceEnvironment CurrentEnvironment => _currentEnvironment;
+        private static volatile AudienceEnvironment _currentEnvironment = AudienceEnvironment.Sandbox;
+
         public static string? UserId => _state.UserId;
 
         // Display-only — Reset and SetConsent(None) wipe it, so it is not
@@ -125,14 +130,15 @@ public static void Init(AudienceConfig config)
                 }
 
                 _config = config;
+                _currentEnvironment = config.Environment;
                 Log.Enabled = config.Debug;
                 // Persisted consent overrides the config default (prior downgrade survives restart).
                 var initialLevel = ConsentStore.Load(config.PersistentDataPath) ?? config.Consent;
                 _state = new ConsentState(initialLevel, null);
 
                 _store = new DiskStore(config.PersistentDataPath);
                 _queue = new EventQueue(_store, config.FlushIntervalSeconds, config.FlushSize);
-                _transport = new HttpTransport(_store, config.PublishableKey, config.OnError, config.HttpHandler);
+                _transport = new HttpTransport(_store, config.PublishableKey, config.Environment, config.OnError, config.HttpHandler);
                 _controlClient = config.HttpHandler != null
                     ? new HttpClient(config.HttpHandler, disposeHandler: false)
                     : new HttpClient();
@@ -388,7 +394,7 @@ public static Task DeleteData(string? userId = null)
                 query = "anonymousId=" + Uri.EscapeDataString(anonymousId);
             }
 
-            var url = Constants.DataUrl(config.PublishableKey) + "?" + query;
+            var url = Constants.DataUrl(config.Environment) + "?" + query;
             var onError = config.OnError;
             var publishableKey = config.PublishableKey;
             var cancellationToken = _shutdownCancellationSource?.Token ?? CancellationToken.None;
@@ -550,7 +556,7 @@ private static void SyncConsentToBackend(AudienceConfig config, ConsentLevel lev
             var client = _controlClient;
             if (client == null) return;
 
-            var url = Constants.ConsentUrl(config.PublishableKey);
+            var url = Constants.ConsentUrl(config.Environment);
             var publishableKey = config.PublishableKey;
             var onError = config.OnError;
             var cancellationToken = _shutdownCancellationSource?.Token ?? CancellationToken.None;
@@ -765,6 +771,9 @@ internal static void ResetState()
                 // Defensive: Shutdown nulls _session too, but a future refactor
                 // that bails before that null must not leak a stale Session.
                 _session = null;
+                // Reset the env cache so test isolation and domain-reload
+                // both start from Sandbox; a subsequent Init overwrites it.
+                _currentEnvironment = AudienceEnvironment.Sandbox;
                 Identity.ClearCache();
             }
         }

src/Packages/Audience/Runtime/Transport/HttpTransport.cs

@@ -28,18 +28,21 @@ internal sealed class HttpTransport : IDisposable
 
         // store: source of event batches.
         // publishableKey: sent as x-immutable-publishable-key on every request.
+        // environment: which backend to send to. Defaults to Sandbox so
+        //   tests and ad-hoc construction cannot accidentally hit production.
         // onError: optional failure callback. Exceptions thrown inside it are caught.
         // handler / getUtcNow: test seams; null for production use.
         internal HttpTransport(
             DiskStore store,
             string publishableKey,
+            AudienceEnvironment environment = AudienceEnvironment.Sandbox,
             Action<AudienceError>? onError = null,
             HttpMessageHandler? handler = null,
             Func<DateTime>? getUtcNow = null)
         {
             _store = store ?? throw new ArgumentNullException(nameof(store));
             _publishableKey = publishableKey ?? throw new ArgumentNullException(nameof(publishableKey));
-            _url = Constants.MessagesUrl(publishableKey);
+            _url = Constants.MessagesUrl(environment);
             _onError = onError;
             // disposeHandler: false so the consumer can reuse their handler
             // across Init/Shutdown cycles (matches _controlClient's policy).

src/Packages/Audience/Tests/Runtime/ConsentSyncTests.cs

@@ -42,7 +42,7 @@ public void SetConsent_FiresPut_WithExpectedBodyShape()
             var put = WaitForPut(handler);
             var body = JsonReader.DeserializeObject(put.Body);
 
-            Assert.AreEqual(Constants.ConsentUrl("pk_imapik-test-key1"), put.Url);
+            Assert.AreEqual(Constants.ConsentUrl(AudienceEnvironment.Sandbox), put.Url);
             Assert.AreEqual("full", body["status"]);
             Assert.AreEqual(Constants.ConsentSource, body["source"]);
             Assert.IsTrue(body.ContainsKey("anonymousId"));

src/Packages/Audience/Tests/Runtime/ConstantsTests.cs

@@ -6,6 +6,32 @@ namespace Immutable.Audience.Tests
     [TestFixture]
     internal class ConstantsTests
     {
+        // -----------------------------------------------------------------
+        // BaseUrl per environment
+        // -----------------------------------------------------------------
+
+        [Test]
+        public void BaseUrl_Dev_ReturnsDevHost()
+        {
+            Assert.AreEqual(Constants.DevBaseUrl, Constants.BaseUrl(AudienceEnvironment.Dev));
+        }
+
+        [Test]
+        public void BaseUrl_Sandbox_ReturnsSandboxHost()
+        {
+            Assert.AreEqual(Constants.SandboxBaseUrl, Constants.BaseUrl(AudienceEnvironment.Sandbox));
+        }
+
+        [Test]
+        public void BaseUrl_Production_ReturnsProductionHost()
+        {
+            Assert.AreEqual(Constants.ProductionBaseUrl, Constants.BaseUrl(AudienceEnvironment.Production));
+        }
+
+        // -----------------------------------------------------------------
+        // Library version
+        // -----------------------------------------------------------------
+
         [Test]
         public void LibraryVersion_MatchesPackageJson()
         {

src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs

@@ -80,6 +80,53 @@ public void Initialized_FlipsAroundInitAndShutdown()
                 "Initialized should flip back to false after Shutdown");
         }
 
+        [Test]
+        public void CurrentEnvironment_DefaultsToSandbox()
+        {
+            // MakeConfig() leaves Environment unset, which means
+            // AudienceConfig's Sandbox default applies.
+            ImmutableAudience.Init(MakeConfig());
+            Assert.AreEqual(AudienceEnvironment.Sandbox,
+                ImmutableAudience.CurrentEnvironment);
+        }
+
+        [Test]
+        public void CurrentEnvironment_ExplicitDev_PassesThrough()
+        {
+            var config = MakeConfig();
+            config.Environment = AudienceEnvironment.Dev;
+            ImmutableAudience.Init(config);
+            Assert.AreEqual(AudienceEnvironment.Dev,
+                ImmutableAudience.CurrentEnvironment);
+        }
+
+        [Test]
+        public void CurrentEnvironment_BeforeInit_ReturnsSandbox()
+        {
+            // Pre-Init there is no config to read. Returning Sandbox
+            // matches the AudienceConfig default so UI never shows a
+            // separate "(uninitialised)" sentinel for this row.
+            Assert.AreEqual(AudienceEnvironment.Sandbox,
+                ImmutableAudience.CurrentEnvironment);
+        }
+
+        [Test]
+        public void CurrentEnvironment_SurvivesShutdown()
+        {
+            // A diagnostic HUD running in Production must not flicker to
+            // Sandbox when the SDK tears down. CurrentEnvironment caches
+            // the last Init's env so it keeps reporting the same value
+            // after Shutdown clears _config.
+            var config = MakeConfig();
+            config.Environment = AudienceEnvironment.Production;
+            ImmutableAudience.Init(config);
+            ImmutableAudience.Shutdown();
+
+            Assert.AreEqual(AudienceEnvironment.Production,
+                ImmutableAudience.CurrentEnvironment,
+                "CurrentEnvironment should retain the last Init's value after Shutdown");
+        }
+
         [Test]
         public void CurrentConsent_ReflectsLatestSetConsent()
         {

src/Packages/Audience/Tests/Runtime/Transport/HttpTransportTests.cs

@@ -123,7 +123,7 @@ public async Task SendBatchAsync_200_SendsPlainJsonPayloadWithoutContentEncoding
 #endif
 
         [Test]
-        public async Task SendBatchAsync_200_UsesCorrectUrlForTestKey()
+        public async Task SendBatchAsync_DefaultEnvironment_HitsSandbox()
         {
             _store.Write("{\"type\":\"track\"}");
 
@@ -138,14 +138,31 @@ public async Task SendBatchAsync_200_UsesCorrectUrlForTestKey()
         }
 
         [Test]
-        public async Task SendBatchAsync_200_UsesCorrectUrlForProdKey()
+        public async Task SendBatchAsync_ExplicitDev_HitsDev()
         {
             _store.Write("{\"type\":\"track\"}");
 
             HttpRequestMessage captured = null;
             var handler = new MockHandler(HttpStatusCode.OK, "{\"accepted\":1,\"rejected\":0}",
                 onRequest: req => captured = req);
-            using var transport = new HttpTransport(_store, "pk_imapik-prodkey", handler: handler);
+            using var transport = new HttpTransport(_store, "pk_imapik-test-key1",
+                environment: AudienceEnvironment.Dev, handler: handler);
+
+            await transport.SendBatchAsync();
+
+            StringAssert.StartsWith(Constants.DevBaseUrl, captured.RequestUri.ToString());
+        }
+
+        [Test]
+        public async Task SendBatchAsync_ExplicitProduction_HitsProduction()
+        {
+            _store.Write("{\"type\":\"track\"}");
+
+            HttpRequestMessage captured = null;
+            var handler = new MockHandler(HttpStatusCode.OK, "{\"accepted\":1,\"rejected\":0}",
+                onRequest: req => captured = req);
+            using var transport = new HttpTransport(_store, "pk_imapik-test-key1",
+                environment: AudienceEnvironment.Production, handler: handler);
 
             await transport.SendBatchAsync();