feat(audience-sdk): add Android Play Install Referrer support (SDK-310)

Captures the Google Play install referrer via the vendored
installreferrer-2.2 AAR and ships it as a dedicated install_referrer_received
event (decoupled from game_launch). The async fetch typically completes
after the first Init has fired, so the event lands on the next launch
from the on-disk cache; an idempotency marker ensures it fires exactly
once per install.

Both the build-time AUDIENCE_MOBILE_ATTRIBUTION scripting define and the
runtime AudienceConfig.EnableMobileAttribution flag must be set for the
fetch to run. The Init-time consent gate blocks the network call when
consent is None, regardless of the flag.

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

Author: nattb8

src/Packages/Audience/README.md

@@ -47,6 +47,18 @@ Press Play; `ImmutableAudience.Initialized` returns `true` and `AnonymousId` bec
 - Integration guide and API reference: <https://docs.immutable.com/docs/products/audience/unity-sdk>
 - Sample Unity project: [`examples/audience`](https://github.com/immutable/unity-immutable-sdk/tree/main/examples/audience)
 
+## Vendored dependencies
+
+The package vendors prebuilt third-party AARs for mobile attribution. They are only included in your build when the corresponding scripting define is set; without the define they're stripped via `defineConstraints` on the plugin meta files.
+
+| File | Version | Source | Required define |
+| --- | --- | --- | --- |
+| `Runtime/Plugins/Android/installreferrer-2.2.aar` | 2.2 | [maven.google.com](https://maven.google.com/web/index.html#com.android.installreferrer:installreferrer:2.2) | `AUDIENCE_MOBILE_ATTRIBUTION` |
+
+`Runtime/Plugins/Android/proguard-user.txt` ships explicit R8 keep rules for the Install Referrer Library. Unity's gradle build merges it automatically when the AAR is included.
+
+Before tagging a release, check `maven.google.com` for newer versions of any vendored dependency and bump the pinned filename if needed.
+
 ## License
 
 See the repository [LICENSE](https://github.com/immutable/unity-immutable-sdk/blob/main/LICENSE.md).

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

@@ -8,6 +8,8 @@ internal static class AudiencePaths
         private const string IdentityFileName = "identity";
         private const string ConsentFileName = "consent";
         private const string QueueDirName = "queue";
+        private const string InstallReferrerFileName = "install_referrer";
+        private const string InstallReferrerSentFileName = "install_referrer_sent";
 
         internal static string AudienceDir(string persistentDataPath) =>
             Path.Combine(persistentDataPath, RootDirName);
@@ -20,5 +22,11 @@ internal static string ConsentFile(string persistentDataPath) =>
 
         internal static string QueueDir(string persistentDataPath) =>
             Path.Combine(AudienceDir(persistentDataPath), QueueDirName);
+
+        internal static string InstallReferrerFile(string persistentDataPath) =>
+            Path.Combine(AudienceDir(persistentDataPath), InstallReferrerFileName);
+
+        internal static string InstallReferrerSentFile(string persistentDataPath) =>
+            Path.Combine(AudienceDir(persistentDataPath), InstallReferrerSentFileName);
     }
 }

src/Packages/Audience/Runtime/ImmutableAudience.cs

@@ -63,6 +63,13 @@ public static class ImmutableAudience
         // non-iOS platforms (the public API resolves to NotDetermined).
         internal static volatile Func<Task<int>>? TrackingAuthorizationRequestProvider;
 
+        // Called during Init when config.EnableMobileAttribution is true.
+        // Returns the cached Android Play Install Referrer string, or null if
+        // not yet cached (first launch, async fetch may complete after
+        // game_launch fires) or none exists for this install. Set by the Unity
+        // layer; null in pure-C# environments and on non-Android platforms.
+        internal static volatile Func<string?>? MobileInstallReferrerProvider;
+
         // 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.
@@ -220,22 +227,35 @@ public static void Init(AudienceConfig config)
             sessionToStart?.Start();
 
             // Consent gate before invoking attribution providers: SKAN
-            // registration is a network side effect and IDFA / ATT status
-            // reads are privacy-sensitive. CanTrack() == false (consent
-            // None) means we have no licence to do either, regardless of
-            // whether EnableMobileAttribution is set in config.
+            // registration and Install Referrer fetch are network side
+            // effects, and IDFA / ATT status reads are privacy-sensitive.
+            // CanTrack() == false (consent None) means we have no licence
+            // to run any of them, regardless of whether EnableMobileAttribution
+            // is set in config.
             bool? skanRegistered = null;
             IReadOnlyDictionary<string, object>? attributionContext = null;
+            string? installReferrer = null;
             if (config.EnableMobileAttribution && consentAtInit.CanTrack())
             {
                 try { skanRegistered = MobileAttributionProvider?.Invoke(); }
                 catch (Exception ex) { Log.Warn(AudienceLogs.MobileAttributionProviderThrew(ex)); }
 
                 try { attributionContext = MobileAttributionContextProvider?.Invoke(); }
                 catch (Exception ex) { Log.Warn(AudienceLogs.MobileAttributionContextProviderThrew(ex)); }
+
+                try { installReferrer = MobileInstallReferrerProvider?.Invoke(); }
+                catch (Exception ex) { Log.Warn(AudienceLogs.MobileInstallReferrerProviderThrew(ex)); }
             }
 
             FireGameLaunch(config, consentAtInit, skanRegistered, attributionContext);
+
+            // Fires once per install. installReferrer lands asynchronously
+            // from Google Play Services; on the first launch the cache is
+            // usually still empty when game_launch fires, so we ship a
+            // dedicated event after Init when the value first becomes
+            // observable. Idempotent across launches via an on-disk marker.
+            if (!string.IsNullOrEmpty(installReferrer))
+                FireInstallReferrerReceivedOnce(config, installReferrer!);
         }
 
         // Pause/Resume hooks for the Unity lifecycle bridge.
