feat(audience-sdk): iOS App Tracking Transparency + IDFA support (SDK-306)

Adds an async ATT prompt API and IDFA collection to the iOS attribution
surface introduced by SDK-307.

* ImmutableAudience.RequestTrackingAuthorizationAsync() — public async
  API returning a 4-state TrackingAuthorizationStatus enum. Studios
  decide when to show the prompt; resolves to NotDetermined off iOS or
  on iOS<14.
* attStatus + idfa shipped on game_launch when EnableMobileAttribution
  is true. IDFA is omitted unless the user has authorized.
* AudienceMobileBridge.mm extended with _AudienceRequestATT (objc_msgSend
  cast preserves block typing) / _AudienceGetATTStatus (IMP-cast to read
  NSUInteger return) / _AudienceGetIDFA (filters Apple's all-zeros UUID).
  Runtime dispatch via NSClassFromString — no hard framework links.
* ATTBridge.cs uses [MonoPInvokeCallback] + [Preserve] on the static
  status callback so the await completes under managed stripping=High;
  a static delegate field keeps the function pointer alive across
  Apple's async window.
* iOSFrameworkPostProcessor adds AdSupport.framework (required) and
  AppTrackingTransparency.framework (weak) to the UnityFramework target
  when AUDIENCE_MOBILE_ATTRIBUTION is set — without explicit linkage the
  IDFA NSClassFromString lookup returns nil and the field is silently
  dropped.
* Sample app: Mobile Attribution toggle and ATT button hide on
  Standalone (toggle is iOS+Android, button iOS-only). Button gated on
  API key + toggle so the result lands somewhere observable.

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

Author: nattb8

examples/audience/Assets/SampleApp/Resources/AudienceSample.uxml

@@ -99,10 +99,20 @@
                                      text="Mirror SDK internal log output into the in-page event log below." />
                         </ui:VisualElement>
 
-                        <ui:VisualElement class="field">
+                        <ui:VisualElement name="mobile-attribution-field" class="field">
                             <ui:Toggle name="enable-mobile-attribution" label="MOBILE ATTRIBUTION" />
                             <ui:Label class="helper-text below-field"
                                      text="Enable iOS SKAdNetwork registration and mobile attribution signals." />
+                            <ui:VisualElement name="att-section">
+                                <ui:VisualElement class="actions last">
+                                    <ui:Button name="btn-request-att" class="with-sig">
+                                        <ui:Label class="btn-label" text="Request ATT" />
+                                        <ui:Label class="btn-sig" text="requestTrackingAuthorizationAsync()" />
+                                    </ui:Button>
+                                </ui:VisualElement>
+                                <ui:Label class="helper-text below-field"
+                                         text="iOS-only. Triggers the system ATT prompt on first call; subsequent calls return the cached status." />
+                            </ui:VisualElement>
                         </ui:VisualElement>
 
                         <ui:VisualElement class="field placeholder-host">

examples/audience/Assets/SampleApp/Scripts/AudienceSample.UI.cs

@@ -53,7 +53,7 @@ private static readonly (string TabId, string PanelId)[] Tabs =
         private TextField _publishableKey, _baseUrl, _flushInterval, _flushSize;
         private DropdownField _initialConsent;
         private Toggle _debug, _enableMobileAttribution;
-        private Button _btnInit, _btnFlush, _btnReset, _btnShutdown, _btnDeleteData;
+        private Button _btnInit, _btnFlush, _btnReset, _btnShutdown, _btnDeleteData, _btnRequestAtt;
 
         // ---- UXML element fields (Consent tab) ----
 
@@ -197,10 +197,13 @@ private void BindElements()
             _flushSize     = Require<TextField>("flush-size");
             _btnInit       = Require<Button>("btn-init");
 
-            _btnFlush      = Require<Button>("btn-flush");
-            _btnReset      = Require<Button>("btn-reset");
-            _btnShutdown   = Require<Button>("btn-shutdown");
-            _btnDeleteData = Require<Button>("btn-delete-data");
+            _btnFlush       = Require<Button>("btn-flush");
+            _btnReset       = Require<Button>("btn-reset");
+            _btnShutdown    = Require<Button>("btn-shutdown");
+            _btnDeleteData  = Require<Button>("btn-delete-data");
+            _btnRequestAtt  = Require<Button>("btn-request-att");
+
+            ApplyMobilePlatformVisibility();
 
             _consentPills = new Dictionary<ConsentLevel, Button>
             {
@@ -247,6 +250,24 @@ private void BindElements()
             _logCount = Require<Label>("log-count");
         }
 
+        // EnableMobileAttribution is a no-op on Standalone, so the toggle and
+        // ATT button only appear on iOS/Android. ATT is iOS-only — Android
+        // attribution uses a different signal — so the ATT subsection is
+        // hidden on Android even when the toggle remains visible.
+        // UNITY_IOS / UNITY_ANDROID also evaluate true in the Editor when the
+        // matching build target is active, which is the right behavior for
+        // testing.
+        private void ApplyMobilePlatformVisibility()
+        {
+#if !(UNITY_IOS || UNITY_ANDROID)
+            var mobileField = _root.Q<VisualElement>("mobile-attribution-field");
+            if (mobileField != null) mobileField.style.display = DisplayStyle.None;
+#elif !UNITY_IOS
+            var attSection = _root.Q<VisualElement>("att-section");
+            if (attSection != null) attSection.style.display = DisplayStyle.None;
+#endif
+        }
+
         private void PopulateDropdowns()
         {
             _initialConsent.choices = ConsentOrder.Select(c => c.ToLowercaseString()).ToList();
@@ -300,16 +321,18 @@ private void RegisterHandlers()
                 _identifyId, _identifyTraits, _traitsUpdate,
             }) RegisterPlaceholder(field);
 
