From efd5005f873e701c6a44dc96f01653078d1c3645 Mon Sep 17 00:00:00 2001
From: Natalie Bunduwongse <natalie.bunduwongse@immutable.com>
Date: Tue, 29 Sep 2026 12:12:14 +1300
Subject: [PATCH] feat(audience): add opt-in exception capture

Adds ErrorTrackingConfig.CaptureExceptions, off by default. When set,
the SDK listens for uncaught C# exceptions via Unity's
logMessageReceivedThreaded and sends them as an exception_captured
event through the existing Track pipeline.

Rate limited per exception type via a token bucket (burst 20, refills
1 every 10s), not one shared counter, so a repeating exception can't
flood the queue or crowd out a different, unrelated one. Matches how
PostHog's client-side exception rate limiter is designed.

Adds a Capture Exceptions toggle and a Throw Test Exception button to
the sample app's Setup tab, plus PlayMode E2E coverage confirming the
event queues when enabled and doesn't when disabled.

No native crash capture (segfaults, ANRs). Managed exceptions only.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
---
 .../SampleApp/Resources/AudienceSample.uxml   |   9 ++
 .../SampleApp/Scripts/AudienceSample.UI.cs    |  25 +++-
 .../SampleApp/Scripts/AudienceSample.cs       |  12 ++
 .../Tests/Runtime/SampleAppLiveFireTests.cs   |  44 ++++++
 .../SampleApp/Tests/Runtime/SampleAppUi.cs    |   3 +
 .../Audience/Runtime/AudienceConfig.cs        |   6 +
 .../Audience/Runtime/Core/Constants.cs        |   3 +
 .../Runtime/Core/ExceptionRateLimiter.cs      |  95 +++++++++++++
 .../Runtime/Core/ExceptionRateLimiter.cs.meta |  11 ++
 .../Audience/Runtime/ErrorTrackingConfig.cs   |  22 +++
 .../Runtime/ErrorTrackingConfig.cs.meta       |  11 ++
 .../Audience/Runtime/Events/ReservedEvents.cs |   1 +
 .../Audience/Runtime/ImmutableAudience.cs     |  28 ++++
 .../Runtime/Unity/AudienceUnityHooks.cs       |  17 +++
 src/Packages/Audience/Runtime/Utility/Log.cs  |   6 +
 .../Runtime/Core/ExceptionRateLimiterTests.cs | 106 ++++++++++++++
 .../Core/ExceptionRateLimiterTests.cs.meta    |  11 ++
 .../Tests/Runtime/ImmutableAudienceTests.cs   | 133 ++++++++++++++++++
 18 files changed, 539 insertions(+), 4 deletions(-)
 create mode 100644 src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs
 create mode 100644 src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs.meta
 create mode 100644 src/Packages/Audience/Runtime/ErrorTrackingConfig.cs
 create mode 100644 src/Packages/Audience/Runtime/ErrorTrackingConfig.cs.meta
 create mode 100644 src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs
 create mode 100644 src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs.meta

diff --git a/examples/audience/Assets/SampleApp/Resources/AudienceSample.uxml b/examples/audience/Assets/SampleApp/Resources/AudienceSample.uxml
index 3c7182b9..e80f7fe5 100644
--- a/examples/audience/Assets/SampleApp/Resources/AudienceSample.uxml
+++ b/examples/audience/Assets/SampleApp/Resources/AudienceSample.uxml
@@ -102,6 +102,15 @@
                                      text="Tags all outbound events with test: true so the backend can filter them from production analytics." />
                         </ui:VisualElement>
 
+                        <ui:VisualElement class="field">
+                            <ui:Toggle name="capture-exceptions" label="CAPTURE EXCEPTIONS" />
+                            <ui:Label class="helper-text below-field"
+                                     text="Send uncaught C# exceptions as exception_captured events." />
+                            <ui:VisualElement class="actions last">
+                                <ui:Button name="btn-throw-test-exception" text="Throw Test Exception" />
+                            </ui:VisualElement>
+                        </ui:VisualElement>
+
                         <ui:VisualElement name="mobile-attribution-field" class="field">
                             <ui:Toggle name="enable-mobile-attribution" label="MOBILE ATTRIBUTION" />
                             <ui:Label class="helper-text below-field"
diff --git a/examples/audience/Assets/SampleApp/Scripts/AudienceSample.UI.cs b/examples/audience/Assets/SampleApp/Scripts/AudienceSample.UI.cs
index 65962613..0e5198f3 100644
--- a/examples/audience/Assets/SampleApp/Scripts/AudienceSample.UI.cs
+++ b/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 Toggle _testMode;
         private DropdownField _initialConsent;
-        private Toggle _debug, _enableMobileAttribution;
+        private Toggle _debug, _enableMobileAttribution, _captureExceptions;
         private Button _btnInit, _btnFlush, _btnReset, _btnShutdown, _btnRequestAtt;
 
         // ---- UXML element fields (Consent tab) ----
@@ -64,7 +64,7 @@ private static readonly (string TabId, string PanelId)[] Tabs =
 
         private VisualElement _typedEventsHost;
         private TextField _customEventName, _customEventProps;
-        private Button _btnCustomEvent;
+        private Button _btnCustomEvent, _btnThrowTestException;
 
         // ---- UXML element fields (Identity tab) ----
 
