Custom SessionReplay masks in MAUI Android apps (#4121)

jamescrosswell · web-flow · commit 85c56e2d2e72 · 2025-04-27T15:15:33.000+12:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+### Features
+
+- Custom SessionReplay masks in MAUI Android apps ([#4121](https://github.com/getsentry/sentry-dotnet/pull/4121))
+
 ## 5.6.0
 
 ### Features
diff --git a/samples/Sentry.Samples.Maui/MainPage.xaml b/samples/Sentry.Samples.Maui/MainPage.xaml
@@ -1,6 +1,7 @@
 <?xml version="1.0" encoding="utf-8" ?>
 <ContentPage xmlns="http://schemas.microsoft.com/dotnet/2021/maui"
              xmlns:x="http://schemas.microsoft.com/winfx/2009/xaml"
+             xmlns:sentry="http://schemas.sentry.io/maui"
              x:Class="Sentry.Samples.Maui.MainPage">
 
     <ScrollView>
@@ -11,6 +12,7 @@
 
             <Image
                 Source="dotnet_bot.png"
+                sentry:SessionReplay.Mask="Unmask"
                 SemanticProperties.Description="Cute dot net bot waving hi to you!"
                 HeightRequest="200"
                 HorizontalOptions="Center" />
diff --git a/samples/Sentry.Samples.Maui/MauiProgram.cs b/samples/Sentry.Samples.Maui/MauiProgram.cs
@@ -25,12 +25,17 @@ public static MauiApp CreateMauiApp()
                 options.Debug = true;
                 options.SampleRate = 1.0F;
 
-#if ANDROID
+#if __ANDROID__
                 // Currently experimental support is only available on Android
                 options.Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate = 1.0;
                 options.Native.ExperimentalOptions.SessionReplay.SessionSampleRate = 1.0;
-                options.Native.ExperimentalOptions.SessionReplay.MaskAllImages = false;
-                options.Native.ExperimentalOptions.SessionReplay.MaskAllText = false;
+                // Mask all images and text by default. This can be overridden for individual view elements via the
+                // sentry:SessionReplay.Mask XML attribute (see MainPage.xaml for an example)
+                options.Native.ExperimentalOptions.SessionReplay.MaskAllImages = true;
+                options.Native.ExperimentalOptions.SessionReplay.MaskAllText = true;
+                // Alternatively the masking behaviour for entire classes of VisualElements can be configured here as
+                // an exception to the default behaviour.
+                options.Native.ExperimentalOptions.SessionReplay.UnmaskControlsOfType<Button>();
 #endif
 
                 options.SetBeforeScreenshotCapture((@event, hint) =>
diff --git a/samples/Sentry.Samples.Maui/Platforms/Android/MainActivity.cs b/samples/Sentry.Samples.Maui/Platforms/Android/MainActivity.cs
@@ -1,5 +1,8 @@
+#if __ANDROID__
 using Android.App;
 using Android.Content.PM;
+using Android.OS;
+#endif
 
 namespace Sentry.Samples.Maui;
 
diff --git a/src/Sentry.Maui/AssemblyInfo.cs b/src/Sentry.Maui/AssemblyInfo.cs
@@ -0,0 +1,3 @@
+// XML namespaces for custom XAML elements defined in the Sentry.Maui assembly (e.g. Bindable Properties)
+[assembly: XmlnsDefinition("http://schemas.sentry.io/maui", "Sentry.Maui")]
+[assembly: Microsoft.Maui.Controls.XmlnsPrefix("http://schemas.sentry.io/maui", "sentry")]
diff --git a/src/Sentry.Maui/Internal/MauiButtonEventsBinder.cs b/src/Sentry.Maui/Internal/MauiButtonEventsBinder.cs
@@ -29,7 +29,6 @@ public void UnBind(VisualElement element)
         }
     }
 
-
     private void OnButtonOnClicked(object? sender, EventArgs _)
         => addBreadcrumbCallback?.Invoke(new(sender, nameof(Button.Clicked)));
 
diff --git a/src/Sentry.Maui/Internal/MauiEventsBinder.cs b/src/Sentry.Maui/Internal/MauiEventsBinder.cs
@@ -1,4 +1,6 @@
 using Microsoft.Extensions.Options;
+using Microsoft.Maui.Platform;
+using Sentry.Extensibility;
 
 namespace Sentry.Maui.Internal;
 
diff --git a/src/Sentry.Maui/Internal/MauiVisualElementEventsBinder.cs b/src/Sentry.Maui/Internal/MauiVisualElementEventsBinder.cs
@@ -0,0 +1,66 @@
+using Microsoft.Extensions.Options;
+using Sentry.Extensibility;
+#if __ANDROID__
+using View = Android.Views.View;
+#endif
+
+namespace Sentry.Maui.Internal;
+
+/// <summary>
+/// Masks or unmasks visual elements for session replay recordings
+/// </summary>
+internal class MauiVisualElementEventsBinder : IMauiElementEventBinder
+{
+    private readonly SentryMauiOptions _options;
+
+    public MauiVisualElementEventsBinder(IOptions<SentryMauiOptions> options)
+    {
+        _options = options.Value;
+    }
+
+    /// <inheritdoc />
+    public void Bind(VisualElement element, Action<BreadcrumbEvent> _)
+    {
+        element.Loaded += OnElementLoaded;
+    }
+
+    /// <inheritdoc />
+    public void UnBind(VisualElement element)
+    {
+        element.Loaded -= OnElementLoaded;
+    }
+
+    internal void OnElementLoaded(object? sender, EventArgs _)
+    {
+        if (sender is not VisualElement element)
+        {
+            _options.LogDebug("OnElementLoaded: sender is not a VisualElement");
+            return;
+        }
+
+        var handler = element.Handler;
+        if (handler is null)
+        {
+            _options.LogDebug("OnElementLoaded: element.Handler is null");
+            return;
+        }
+
+#if __ANDROID__
+        if (element.Handler?.PlatformView is not View nativeView)
+        {
+            return;
+        }
+
+        if (_options.Native.ExperimentalOptions.SessionReplay.MaskedControls.FirstOrDefault(maskType => element.GetType().IsAssignableFrom(maskType)) is not null)
+        {
+            nativeView.Tag = SessionReplayMaskMode.Mask.ToNativeTag();
+            _options.LogDebug("OnElementLoaded: Successfully set sentry-mask tag on native view");
+        }
+        else if (_options.Native.ExperimentalOptions.SessionReplay.UnmaskedControls.FirstOrDefault(unmaskType => element.GetType().IsAssignableFrom(unmaskType)) is not null)
+        {
+            nativeView.Tag = SessionReplayMaskMode.Unmask.ToNativeTag();
+            _options.LogDebug("OnElementLoaded: Successfully set sentry-unmask tag on native view");
+        }
+#endif
+    }
+}
diff --git a/src/Sentry.Maui/SentryMauiAppBuilderExtensions.cs b/src/Sentry.Maui/SentryMauiAppBuilderExtensions.cs
@@ -57,6 +57,7 @@ public static MauiAppBuilder UseSentry(this MauiAppBuilder builder,
 
         services.AddSingleton<IMauiElementEventBinder, MauiButtonEventsBinder>();
         services.AddSingleton<IMauiElementEventBinder, MauiImageButtonEventsBinder>();
+        services.AddSingleton<IMauiElementEventBinder, MauiVisualElementEventsBinder>();
         services.TryAddSingleton<IMauiEventsBinder, MauiEventsBinder>();
 
         services.AddSentry<SentryMauiOptions>();
diff --git a/src/Sentry.Maui/SentryMauiOptions.cs b/src/Sentry.Maui/SentryMauiOptions.cs
@@ -81,7 +81,7 @@ public SentryMauiOptions()
     /// if this callback return false the capture will not take place
     /// </remarks>
     /// <code>
-    /// 
+    ///
     ///options.SetBeforeCapture((@event, hint) =>
     ///{
     ///    // Return true to capture or false to prevent the capture
diff --git a/src/Sentry.Maui/SessionReplay.cs b/src/Sentry.Maui/SessionReplay.cs
@@ -0,0 +1,90 @@
+
+using Sentry.Infrastructure;
+#if __ANDROID__
+using View = Android.Views.View;
+using Android.Views;
+using Java.Lang;
+using Microsoft.Maui.Handlers;
+using Microsoft.Maui.Platform;
+#endif
+
+namespace Sentry.Maui;
+
+/// <summary>
+/// Contains custom <see cref="BindableProperty"/> definitions used to control the behaviour of the Sentry SessionReplay
+/// feature in MAUI apps.
+/// <remarks>
+/// NOTE: Session Replay is currently an experimental feature for MAUI and is subject to change.
+/// </remarks>
+/// </summary>
+public static class SessionReplay
+{
+    /// <summary>
+    /// Mask can be used to either unmask or mask a view.
+    /// </summary>
+    public static readonly BindableProperty MaskProperty =
+        BindableProperty.CreateAttached(
+            "Mask",
+            typeof(SessionReplayMaskMode),
+            typeof(SessionReplay),
+            defaultValue: SessionReplayMaskMode.Mask,
+            propertyChanged: OnMaskChanged);
+
+    /// <summary>
+    /// Gets the value of the Mask property for a view.
+    /// </summary>
+    public static SessionReplayMaskMode GetMask(BindableObject view) => (SessionReplayMaskMode)view.GetValue(MaskProperty);
+
+    /// <summary>
+    /// Sets the value of the Mask property for a view.
+    /// </summary>
+    /// <param name="view">The view element to mask or unmask</param>
+    /// <param name="value">The value to assign. Can be either "sentry-mask" or "sentry-unmask".</param>
+    public static void SetMask(BindableObject view, SessionReplayMaskMode value) => view.SetValue(MaskProperty, value);
+
+    private static void OnMaskChanged(BindableObject bindable, object oldValue, object newValue)
+    {
+#if __ANDROID__
+        if (bindable is not VisualElement ve || newValue is not SessionReplayMaskMode maskSetting)
+        {
+            return;
+        }
+
+        // This code looks pretty funky... just matching how funky MAUI is though.
+        // See https://github.com/getsentry/sentry-dotnet/pull/4121#discussion_r2054129378
+        ve.HandlerChanged -= OnMaskedElementHandlerChanged;
+        ve.HandlerChanged -= OnUnmaskedElementHandlerChanged;
+
+        if (maskSetting == SessionReplayMaskMode.Mask)
+        {
+            ve.HandlerChanged += OnMaskedElementHandlerChanged;
+        }
+        else if (maskSetting == SessionReplayMaskMode.Unmask)
+        {
+            ve.HandlerChanged += OnUnmaskedElementHandlerChanged;
+        }
+#endif
+    }
+
+#if __ANDROID__
+    private static void OnMaskedElementHandlerChanged(object? sender, EventArgs _)
+    {
+        if ((sender as VisualElement)?.Handler?.PlatformView is not View nativeView)
+        {
+            return;
+        }
+
+        nativeView.Tag = SessionReplayMaskMode.Mask.ToNativeTag();
+    }
+
+    private static void OnUnmaskedElementHandlerChanged(object? sender, EventArgs _)
+    {
+        if ((sender as VisualElement)?.Handler?.PlatformView is not View nativeView)
+        {
+            return;
+        }
+
+        nativeView.Tag = SessionReplayMaskMode.Unmask.ToNativeTag();
+    }
+#endif
+}
diff --git a/src/Sentry.Maui/SessionReplayMaskMode.cs b/src/Sentry.Maui/SessionReplayMaskMode.cs
@@ -0,0 +1,32 @@
+namespace Sentry.Maui;
+
+/// <summary>
+/// Controls the masking behaviour of the Session Replay feature.
+/// </summary>
+public enum SessionReplayMaskMode
+{
+    /// <summary>
+    /// Masks the view
+    /// </summary>
+    Mask,
+    /// <summary>
+    /// Unmasks the view
+    /// </summary>
+    Unmask
+}
+
+internal static class SessionReplayMaskModeExtensions
+{
+#if __ANDROID__
+    /// <summary>
+    /// Maps from <see cref="SessionReplayMaskMode"/> to the native tag values used by the JavaSDK to mask and unmask
+    /// views. See https://docs.sentry.io/platforms/android/session-replay/privacy/#mask-by-view-instance
+    /// </summary>
+    public static string ToNativeTag(this SessionReplayMaskMode maskMode) => maskMode switch
+    {
+        SessionReplayMaskMode.Mask => "sentry-mask",
+        SessionReplayMaskMode.Unmask => "sentry-unmask",
+        _ => throw new ArgumentOutOfRangeException(nameof(maskMode), maskMode, null)
+    };
+#endif
+}
diff --git a/src/Sentry/Platforms/Android/NativeOptions.cs b/src/Sentry/Platforms/Android/NativeOptions.cs
@@ -272,6 +272,18 @@ public class NativeSentryReplayOptions
             public double? SessionSampleRate { get; set; }
             public bool MaskAllImages { get; set; } = true;
             public bool MaskAllText { get; set; } = true;
+            internal HashSet<Type> MaskedControls { get; } = [];
+            internal HashSet<Type> UnmaskedControls { get; } = [];
+
+            public void MaskControlsOfType<T>()
+            {
+                MaskedControls.Add(typeof(T));
+            }
+
+            public void UnmaskControlsOfType<T>()
+            {
+                UnmaskedControls.Add(typeof(T));
+            }
         }
 
         /// <summary>
diff --git a/test/Sentry.Maui.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt b/test/Sentry.Maui.Tests/ApiApprovalTests.Run.DotNet8_0.verified.txt
@@ -1,4 +1,6 @@
-﻿namespace Microsoft.Maui.Hosting
+﻿[assembly: Microsoft.Maui.Controls.XmlnsDefinition("http://schemas.sentry.io/maui", "Sentry.Maui")]
+[assembly: Microsoft.Maui.Controls.XmlnsPrefix("http://schemas.sentry.io/maui", "sentry")]
+namespace Microsoft.Maui.Hosting
 {
     public static class SentryMauiAppBuilderExtensions
     {
@@ -36,6 +38,17 @@ namespace Sentry.Maui
         public bool IncludeTitleInBreadcrumbs { get; set; }
         public void SetBeforeScreenshotCapture(System.Func<Sentry.SentryEvent, Sentry.SentryHint, bool> beforeCapture) { }
     }
+    public static class SessionReplay
+    {
+        public static readonly Microsoft.Maui.Controls.BindableProperty MaskProperty;
+        public static Sentry.Maui.SessionReplayMaskMode GetMask(Microsoft.Maui.Controls.BindableObject view) { }
+        public static void SetMask(Microsoft.Maui.Controls.BindableObject view, Sentry.Maui.SessionReplayMaskMode value) { }
+    }
+    public enum SessionReplayMaskMode
+    {
+        Mask = 0,
+        Unmask = 1,
+    }
 }
 namespace Sentry.Maui.Internal
 {
diff --git a/test/Sentry.Maui.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt b/test/Sentry.Maui.Tests/ApiApprovalTests.Run.DotNet9_0.verified.txt
@@ -1,4 +1,6 @@
-﻿namespace Microsoft.Maui.Hosting
+﻿[assembly: Microsoft.Maui.Controls.XmlnsDefinition("http://schemas.sentry.io/maui", "Sentry.Maui")]
+[assembly: Microsoft.Maui.Controls.XmlnsPrefix("http://schemas.sentry.io/maui", "sentry")]
+namespace Microsoft.Maui.Hosting
 {
     public static class SentryMauiAppBuilderExtensions
     {
@@ -36,6 +38,17 @@ namespace Sentry.Maui
         public bool IncludeTitleInBreadcrumbs { get; set; }
         public void SetBeforeScreenshotCapture(System.Func<Sentry.SentryEvent, Sentry.SentryHint, bool> beforeCapture) { }
     }
+    public static class SessionReplay
+    {
+        public static readonly Microsoft.Maui.Controls.BindableProperty MaskProperty;
+        public static Sentry.Maui.SessionReplayMaskMode GetMask(Microsoft.Maui.Controls.BindableObject view) { }
+        public static void SetMask(Microsoft.Maui.Controls.BindableObject view, Sentry.Maui.SessionReplayMaskMode value) { }
+    }
+    public enum SessionReplayMaskMode
+    {
+        Mask = 0,
+        Unmask = 1,
+    }
 }
 namespace Sentry.Maui.Internal
 {
diff --git a/test/Sentry.Maui.Tests/MauiEventsBinderTests.VisualElement.cs b/test/Sentry.Maui.Tests/MauiEventsBinderTests.VisualElement.cs
@@ -1,5 +1,8 @@
 using Sentry.Maui.Internal;
 using Sentry.Maui.Tests.Mocks;
+#if __ANDROID__
+using View = Android.Views.View;
+#endif
 
 namespace Sentry.Maui.Tests;
 
diff --git a/test/Sentry.Maui.Tests/MauiEventsBinderTests.cs b/test/Sentry.Maui.Tests/MauiEventsBinderTests.cs
@@ -18,6 +18,10 @@ public Fixture()
             hub.When(h => h.ConfigureScope(Arg.Any<Action<Scope>>()))
                 .Do(c => c.Arg<Action<Scope>>()(Scope));
 
+            Options.Debug = true;
+            var logger = Substitute.For<IDiagnosticLogger>();
+            logger.IsEnabled(Arg.Any<SentryLevel>()).Returns(true);
+            Options.DiagnosticLogger = logger;
             var options = Microsoft.Extensions.Options.Options.Create(Options);
             Binder = new MauiEventsBinder(
                 hub,
diff --git a/test/Sentry.Maui.Tests/MauiVisualElementEventsBinderTests.cs b/test/Sentry.Maui.Tests/MauiVisualElementEventsBinderTests.cs

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+// XML namespaces for custom XAML elements defined in the Sentry.Maui assembly (e.g. Bindable Properties)`
	`2`	`+[assembly: XmlnsDefinition("http://schemas.sentry.io/maui", "Sentry.Maui")]`
	`3`	`+[assembly: Microsoft.Maui.Controls.XmlnsPrefix("http://schemas.sentry.io/maui", "sentry")]`
Original file line number	Diff line number	Diff line change
`@@ -29,7 +29,6 @@ public void UnBind(VisualElement element)`
`29`	`29`	`}`
`30`	`30`	`}`
`31`	`31`
`32`		`-`
`33`	`32`	`private void OnButtonOnClicked(object? sender, EventArgs _)`
`34`	`33`	`=> addBreadcrumbCallback?.Invoke(new(sender, nameof(Button.Clicked)));`
`35`	`34`