-            _publishableKey.RegisterValueChangedCallback(_ => { _btnInit.SetEnabled(!_initialised && !string.IsNullOrWhiteSpace(_publishableKey.value)); RefreshStatusBar(); });
+            _publishableKey.RegisterValueChangedCallback(_ => { _btnInit.SetEnabled(!_initialised && !string.IsNullOrWhiteSpace(_publishableKey.value)); UpdateAttButtonGate(); RefreshStatusBar(); });
             _initialConsent.RegisterValueChangedCallback(_ => RefreshStatusBar());
             _baseUrl.RegisterValueChangedCallback(_ => RefreshStatusBar());
+            _enableMobileAttribution.RegisterValueChangedCallback(_ => UpdateAttButtonGate());
 
             _btnInit.clicked += OnInit;
 
             _btnFlush.clicked += async () => await OnFlushAsync();
             _btnReset.clicked += OnReset;
             _btnShutdown.clicked += OnShutdown;
             _btnDeleteData.clicked += async () => await OnDeleteDataAsync();
+            _btnRequestAtt.clicked += async () => await OnRequestAttAsync();
             _btnIdentify.clicked += OnIdentify;
             _btnIdentifyTraits.clicked += OnIdentifyTraits;
             _btnAlias.clicked += OnAlias;
@@ -621,6 +644,18 @@ private void RefreshInitState()
             foreach (var btn in _typedEventsHost.Query<Button>().ToList()) btn.SetEnabled(_initialised);
             _btnInit.SetEnabled(!_initialised && !string.IsNullOrWhiteSpace(_publishableKey.value));
             _btnAlias.SetEnabled(_initialised && IsAliasReady());
+            UpdateAttButtonGate();
+        }
+
+        // ATT prompt is independent of SDK init, but in the demo flow it's
+        // only useful once a key is set (so events have somewhere to ship)
+        // and the toggle is on (so the chosen status actually appears on
+        // game_launch via MobileAttributionContextProvider).
+        private void UpdateAttButtonGate()
+        {
+            _btnRequestAtt.SetEnabled(
+                !string.IsNullOrWhiteSpace(_publishableKey.value) &&
+                _enableMobileAttribution.value);
         }
 
         private void RefreshIdentityPanel()