@@ -184,10 +184,11 @@ private void BindElements()
             _debug                    = Require<Toggle>("debug");
             _testMode                 = Require<Toggle>("test-mode");
             _enableMobileAttribution  = Require<Toggle>("enable-mobile-attribution");
+            _captureExceptions        = Require<Toggle>("capture-exceptions");
             // Inject a tick Label — Unity 2021.3 runtime panels render the
             // checked state as a plain coloured square otherwise. USS hides
             // the tick when unchecked.
-            foreach (var toggle in new[] { _debug, _testMode, _enableMobileAttribution })
+            foreach (var toggle in new[] { _debug, _testMode, _enableMobileAttribution, _captureExceptions })
             {
                 var checkmark = toggle.Q<VisualElement>(className: "unity-toggle__checkmark");
                 if (checkmark == null) continue;
@@ -218,6 +219,7 @@ private void BindElements()
             _customEventName  = Require<TextField>("custom-event-name");
             _customEventProps = Require<TextField>("custom-event-props");
             _btnCustomEvent   = Require<Button>("btn-custom-event");
+            _btnThrowTestException = Require<Button>("btn-throw-test-exception");
 
             _identityUserId       = Require<Label>("identity-user-id");
             _identityIdentityType = Require<Label>("identity-identity-type");
@@ -327,6 +329,7 @@ private void RegisterHandlers()
             _initialConsent.RegisterValueChangedCallback(_ => RefreshStatusBar());
             _baseUrl.RegisterValueChangedCallback(_ => RefreshStatusBar());
             _enableMobileAttribution.RegisterValueChangedCallback(_ => UpdateAttButtonGate());
+            _captureExceptions.RegisterValueChangedCallback(_ => UpdateThrowTestExceptionButtonGate());
 
             _btnInit.clicked += OnInit;
 
@@ -338,6 +341,7 @@ private void RegisterHandlers()
             _btnIdentifyTraits.clicked += OnIdentifyTraits;
             _btnAlias.clicked += OnAlias;
             _btnCustomEvent.clicked += OnSendCustomEvent;
+            _btnThrowTestException.clicked += OnThrowTestException;
 
             var btnCopyLog = Require<Button>("btn-copy-log");
             btnCopyLog.clicked += () =>
@@ -640,6 +644,7 @@ private void RefreshInitState()
             _btnInit.SetEnabled(!_initialised && !string.IsNullOrWhiteSpace(_publishableKey.value));
             _btnAlias.SetEnabled(_initialised && IsAliasReady());
             UpdateAttButtonGate();
+            UpdateThrowTestExceptionButtonGate();
         }
 
         // ATT prompt is independent of SDK init, but in the demo flow it's
@@ -653,6 +658,15 @@ private void UpdateAttButtonGate()
                 _enableMobileAttribution.value);
         }
 
+        // Throwing before Init, or with the toggle off, is a harmless no-op
+        // inside the SDK (CaptureException checks _initialized first), but a
+        // confusing one to test with: the button still reports "Ok" while
+        // quietly capturing nothing.
+        private void UpdateThrowTestExceptionButtonGate()
+        {
+            _btnThrowTestException.SetEnabled(_initialised && _captureExceptions.value);
+        }
+
         private void RefreshIdentityPanel()
         {
             _identityUserId.text       = ImmutableAudience.UserId ?? "—";
@@ -673,10 +687,11 @@ internal readonly struct InitForm
             public readonly bool Debug;
             public readonly bool TestMode;
             public readonly bool EnableMobileAttribution;
+            public readonly bool CaptureExceptions;
             public readonly int? FlushIntervalMs;
             public readonly int? FlushSize;
 
-            public InitForm(string publishableKey, string baseUrl, ConsentLevel consent, bool debug, bool testMode, bool enableMobileAttribution, int? flushIntervalMs, int? flushSize)
+            public InitForm(string publishableKey, string baseUrl, ConsentLevel consent, bool debug, bool testMode, bool enableMobileAttribution, bool captureExceptions, int? flushIntervalMs, int? flushSize)
             {
                 PublishableKey = publishableKey;
                 BaseUrl = baseUrl;
@@ -684,6 +699,7 @@ public InitForm(string publishableKey, string baseUrl, ConsentLevel consent, boo
                 Debug = debug;
                 TestMode = testMode;
                 EnableMobileAttribution = enableMobileAttribution;
+                CaptureExceptions = captureExceptions;
                 FlushIntervalMs = flushIntervalMs;
                 FlushSize = flushSize;
             }
@@ -701,6 +717,7 @@ internal InitForm CaptureInitForm()
                 debug:                   _debug.value,
                 testMode:                _testMode.value,
                 enableMobileAttribution: _enableMobileAttribution.value,
+                captureExceptions:       _captureExceptions.value,
                 flushIntervalMs:         flushIntervalMs,
                 flushSize:               flushSize);
         }
diff --git a/examples/audience/Assets/SampleApp/Scripts/AudienceSample.cs b/examples/audience/Assets/SampleApp/Scripts/AudienceSample.cs
index ce493783..efb8aaef 100644
--- a/examples/audience/Assets/SampleApp/Scripts/AudienceSample.cs
+++ b/examples/audience/Assets/SampleApp/Scripts/AudienceSample.cs
@@ -156,6 +156,16 @@ private void OnSendCustomEvent() => RunAndLog("track()", () =>
             return Json.Serialize(echo, 2);
         });
 
