feat: add before send callback (#114)

* feat: add before send callback

* test: cover before send edge cases

Author: marandaneto

.changeset/bright-owls-filter.md

@@ -0,0 +1,5 @@
+---
+"com.posthog.unity": minor
+---
+
+Add a beforeSend callback for modifying or dropping fully enriched events.

api/PostHog.PublicAPI.Shipped.txt

@@ -103,6 +103,7 @@ namespace PostHogUnity
     {
         public PostHogConfig() { }
         public string ApiKey { get; set; }
+        public System.Func<PostHogUnity.PostHogEvent, PostHogUnity.PostHogEvent> BeforeSend { get; set; }
         public bool CaptureApplicationLifecycleEvents { get; set; }
         public bool CaptureExceptions { get; set; }
         public bool CaptureExceptionsInEditor { get; set; }

com.posthog.unity/Runtime/PostHogConfig.cs

@@ -106,6 +106,13 @@ public class PostHogConfig
         /// </summary>
         public Action OnFeatureFlagsLoaded { get; set; }
 
+        /// <summary>
+        /// Callback invoked after an event is fully enriched and before it is queued.
+        /// Return the event (mutated or unchanged) to continue, or null to drop it.
+        /// If the callback throws, the SDK logs the exception and drops the event.
+        /// </summary>
+        public Func<PostHogEvent, PostHogEvent> BeforeSend { get; set; }
+
         /// <summary>
         /// Whether to flush events before the application quits.
         /// When true, the SDK uses Application.wantsToQuit to delay quitting

com.posthog.unity/Runtime/PostHogSDK.cs

@@ -414,8 +414,15 @@ void CaptureInternal(string eventName, Dictionary<string, object> properties)
                 eventProps["$groups"] = groups;
             }
 
-            // Create and enqueue the event
+            // Create the fully enriched event, then give customers a final chance to modify or drop it.
             var evt = new PostHogEvent(eventName, _identityManager.DistinctId, eventProps);
+            evt = RunBeforeSend(evt);
+            if (evt == null)
+            {
+                PostHogLogger.Debug($"Event dropped by beforeSend: {eventName}");
+                return;
+            }
+
             _eventQueue.Enqueue(evt);
 
             // Touch session
@@ -424,6 +431,25 @@ void CaptureInternal(string eventName, Dictionary<string, object> properties)
             PostHogLogger.Debug($"Captured event: {eventName}");
         }
 
+        PostHogEvent RunBeforeSend(PostHogEvent evt)
+        {
+            var beforeSend = _config.BeforeSend;
+            if (beforeSend == null)
+            {
+                return evt;
+            }
+
+            try
+            {
+                return beforeSend(evt);
+            }
+            catch (Exception ex)
+            {
+                PostHogLogger.Error("beforeSend callback threw", ex);
+                return null;
+            }
+        }
+
         void AddSdkProperties(Dictionary<string, object> properties)
         {
             properties["$lib"] = SdkInfo.LibraryName;

tests/PostHog.Unity.Tests/PostHogSDKTests.cs

@@ -138,6 +138,93 @@ public void ResetsFeatureFlagCallTracking()
             }
         }
 
+        public class TheBeforeSendCallback
+        {
+            [Fact]
+            public void CanModifyEventBeforeItIsQueued()
+            {
+                var config = new PostHogConfig
+                {
+                    ApiKey = "test-api-key",
+                    BeforeSend = evt =>
+                    {
+                        evt.Properties.Remove("secret");
+                        evt.Properties["before_send"] = true;
+                        return evt;
+                    },
+                };
+                var sdk = CreateSdk(config);
+                var evt = new PostHogEvent(
+                    "before-send-event",
+                    "distinct-id",
+                    new Dictionary<string, object>
+                    {
+                        ["$lib"] = "posthog-unity",
+                        ["$lib_version"] = "1.0.0",
+                        ["$session_id"] = "session-id",
+                        ["source"] = "super",
+                        ["secret"] = "remove",
+                    }
+                );
+
+                var processed = RunBeforeSend(sdk, evt);
+
+                Assert.NotNull(processed);
+                Assert.True((bool)processed.Properties["before_send"]);
+                Assert.False(processed.Properties.ContainsKey("secret"));
+            }
+
+            [Theory]
+            [MemberData(nameof(DropCallbacks))]
+            public void CanDropEventBeforeItIsQueued(Func<PostHogEvent, PostHogEvent> beforeSend)
+            {
+                var config = new PostHogConfig { ApiKey = "test-api-key", BeforeSend = beforeSend };
+                var sdk = CreateSdk(config);
+
+                var processed = RunBeforeSend(sdk, new PostHogEvent("drop-me", "distinct-id"));
+
+                Assert.Null(processed);
+            }
+
+            public static IEnumerable<object[]> DropCallbacks()
+            {
+                yield return new object[] { (Func<PostHogEvent, PostHogEvent>)(_ => null) };
+                yield return new object[]
+                {
+                    (Func<PostHogEvent, PostHogEvent>)(
+                        _ => throw new InvalidOperationException("beforeSend failed")
+                    ),
+                };
+            }
+
+            static PostHogSDK CreateSdk(PostHogConfig config)
+            {
+                var sdk = (PostHogSDK)RuntimeHelpers.GetUninitializedObject(typeof(PostHogSDK));
+                SetField(sdk, "_config", config);
+                return sdk;
+            }
+
+            static PostHogEvent RunBeforeSend(PostHogSDK sdk, PostHogEvent evt)
+            {
+                var method = typeof(PostHogSDK).GetMethod(
+                    "RunBeforeSend",
+                    BindingFlags.Instance | BindingFlags.NonPublic
+                );
+                Assert.NotNull(method);
+                return (PostHogEvent)method.Invoke(sdk, new object[] { evt });
+            }
+
+            static void SetField(PostHogSDK sdk, string name, object value)
+            {
+                var field = typeof(PostHogSDK).GetField(
+                    name,
+                    BindingFlags.Instance | BindingFlags.NonPublic
+                );
+                Assert.NotNull(field);
+                field.SetValue(sdk, value);
+            }
+        }
+
         [Collection("UnityGlobals")]
         public class ThePublicApiMethods
         {