examples/audience/Assets/SampleApp/Scripts/AudienceSample.cs

@@ -101,6 +101,21 @@ private async Task OnDeleteDataAsync()
             }
         }
 
+        private async Task OnRequestAttAsync()
+        {
+            AppendLog("requestTrackingAuthorizationAsync()", "ATT request dispatched", LogLevel.Info, LogSource.App);
+            try
+            {
+                var status = await ImmutableAudience.RequestTrackingAuthorizationAsync();
+                AppendLog("requestTrackingAuthorizationAsync()",
+                    $"status: {status}", LogLevel.Ok, LogSource.App);
+            }
+            catch (Exception ex)
+            {
+                AppendLog("requestTrackingAuthorizationAsync()", ex.Message, LogLevel.Err, LogSource.App);
+            }
+        }
+
         // ---- SDK action handlers: telemetry ----
 
         // Prefers the typed overload for the four events with public C#

examples/audience/ProjectSettings/ProjectSettings.asset

@@ -158,8 +158,8 @@ PlayerSettings:
   androidSupportedAspectRatio: 1
   androidMaxAspectRatio: 2.1
   applicationIdentifier:
-    iPhone: com.immutable.audience
     Android: com.immutable.audience
+    iPhone: com.Immutable.audience
   buildNumber:
     Standalone: 0
     iPhone: 0
@@ -808,7 +808,8 @@ PlayerSettings:
   webGLThreadsSupport: 0
   webGLDecompressionFallback: 0
   webGLPowerPreference: 2
-  scriptingDefineSymbols: {}
+  scriptingDefineSymbols:
+    iPhone: AUDIENCE_MOBILE_ATTRIBUTION
   additionalCompilerArguments: {}
   platformArchitecture: {}
   scriptingBackend:
@@ -817,6 +818,7 @@ PlayerSettings:
     iPhone: 1
   il2cppCompilerConfiguration: {}
   managedStrippingLevel:
+    Android: 3
     EmbeddedLinux: 1
     GameCoreScarlett: 1
     GameCoreXboxOne: 1
@@ -829,7 +831,6 @@ PlayerSettings:
     WebGL: 1
     Windows Store Apps: 1
     XboxOne: 1
-    Android: 3
     iPhone: 3
     tvOS: 1
   incrementalIl2cppBuild: {}

src/Packages/Audience/Editor/iOSFrameworkPostProcessor.cs