+        // Logs a fake exception so exception capture (when enabled on the
+        // Setup tab) has something to pick up. Debug.LogException reaches
+        // Unity's LogType.Exception channel the same way a real uncaught
+        // exception would, without actually crashing anything.
+        private void OnThrowTestException() => RunAndLog("throwTestException()", () =>
+        {
+            Debug.LogException(new Exception("Sample app test exception"));
+            return "Logged a test exception via Debug.LogException.";
+        });
+
         // ---- SDK action handlers: consent ----
 
         // None clears the anonymous ID and stops future collection; already-queued
@@ -333,6 +343,7 @@ private AudienceConfig BuildAudienceConfig(InitForm form, Action<AudienceError>
                 Debug                   = form.Debug,
                 TestMode                = form.TestMode,
                 EnableMobileAttribution = form.EnableMobileAttribution,
+                ErrorTracking           = new ErrorTrackingConfig { CaptureExceptions = form.CaptureExceptions },
                 OnError                 = onError,
             };
             if (form.FlushIntervalMs is int flushMs && flushMs > 0)
@@ -356,6 +367,7 @@ private static Dictionary<string, object> BuildConfigEcho(AudienceConfig config)
                 ["debug"]                    = config.Debug,
                 ["testMode"]                 = config.TestMode,
                 ["enableMobileAttribution"]  = config.EnableMobileAttribution,
+                ["captureExceptions"]        = config.ErrorTracking?.CaptureExceptions ?? false,
                 ["flushIntervalSeconds"]     = config.FlushIntervalSeconds,
                 ["flushSize"]                = config.FlushSize,
                 ["shutdownFlushTimeoutMs"]   = config.ShutdownFlushTimeoutMs,
diff --git a/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppLiveFireTests.cs b/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppLiveFireTests.cs
index 3a9ef544..650f9682 100644
--- a/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppLiveFireTests.cs
+++ b/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppLiveFireTests.cs
@@ -349,6 +349,50 @@ public IEnumerator CustomTrack_WithDictionaryProps_FlushReportsOk()
             yield return FlushAndAssertNoErrors();
         }
 
+        [UnityTest]
+        public IEnumerator ExceptionCapture_WhenEnabled_QueuesEventAndFlushReportsOk()
+        {
+            yield return LoadAndInit(configure: root =>
+            {
+                root.Q<Toggle>(SampleAppUi.Setup.CaptureExceptions).value = true;
+            });
+
+            var queueLabel = _root!.Q<Label>(SampleAppUi.StatusBar.Queue);
+            int.TryParse(queueLabel.text, out var baseline);
+
+            // ignoreFailingMessages doesn't cover LogType.Exception; must be declared expected here.
+            LogAssert.Expect(LogType.Exception, "Exception: Sample app test exception");
+            _root.Q<Button>(SampleAppUi.Buttons.ThrowTestException).Click();
+            yield return SampleAppTestHelpers.WaitForLogEntry(_root, SampleAppUi.LogLabels.ThrowTestException, LogLevels.Ok, 5f);
+
+            yield return SampleAppTestHelpers.WaitForCondition(
+                () => int.TryParse(queueLabel.text, out var current) && current > baseline,
+                2f, "queue size to grow after throwing a test exception with capture enabled");
+
+            yield return FlushAndAssertNoErrors("exception capture enabled");
+        }
+
+        [UnityTest]
+        public IEnumerator ExceptionCapture_WhenDisabled_DoesNotQueueEvent()
+        {
+            // capture-exceptions defaults to off; LoadAndInit leaves it untouched.
+            yield return LoadAndInit();
+
+            var queueLabel = _root!.Q<Label>(SampleAppUi.StatusBar.Queue);
+            int.TryParse(queueLabel.text, out var baseline);
+
+            LogAssert.Expect(LogType.Exception, "Exception: Sample app test exception");
+            _root.Q<Button>(SampleAppUi.Buttons.ThrowTestException).Click();
+            yield return SampleAppTestHelpers.WaitForLogEntry(_root, SampleAppUi.LogLabels.ThrowTestException, LogLevels.Ok, 5f);
+            yield return null;
+
+            int.TryParse(queueLabel.text, out var afterThrow);
+            Assert.AreEqual(baseline, afterThrow,
+                "queue size must not grow from a thrown exception when capture is disabled");
+
+            yield return FlushAndAssertNoErrors("exception capture disabled");
+        }
+
         // ---- Lifecycle / control-plane tests ----
 
         [UnityTest]
diff --git a/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppUi.cs b/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppUi.cs
index 4b7aae03..cf60ac19 100644
--- a/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppUi.cs
+++ b/examples/audience/Assets/SampleApp/Tests/Runtime/SampleAppUi.cs
@@ -44,6 +44,7 @@ internal static class Setup
             internal const string TestMode = "test-mode";
             internal const string FlushInterval = "flush-interval";
             internal const string FlushSize = "flush-size";
+            internal const string CaptureExceptions = "capture-exceptions";
         }
 
         internal static class Buttons