@@ -1120,5 +1140,36 @@ private static void FireGameLaunch(
             // via eventTimestamp with the session_start that fires just before.
             Track("game_launch", properties.Count > 0 ? properties : null);
         }
+
+        // Fires install_referrer_received exactly once per install. Cache
+        // file presence alone isn't enough — on first launch the bridge may
+        // write the cache after Init has already run, so the event must be
+        // dispatched at the next Init that observes a cache hit. The on-disk
+        // "sent" marker provides idempotency across that boundary.
+        private static void FireInstallReferrerReceivedOnce(AudienceConfig config, string installReferrer)
+        {
+            var sentFile = AudiencePaths.InstallReferrerSentFile(config.PersistentDataPath!);
+            if (File.Exists(sentFile)) return;
+
+            Track("install_referrer_received", new Dictionary<string, object>
+            {
+                ["installReferrer"] = installReferrer,
+            });
+
+            try
+            {
+                var dir = Path.GetDirectoryName(sentFile);
+                if (!string.IsNullOrEmpty(dir) && !Directory.Exists(dir))
+                    Directory.CreateDirectory(dir);
+                File.WriteAllText(sentFile, string.Empty);
+            }
+            catch (Exception ex) when (ex is IOException || ex is UnauthorizedAccessException)
+            {
+                // Marker write failed — the event will re-fire on the next
+                // launch. Pipeline-side dedup or the cost of one duplicate is
+                // less bad than never sending the event at all.
+                Log.Warn(AudienceLogs.InstallReferrerSentMarkerWriteFailed(ex));
+            }
+        }
     }
 }

src/Packages/Audience/Runtime/Plugins/Android.meta

@@ -0,0 +1,11 @@
+# Keep Google Play Install Referrer Library symbols.
+#
+# The AAR (installreferrer-2.2.aar) ships consumer rules in
+# META-INF/com.android.tools/proguard/proguard.txt and Unity's gradle build
+# auto-merges them, but R8 fullMode in Unity 2022.3+ has been observed to
+# discard merged consumer rules in some studio configurations. These
+# explicit rules are defensive: they ensure the JNI surface
+# (InstallReferrerClient, ReferrerDetails, the listener interface) survives
+# minification regardless of fullMode behaviour.
+-keep class com.android.installreferrer.** { *; }
+-keep interface com.android.installreferrer.** { *; }

src/Packages/Audience/Runtime/Plugins/Android/installreferrer-2.2.aar

@@ -9,6 +9,12 @@ namespace Immutable.Audience.Unity
 {
     internal static class AudienceUnityHooks
     {
+        // Captured at SubsystemRegistration so the Install Referrer provider
+        // (called from ImmutableAudience.Init on whatever thread the user
+        // invokes it from) can read it without touching
+        // Application.persistentDataPath off the main thread.
+        private static string? _persistentDataPath;
+
         [RuntimeInitializeOnLoadMethod(RuntimeInitializeLoadType.SubsystemRegistration)]
         private static void Install()
         {
@@ -18,6 +24,7 @@ private static void Install()
             Application.quitting -= ImmutableAudience.Shutdown;
             Application.quitting += ImmutableAudience.Shutdown;
 
+            _persistentDataPath = Application.persistentDataPath;
             ImmutableAudience.DefaultPersistentDataPathProvider = () => Application.persistentDataPath;
 
             // Captured once on main thread; ReadOnlyDictionary blocks downstream mutation.
@@ -34,9 +41,27 @@ private static void Install()
             ImmutableAudience.TrackingAuthorizationRequestProvider = () => ATTBridge.RequestAsync();
 #endif
 
+#if UNITY_ANDROID && !UNITY_EDITOR
+            ImmutableAudience.MobileInstallReferrerProvider = ProvideInstallReferrer;
+#endif
+
             UnityLifecycleBridge.EnsureExists();
 
             if (Log.Writer == null) Log.Writer = Debug.Log;
         }
+
+        // Warms the install referrer cache for the next launch and returns
+        // the currently cached value if any. Returns null on first launch
+        // (cache miss while async fetch is in flight) or when the device
+        // reports no referrer for this install. Exceptions propagate to
+        // ImmutableAudience.Init's MobileInstallReferrerProviderThrew handler.
+        private static string? ProvideInstallReferrer()
+        {
+            var path = _persistentDataPath;
+            if (string.IsNullOrEmpty(path)) return null;
+
+            InstallReferrerBridge.EnsureFetchStarted(path!);
+            return InstallReferrerBridge.GetCachedInstallReferrer(path!);
+        }
     }
 }