@@ -0,0 +1,92 @@
+#nullable enable
+
+using System.IO;
+using UnityEditor;
+using UnityEditor.Callbacks;
+using UnityEngine;
+#if UNITY_IOS
+using UnityEditor.iOS.Xcode;
+#endif
+
+namespace Immutable.Audience.Editor
+{
+    /// <summary>
+    /// Links the Apple frameworks the runtime mobile-attribution code needs
+    /// into the generated iOS Xcode project.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// <c>AdSupport.framework</c> hosts <c>ASIdentifierManager</c> (the IDFA
+    /// accessor). Without it linked, the runtime <c>NSClassFromString</c>
+    /// lookup returns nil and the IDFA is silently dropped from
+    /// <c>game_launch</c> — the Info.plist key alone does not load this
+    /// framework. Linked as a required dep; the framework has shipped on
+    /// every iOS release since 6.0.
+    /// </para>
+    /// <para>
+    /// <c>AppTrackingTransparency.framework</c> hosts <c>ATTrackingManager</c>.
+    /// Unity often auto-links this when <c>NSUserTrackingUsageDescription</c>
+    /// is present, but the auto-link heuristic is undocumented and
+    /// version-sensitive — an explicit weak link is immune to that drift and
+    /// keeps the binary loadable on iOS &lt; 14 (the runtime code already
+    /// guards via <c>NSClassFromString</c>).
+    /// </para>
+    /// <para>
+    /// Gated on the same <c>AUDIENCE_MOBILE_ATTRIBUTION</c> scripting define
+    /// as the Info.plist post-processor so studios who haven't opted into
+    /// attribution ship a clean Frameworks list.
+    /// </para>
+    /// </remarks>
+    internal static class iOSFrameworkPostProcessor
+    {
+        // Runs just after the Info.plist post-processor (9050). Order is
+        // independent in practice — both edit different files — but keeping
+        // them adjacent makes the build log obvious.
+        internal const int CallbackOrder = 9051;
+
+        [PostProcessBuild(CallbackOrder)]
+        internal static void OnPostProcessBuild(BuildTarget target, string pathToBuiltProject)
+        {
+            if (target != BuildTarget.iOS) return;
+
+#if UNITY_IOS
+            if (!AttributionDefineEnabled()) return;
+
+            var pbxPath = PBXProject.GetPBXProjectPath(pathToBuiltProject);
+            if (!File.Exists(pbxPath))
+            {
+                Debug.LogWarning(
+                    $"[ImmutableAudience] iOS framework post-processor: project.pbxproj not found at {pbxPath}. Skipping.");
+                return;
+            }
+
+            var pbx = new PBXProject();
+            pbx.ReadFromFile(pbxPath);
+
+            // Native plugin code under Runtime/Plugins/iOS compiles into the
+            // UnityFramework target on Unity 2019.3+. Linking against the
+            // main target instead leaves the symbols unresolved at runtime
+            // and the IDFA / ATT calls silently no-op.
+            var frameworkTarget = pbx.GetUnityFrameworkTargetGuid();
+
+            pbx.AddFrameworkToProject(frameworkTarget, "AdSupport.framework", weak: false);
+            pbx.AddFrameworkToProject(frameworkTarget, "AppTrackingTransparency.framework", weak: true);
+
+            pbx.WriteToFile(pbxPath);
+#endif
+        }
+
+        // Reads the iOS-target define list specifically — the post-processor
+        // mutates iOS build output regardless of which target the editor is
+        // currently focused on.
+        private static bool AttributionDefineEnabled()
+        {
+            var defines = PlayerSettings.GetScriptingDefineSymbolsForGroup(BuildTargetGroup.iOS) ?? string.Empty;
+            foreach (var define in defines.Split(';'))
+            {
+                if (define.Trim() == iOSInfoPlistPostProcessor.AttributionDefine) return true;
+            }
+            return false;
+        }
+    }
+}

src/Packages/Audience/Editor/iOSFrameworkPostProcessor.cs.meta

@@ -53,6 +53,16 @@ public static class ImmutableAudience
         // Set by the Unity layer; null in pure-C# environments.
         internal static volatile Func<bool?>? MobileAttributionProvider;
 
+        // Called during Init when config.EnableMobileAttribution is true.
+        // Returns iOS attribution context (attStatus, idfa) to merge into
+        // game_launch properties. Set by the Unity layer.
+        internal static volatile Func<IReadOnlyDictionary<string, object>?>? MobileAttributionContextProvider;
+
+        // Backs RequestTrackingAuthorizationAsync. Set by the Unity layer to
+        // ATTBridge.RequestAsync; null in pure-C# environments and on
+        // non-iOS platforms (the public API resolves to NotDetermined).
+        internal static volatile Func<Task<int>>? TrackingAuthorizationRequestProvider;
+
         // Active session. Created at Init (or on upgrade from None) and disposed
         // on Shutdown or SetConsent(None). Volatile so OnPause/OnResume see
         // assignments from SetConsent without taking _initLock.
@@ -210,13 +220,17 @@ public static void Init(AudienceConfig config)
             sessionToStart?.Start();
 
             bool? skanRegistered = null;
+            IReadOnlyDictionary<string, object>? attributionContext = null;
             if (config.EnableMobileAttribution)
             {
                 try { skanRegistered = MobileAttributionProvider?.Invoke(); }
                 catch (Exception ex) { Log.Warn(AudienceLogs.MobileAttributionProviderThrew(ex)); }
+
+                try { attributionContext = MobileAttributionContextProvider?.Invoke(); }
+                catch (Exception ex) { Log.Warn(AudienceLogs.MobileAttributionContextProviderThrew(ex)); }
             }
 