@@ -56,6 +57,7 @@ internal static class Buttons
             internal const string ConsentAnon = "btn-consent-anon";
             internal const string ConsentFull = "btn-consent-full";
             internal const string CustomEvent = "btn-custom-event";
+            internal const string ThrowTestException = "btn-throw-test-exception";
             internal const string Identify = "btn-identify";
             internal const string IdentifyTraits = "btn-identify-traits";
             internal const string Alias = "btn-alias";
@@ -152,6 +154,7 @@ internal static class LogLabels
             internal const string Identify = "identify()";
             internal const string IdentifyTraits = "identify(traits)";
             internal const string Alias = "alias()";
+            internal const string ThrowTestException = "throwTestException()";
 
             // Label AudienceSample.cs.RouteSdkLogToPane gives every mirrored SDK log line.
             internal const string Sdk = "sdk";
diff --git a/src/Packages/Audience/Runtime/AudienceConfig.cs b/src/Packages/Audience/Runtime/AudienceConfig.cs
index a420092d..a262916d 100644
--- a/src/Packages/Audience/Runtime/AudienceConfig.cs
+++ b/src/Packages/Audience/Runtime/AudienceConfig.cs
@@ -90,6 +90,12 @@ public class AudienceConfig
         /// </remarks>
         public string[]? SKAdNetworkIds { get; set; }
 
+        /// <summary>
+        /// Opts into sending uncaught C# exceptions as events. Null (the
+        /// default) disables capture entirely.
+        /// </summary>
+        public ErrorTrackingConfig? ErrorTracking { get; set; }
+
         /// <summary>
         /// Interval between automatic flushes to the backend, in seconds.
         /// </summary>
diff --git a/src/Packages/Audience/Runtime/Core/Constants.cs b/src/Packages/Audience/Runtime/Core/Constants.cs
index be72592e..99d1299b 100644
--- a/src/Packages/Audience/Runtime/Core/Constants.cs
+++ b/src/Packages/Audience/Runtime/Core/Constants.cs
@@ -16,6 +16,9 @@ internal static class Constants
         internal const int MaxClockSkewFutureHours = 24; // Backend rejects eventTimestamp further ahead than this.
         internal const int MaxFieldLength = 256; // Backend schema limit.
         internal const int ControlPlaneRequestTimeoutSeconds = 30;
+        // See ExceptionRateLimiter for how these two are used.
+        internal const int MaxCapturedExceptions = 20;
+        internal const int ExceptionCaptureRefillSeconds = 10;
 
         internal const string LibraryName = "com.immutable.audience";
         internal const string LibraryVersion = "0.7.3";
diff --git a/src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs b/src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs
new file mode 100644
index 00000000..2df8651d
--- /dev/null
+++ b/src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs
@@ -0,0 +1,95 @@
+#nullable enable
+
+using System;
+using System.Collections.Generic;
+
+namespace Immutable.Audience
+{
+    /// <summary>
+    /// Per-exception-type token bucket. Keeps one repeating exception from
+    /// flooding the event queue without silencing a different, unrelated one.
+    /// </summary>
+    /// <remarks>
+    /// Each exception type gets its own bucket, starting full. A capture
+    /// spends one token; the bucket refills by one token per
+    /// <c>refillInterval</c>, capped at <c>capacity</c>. A type that keeps
+    /// recurring settles into a steady trickle instead of going silent
+    /// once, or drowning out a different type sharing one global count.
+    /// </remarks>
+    internal sealed class ExceptionRateLimiter
+    {
+        private readonly int _capacity;
+        private readonly TimeSpan _refillInterval;
+        private readonly Func<DateTime> _now;
+        private readonly Dictionary<string, Bucket> _buckets = new Dictionary<string, Bucket>();
+        private readonly object _lock = new object();
+
+        internal ExceptionRateLimiter(int capacity, TimeSpan refillInterval, Func<DateTime>? now = null)
+        {
+            _capacity = capacity;
+            _refillInterval = refillInterval;
+            _now = now ?? (() => DateTime.UtcNow);
+        }
+
+        /// <summary>
+        /// Attempts to spend one token for <paramref name="exceptionType"/>.
+        /// </summary>
+        /// <returns>
+        /// <c>allowed</c>: true if a token was spent and the caller should proceed.
+        /// <c>firstTimeLimited</c>: true the moment this type's bucket runs out,
+        /// so the caller can log a warning once per exhaustion episode rather
+        /// than once per dropped exception.
+        /// </returns>
+        internal (bool allowed, bool firstTimeLimited) TryConsume(string exceptionType)
+        {
+            var now = _now();
+            lock (_lock)
+            {
+                if (!_buckets.TryGetValue(exceptionType, out var bucket))
+                {
+                    bucket = new Bucket { Tokens = _capacity, LastRefill = now };
+                    _buckets[exceptionType] = bucket;
+                }
+                else
+                {
+                    Refill(bucket, now);
+                }
+
+                if (bucket.Tokens < 1)
+                {
+                    var firstTimeLimited = !bucket.HasWarned;
+                    bucket.HasWarned = true;
+                    return (false, firstTimeLimited);
+                }
+
+                bucket.Tokens -= 1;
+                bucket.HasWarned = false;
+                return (true, false);
+            }
+        }
+
+        private void Refill(Bucket bucket, DateTime now)
+        {
+            var elapsed = now - bucket.LastRefill;
+            if (elapsed <= TimeSpan.Zero) return;
+
+            var tokensToAdd = elapsed.Ticks / (double)_refillInterval.Ticks;
+            if (tokensToAdd <= 0) return;
+
+            bucket.Tokens = Math.Min(_capacity, bucket.Tokens + tokensToAdd);
+            bucket.LastRefill = now;
+        }
+
+        internal void Reset()
+        {
+            lock (_lock) { _buckets.Clear(); }
+        }
+
+        private sealed class Bucket
+        {
+            internal double Tokens;
+            internal DateTime LastRefill;
+            internal bool HasWarned;
+        }
+    }
+}
diff --git a/src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs.meta b/src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs.meta
new file mode 100644
index 00000000..94d9a83c
--- /dev/null
+++ b/src/Packages/Audience/Runtime/Core/ExceptionRateLimiter.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 376350eba87ab429193b17eb072c0d0a
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
diff --git a/src/Packages/Audience/Runtime/ErrorTrackingConfig.cs b/src/Packages/Audience/Runtime/ErrorTrackingConfig.cs
new file mode 100644
index 00000000..77d95afe
--- /dev/null
+++ b/src/Packages/Audience/Runtime/ErrorTrackingConfig.cs
@@ -0,0 +1,22 @@
+#nullable enable
+
+namespace Immutable.Audience
+{
+    /// <summary>
+    /// Exception-capture settings passed to <see cref="ImmutableAudience.Init"/>
+    /// via <see cref="AudienceConfig.ErrorTracking"/>.
+    /// </summary>
+    public class ErrorTrackingConfig
+    {
+        /// <summary>
+        /// Opts into sending uncaught C# exceptions as <c>exception_captured</c>
+        /// events. Default <c>false</c>.
+        /// </summary>
+        /// <remarks>
+        /// Managed exceptions only. Native crashes (segfaults, ANRs) are not
+        /// covered. Capture is capped per run so a repeating exception can't
+        /// flood the event queue.
+        /// </remarks>
+        public bool CaptureExceptions { get; set; } = false;
+    }
+}
diff --git a/src/Packages/Audience/Runtime/ErrorTrackingConfig.cs.meta b/src/Packages/Audience/Runtime/ErrorTrackingConfig.cs.meta
new file mode 100644
index 00000000..c541fce6
--- /dev/null
+++ b/src/Packages/Audience/Runtime/ErrorTrackingConfig.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: 66bd5c440c03b4138a502638bef1c9d8
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
diff --git a/src/Packages/Audience/Runtime/Events/ReservedEvents.cs b/src/Packages/Audience/Runtime/Events/ReservedEvents.cs
index 91bf8583..e8fefe95 100644
--- a/src/Packages/Audience/Runtime/Events/ReservedEvents.cs
+++ b/src/Packages/Audience/Runtime/Events/ReservedEvents.cs
@@ -22,6 +22,7 @@ internal static class ReservedEvents
                 ["resource"] = new[] { "flow", "currency", "amount" },
                 ["achievement_unlocked"] = new[] { "achievement_id", "achievement_name" },
                 ["milestone_reached"] = new[] { "name" },
+                ["exception_captured"] = new[] { "exception_type", "message", "stack_trace" },
             };
     }
 }
diff --git a/src/Packages/Audience/Runtime/ImmutableAudience.cs b/src/Packages/Audience/Runtime/ImmutableAudience.cs
index 6ddb273e..d77b62d6 100644
--- a/src/Packages/Audience/Runtime/ImmutableAudience.cs
+++ b/src/Packages/Audience/Runtime/ImmutableAudience.cs
@@ -41,6 +41,10 @@ public static class ImmutableAudience
         // Gate against overlapping timer ticks (Timer callbacks run on independent ThreadPool threads).
         private static int _sendInFlight;
 
+        // Mutable, not readonly: tests swap this for one using a fake clock.
+        internal static ExceptionRateLimiter ExceptionRateLimiter =
+            new ExceptionRateLimiter(Constants.MaxCapturedExceptions, TimeSpan.FromSeconds(Constants.ExceptionCaptureRefillSeconds));
+
         // Passport IDs are "<connection>|<id>" (e.g. "email|abc123", "google-oauth2|123")
         // or, for some accounts, a bare UUID with no connection prefix.
         // Not RegexOptions.Compiled: that needs Reflection.Emit, unavailable under IL2CPP/AOT.
@@ -239,6 +243,10 @@ public static void Init(AudienceConfig config)
 
                 _config = config;
                 Log.Enabled = config.Debug;
+                // Shutdown() doesn't touch this, so a reinit after Shutdown must
+                // clear it here or an exhausted bucket from the prior run would
+                // silently carry over.
+                ExceptionRateLimiter.Reset();
                 // Persisted consent overrides the config default (prior downgrade survives restart).
                 var initialLevel = ConsentStore.Load(config.PersistentDataPath) ?? config.Consent;
                 _state = new ConsentState(initialLevel, null, null);