-            FireGameLaunch(config, consentAtInit, skanRegistered);
+            FireGameLaunch(config, consentAtInit, skanRegistered, attributionContext);
         }
 
         // Pause/Resume hooks for the Unity lifecycle bridge.
@@ -677,6 +691,55 @@ private static void SyncConsentToBackend(AudienceConfig config, ConsentLevel lev
             });
         }
 
+        // -----------------------------------------------------------------
+        // Mobile attribution
+        // -----------------------------------------------------------------
+
+        /// <summary>
+        /// Requests the iOS App Tracking Transparency authorization. Triggers
+        /// the system prompt on first call; returns the cached status on
+        /// subsequent calls.
+        /// </summary>
+        /// <remarks>
+        /// Studios decide when to show the prompt — Apple's HIG requires it
+        /// to fire at a moment that makes the value to the player obvious,
+        /// not at SDK Init. Resolves to
+        /// <see cref="TrackingAuthorizationStatus.NotDetermined"/> on
+        /// non-iOS platforms and on iOS &lt; 14. The IDFA, when authorized,
+        /// is collected automatically on the next
+        /// <see cref="ImmutableAudience.Init"/> via the
+        /// <c>game_launch</c> event when
+        /// <see cref="AudienceConfig.EnableMobileAttribution"/> is set.
+        /// </remarks>
+        /// <returns>
+        /// A task that completes with the user's authorization decision.
+        /// </returns>
+        public static async Task<TrackingAuthorizationStatus> RequestTrackingAuthorizationAsync()
+        {
+            var provider = TrackingAuthorizationRequestProvider;
+            if (provider == null)
+                return TrackingAuthorizationStatus.NotDetermined;
+
+            int status;
+            try
+            {
+                status = await provider().ConfigureAwait(false);
+            }
+            catch (Exception ex)
+            {
+                Log.Warn(AudienceLogs.TrackingAuthorizationRequestThrew(ex));
+                return TrackingAuthorizationStatus.NotDetermined;
+            }
+
+            // Defensively clamp: any value outside Apple's documented range
+            // (0..3) is surfaced as NotDetermined rather than as an invalid
+            // enum cast that callers can't pattern-match safely.
+            if (status < 0 || status > 3)
+                return TrackingAuthorizationStatus.NotDetermined;
+
+            return (TrackingAuthorizationStatus)status;
+        }
+
         // -----------------------------------------------------------------
         // Flush / Shutdown
         // -----------------------------------------------------------------
@@ -994,7 +1057,11 @@ private static void RescheduleSendTimer(HttpTransport transport)
         }
 
         // consentAtInit only gates the launch; Track still checks live _state via CanTrack.
-        private static void FireGameLaunch(AudienceConfig config, ConsentLevel consentAtInit, bool? skanRegistered = null)
+        private static void FireGameLaunch(
+            AudienceConfig config,
+            ConsentLevel consentAtInit,
+            bool? skanRegistered = null,
+            IReadOnlyDictionary<string, object>? attributionContext = null)
         {
             if (!consentAtInit.CanTrack()) return;
 
@@ -1027,6 +1094,14 @@ private static void FireGameLaunch(AudienceConfig config, ConsentLevel consentAt
             if (skanRegistered == true)
                 properties["skanRegistered"] = true;
 
+            // iOS ATT/IDFA snapshot — merged after Unity context so attribution
+            // keys are authoritative if both sources happen to set the same key.
+            if (attributionContext != null)
+            {
+                foreach (var kvp in attributionContext)
+                    properties[kvp.Key] = kvp.Value;
+            }
+
             // No sessionId on game_launch per Event Reference. Pipeline correlates
             // via eventTimestamp with the session_start that fires just before.
             Track("game_launch", properties.Count > 0 ? properties : null);