@@ -418,6 +426,25 @@ private static void ValidateReservedEventProperties(string eventName, Dictionary
                 throw new ArgumentException(AudienceLogs.TrackStringMissingRequiredProps(eventName, missing), nameof(properties));
         }
 
+        // Called by the Unity layer for every uncaught C# exception.
+        internal static void CaptureException(string exceptionType, string message, string stackTrace)
+        {
+            if (!_initialized) return;
+            if (_config?.ErrorTracking?.CaptureExceptions != true) return;
+
+            var (allowed, firstTimeLimited) = ExceptionRateLimiter.TryConsume(exceptionType);
+            if (firstTimeLimited)
+                Log.Warn(AudienceLogs.ExceptionCaptureRateLimited(exceptionType, Constants.MaxCapturedExceptions));
+            if (!allowed) return;
+
+            Track("exception_captured", new Dictionary<string, object>
+            {
+                ["exception_type"] = exceptionType,
+                ["message"] = message,
+                ["stack_trace"] = stackTrace,
+            });
+        }
+
         // Shared tail for both Track overloads and TrackFromSession.
         private static void EnqueueTrackedEvent(
             string eventName,
@@ -1006,6 +1033,7 @@ 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;
+                ExceptionRateLimiter.Reset();
                 Identity.ClearCache();
             }
         }
diff --git a/src/Packages/Audience/Runtime/Unity/AudienceUnityHooks.cs b/src/Packages/Audience/Runtime/Unity/AudienceUnityHooks.cs
index 38710f9d..ff0220c3 100644
--- a/src/Packages/Audience/Runtime/Unity/AudienceUnityHooks.cs
+++ b/src/Packages/Audience/Runtime/Unity/AudienceUnityHooks.cs
@@ -28,6 +28,8 @@ private static void Install()
             // Avoid stacked subscriptions on reload.
             Application.quitting -= ImmutableAudience.Shutdown;
             Application.quitting += ImmutableAudience.Shutdown;
+            Application.logMessageReceivedThreaded -= OnLogMessageReceived;
+            Application.logMessageReceivedThreaded += OnLogMessageReceived;
 
             _persistentDataPath = Application.persistentDataPath;
             ImmutableAudience.DefaultPersistentDataPathProvider = () => Application.persistentDataPath;
@@ -83,6 +85,21 @@ private static void Install()
             UnityLifecycleBridge.EnsureExists();
         }
 
+        // Threaded variant: fires from background threads/jobs too, not just main.
+        private static void OnLogMessageReceived(string condition, string stackTrace, LogType type)
+        {
+            if (type != LogType.Exception) return;
+
+            // Unity formats this as "<ExceptionType>: <Message>". Splitting on
+            // the first ": " recovers the type for grouping; a message that
+            // happens to start with ": " just yields an empty type, never a crash.
+            var separatorIndex = condition.IndexOf(": ", StringComparison.Ordinal);
+            var exceptionType = separatorIndex >= 0 ? condition.Substring(0, separatorIndex) : string.Empty;
+            var message = separatorIndex >= 0 ? condition.Substring(separatorIndex + 2) : condition;
+
+            ImmutableAudience.CaptureException(exceptionType, message, stackTrace);
+        }
+
         // 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
diff --git a/src/Packages/Audience/Runtime/Utility/Log.cs b/src/Packages/Audience/Runtime/Utility/Log.cs
index 79e78e77..8f28a9cb 100644
--- a/src/Packages/Audience/Runtime/Utility/Log.cs
+++ b/src/Packages/Audience/Runtime/Utility/Log.cs
@@ -199,6 +199,12 @@ internal static string GAIDFetchThrew(Exception ex) =>
             $"GAID fetch threw {ex.GetType().Name}: {ex.Message}. " +
             "gaid will not ship on game_launch this session; next launch retries.";
 
+        // ---- Exception capture ----
+
+        internal static string ExceptionCaptureRateLimited(string exceptionType, int max) =>
+            $"\"{exceptionType}\" hit the exception capture rate limit ({max} burst, refilling over time). " +
+            "Further occurrences of this type are dropped until it refills.";
+
         // ---- Identity ----
 
         internal static string IdentityRotateFailed(Exception ex) =>
diff --git a/src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs b/src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs
new file mode 100644
index 00000000..21cec5dc
--- /dev/null
+++ b/src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs
@@ -0,0 +1,106 @@
+#nullable enable
+
+using System;
+using NUnit.Framework;
+
+namespace Immutable.Audience.Tests
+{
+    [TestFixture]
+    internal class ExceptionRateLimiterTests
+    {
+        private DateTime _now;
+
+        private ExceptionRateLimiter MakeLimiter(int capacity = 20, int refillSeconds = 10)
+        {
+            _now = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+            return new ExceptionRateLimiter(capacity, TimeSpan.FromSeconds(refillSeconds), () => _now);
+        }
+
+        [Test]
+        public void TryConsume_BurstUpToCapacity_AllAllowed()
+        {
+            var limiter = MakeLimiter(capacity: 3);
+
+            for (var i = 0; i < 3; i++)
+            {
+                var (allowed, firstTimeLimited) = limiter.TryConsume("Exception");
+                Assert.IsTrue(allowed, $"attempt {i} should be within capacity");
+                Assert.IsFalse(firstTimeLimited);
+            }
+        }
+
+        [Test]
+        public void TryConsume_BeyondCapacity_Dropped()
+        {
+            var limiter = MakeLimiter(capacity: 3);
+            for (var i = 0; i < 3; i++) limiter.TryConsume("Exception");
+
+            var (allowed, firstTimeLimited) = limiter.TryConsume("Exception");
+
+            Assert.IsFalse(allowed);
+            Assert.IsTrue(firstTimeLimited, "the first drop after exhausting the bucket must report firstTimeLimited");
+        }
+
+        [Test]
+        public void TryConsume_FirstTimeLimited_OnlyReportedOnce()
+        {
+            var limiter = MakeLimiter(capacity: 1);
+            limiter.TryConsume("Exception");
+
+            var (_, first) = limiter.TryConsume("Exception");
+            var (_, second) = limiter.TryConsume("Exception");
+
+            Assert.IsTrue(first, "first drop after exhaustion should report firstTimeLimited");
+            Assert.IsFalse(second, "subsequent drops in the same exhaustion episode should not report it again");
+        }
+
+        [Test]
+        public void TryConsume_RefillsOverTime_AllowsOneMore()
+        {
+            var limiter = MakeLimiter(capacity: 1, refillSeconds: 10);
+            limiter.TryConsume("Exception");
+            Assert.IsFalse(limiter.TryConsume("Exception").allowed, "bucket should be empty right after the burst");
+
+            _now = _now.AddSeconds(10);
+
+            Assert.IsTrue(limiter.TryConsume("Exception").allowed, "one refill interval should free exactly one token");
+        }
+
+        [Test]
+        public void TryConsume_DoesNotOverflowPastCapacity()
+        {
+            var limiter = MakeLimiter(capacity: 3, refillSeconds: 10);
+            limiter.TryConsume("Exception");
+
+            _now = _now.AddSeconds(1000); // far more than enough to refill several times over
+
+            for (var i = 0; i < 3; i++)
+                Assert.IsTrue(limiter.TryConsume("Exception").allowed, $"attempt {i} should still be within capacity");
+            Assert.IsFalse(limiter.TryConsume("Exception").allowed, "capacity must not overflow past its max even after a long idle period");
+        }
+
+        [Test]
+        public void TryConsume_DifferentExceptionTypes_HaveIndependentBuckets()
+        {
+            var limiter = MakeLimiter(capacity: 1);
+            limiter.TryConsume("NullReferenceException");
+
+            Assert.IsFalse(limiter.TryConsume("NullReferenceException").allowed,
+                "NullReferenceException's bucket should already be empty");
+            Assert.IsTrue(limiter.TryConsume("ArgumentException").allowed,
+                "a different exception type must have its own, untouched bucket");
+        }
+
+        [Test]
+        public void Reset_ClearsAllBuckets()
+        {
+            var limiter = MakeLimiter(capacity: 1);
+            limiter.TryConsume("Exception");
+            Assert.IsFalse(limiter.TryConsume("Exception").allowed);
+
+            limiter.Reset();
+
+            Assert.IsTrue(limiter.TryConsume("Exception").allowed, "a bucket must start full again after Reset");
+        }
+    }
+}
diff --git a/src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs.meta b/src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs.meta
new file mode 100644
index 00000000..62486a55
--- /dev/null
+++ b/src/Packages/Audience/Tests/Runtime/Core/ExceptionRateLimiterTests.cs.meta
@@ -0,0 +1,11 @@
+fileFormatVersion: 2
+guid: e56e8ba2eaee2442bb34221c20b21c01
+MonoImporter:
+  externalObjects: {}
+  serializedVersion: 2
+  defaultReferences: []
+  executionOrder: 0
+  icon: {instanceID: 0}
+  userData: 
+  assetBundleName: 
+  assetBundleVariant: 
diff --git a/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs b/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs
index 15d0bd37..8731baa7 100644
--- a/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs
+++ b/src/Packages/Audience/Tests/Runtime/ImmutableAudienceTests.cs
@@ -35,6 +35,8 @@ public void TearDown()
             ImmutableAudience.MobileInstallReferrerProvider = null;
             ImmutableAudience.MobileATTStatusProvider = null;
             ImmutableAudience.MobileIDFAProvider = null;
+            ImmutableAudience.ExceptionRateLimiter =
+                new ExceptionRateLimiter(Constants.MaxCapturedExceptions, TimeSpan.FromSeconds(Constants.ExceptionCaptureRefillSeconds));
             Identity.Reset(_testDir);
             if (Directory.Exists(_testDir))
                 Directory.Delete(_testDir, recursive: true);
@@ -2830,5 +2832,136 @@ public void AttStatusChanged_NotFired_WhenEnableMobileAttributionFalse()
                 .Select(File.ReadAllText).ToList();
             Assert.IsFalse(blobs.Any(b => b.Contains("\"tracking_authorization_changed\"")));
         }
+
+        // -----------------------------------------------------------------
+        // CaptureException / exception_captured
+        //
+        // A no-op unless ErrorTracking.CaptureExceptions is set. Rate limited
+        // per exception type via ExceptionRateLimiter.
+        // -----------------------------------------------------------------
+
+        private List<string> ReadQueuedBlobs()
+        {
+            var queueDir = AudiencePaths.QueueDir(_testDir);
+            if (!Directory.Exists(queueDir)) return new List<string>();
+            return Directory.GetFiles(queueDir, "*.json").Select(File.ReadAllText).ToList();
+        }
+
+        [Test]
+        public void CaptureException_Disabled_DoesNotTrack()
+        {
+            ImmutableAudience.Init(MakeConfig(ConsentLevel.Anonymous));
+
+            ImmutableAudience.CaptureException("NullReferenceException", "Object reference not set", "at Foo()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            Assert.IsFalse(ReadQueuedBlobs().Any(b => b.Contains("\"exception_captured\"")));
+        }
+
+        [Test]
+        public void CaptureException_Enabled_SendsEventWithProperties()
+        {
+            var config = MakeConfig(ConsentLevel.Anonymous);
+            config.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(config);
+
+            ImmutableAudience.CaptureException("NullReferenceException", "Object reference not set", "at Foo()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            var blobs = ReadQueuedBlobs();
+            Assert.IsTrue(blobs.Any(b =>
+                b.Contains("\"exception_captured\"") &&
+                b.Contains("NullReferenceException") &&
+                b.Contains("Object reference not set") &&
+                b.Contains("at Foo()")));
+        }
+
+        [Test]
+        public void CaptureException_RespectsConsent_NoneIsANoOp()
+        {
+            var config = MakeConfig(ConsentLevel.None);
+            config.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(config);
+
+            ImmutableAudience.CaptureException("Exception", "boom", "at Foo()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            Assert.IsFalse(ReadQueuedBlobs().Any(b => b.Contains("\"exception_captured\"")));
+        }
+
+        [Test]
+        public void CaptureException_BurstsUpToCapacity_ThenStops()
+        {
+            var config = MakeConfig(ConsentLevel.Anonymous);
+            config.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(config);
+
+            for (var i = 0; i < Constants.MaxCapturedExceptions + 5; i++)
+                ImmutableAudience.CaptureException("Exception", $"boom {i}", "at Foo()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            var captured = ReadQueuedBlobs().Count(b => b.Contains("\"exception_captured\""));
+            Assert.AreEqual(Constants.MaxCapturedExceptions, captured,
+                "a single exception type must stop at its burst capacity even though more kept firing");
+        }
+
+        [Test]
+        public void CaptureException_DifferentTypes_DoNotShareABucket()
+        {
+            var config = MakeConfig(ConsentLevel.Anonymous);
+            config.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(config);
+
+            for (var i = 0; i < Constants.MaxCapturedExceptions; i++)
+                ImmutableAudience.CaptureException("NullReferenceException", $"boom {i}", "at Foo()");
+            ImmutableAudience.CaptureException("ArgumentException", "different bug", "at Bar()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            Assert.IsTrue(ReadQueuedBlobs().Any(b => b.Contains("\"exception_type\":\"ArgumentException\"")),
+                "a different exception type must have its own bucket, unaffected by another type's cap");
+        }
+
+        [Test]
+        public void CaptureException_RefillsOverTime_AllowsMoreOfTheSameType()
+        {
+            var fakeNow = new DateTime(2026, 1, 1, 0, 0, 0, DateTimeKind.Utc);
+            ImmutableAudience.ExceptionRateLimiter =
+                new ExceptionRateLimiter(Constants.MaxCapturedExceptions, TimeSpan.FromSeconds(Constants.ExceptionCaptureRefillSeconds), () => fakeNow);
+
+            var config = MakeConfig(ConsentLevel.Anonymous);
+            config.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(config);
+
+            for (var i = 0; i < Constants.MaxCapturedExceptions; i++)
+                ImmutableAudience.CaptureException("Exception", $"boom {i}", "at Foo()");
+            fakeNow = fakeNow.AddSeconds(Constants.ExceptionCaptureRefillSeconds);
+            ImmutableAudience.CaptureException("Exception", "boom after refill", "at Foo()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            var captured = ReadQueuedBlobs().Count(b => b.Contains("\"exception_captured\""));
+            Assert.AreEqual(Constants.MaxCapturedExceptions + 1, captured,
+                "one refill interval should free exactly one more token for the same type");
+        }
+
+        [Test]
+        public void CaptureException_CapIsResetOnFreshInit()
+        {
+            var config = MakeConfig(ConsentLevel.Anonymous);
+            config.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(config);
+            for (var i = 0; i < Constants.MaxCapturedExceptions; i++)
+                ImmutableAudience.CaptureException("Exception", $"boom {i}", "at Foo()");
+            ImmutableAudience.Shutdown();
+
+            var secondConfig = MakeConfig(ConsentLevel.Anonymous);
+            secondConfig.ErrorTracking = new ErrorTrackingConfig { CaptureExceptions = true };
+            ImmutableAudience.Init(secondConfig);
+            ImmutableAudience.CaptureException("Exception", "boom after restart", "at Foo()");
+            ImmutableAudience.FlushQueueToDiskForTesting();
+
+            Assert.IsTrue(ReadQueuedBlobs().Any(b =>
+                b.Contains("\"exception_captured\"") && b.Contains("boom after restart")),
+                "Init must reset rate limit state left over from a prior run, Shutdown alone does not");
+        }
     }
 }
\ No newline at end of file