Session Replay for iOS (#4664)

Author: jamescrosswell

CHANGELOG.md

@@ -15,6 +15,7 @@
 - The SDK now makes use of the new SessionEndStatus `Unhandled` when capturing an unhandled but non-terminal exception, i.e. through the UnobservedTaskExceptionIntegration ([#4633](https://github.com/getsentry/sentry-dotnet/pull/4633), [#4653](https://github.com/getsentry/sentry-dotnet/pull/4653))
 - The SDK now provides a `IsSessionActive` to allow checking the session state ([#4662](https://github.com/getsentry/sentry-dotnet/pull/4662))
 - The SDK now makes use of the new SessionEndStatus `Unhandled` when capturing an unhandled but non-terminal exception, i.e. through the UnobservedTaskExceptionIntegration ([#4633](https://github.com/getsentry/sentry-dotnet/pull/4633))
+- Added experimental support for Session Replay on iOS ([#4664](https://github.com/getsentry/sentry-dotnet/pull/4664))
 - Extended the App context by `app_memory` that can hold the amount of memory used by the application in bytes. ([#4707](https://github.com/getsentry/sentry-dotnet/pull/4707))
 
 ### Fixes

Sentry.sln

@@ -221,7 +221,6 @@ Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "scripts", "scripts", "{A8A9
 		scripts\build-sentry-cocoa.sh = scripts\build-sentry-cocoa.sh
 		scripts\update-project-xml.ps1 = scripts\update-project-xml.ps1
 		scripts\build-sentry-native.ps1 = scripts\build-sentry-native.ps1
-		scripts\ios-simulator-utils.ps1 = scripts\ios-simulator-utils.ps1
 		scripts\commit-formatted-code.sh = scripts\commit-formatted-code.sh
 		scripts\accept-verifier-changes.ps1 = scripts\accept-verifier-changes.ps1
 		scripts\generate-cocoa-bindings.ps1 = scripts\generate-cocoa-bindings.ps1

samples/Sentry.Samples.Maui/MauiProgram.cs

@@ -44,20 +44,22 @@ public static MauiApp CreateMauiApp()
                 // Automatically create traces for async relay commands in the MVVM Community Toolkit
                 options.AddCommunityToolkitIntegration();
 
-#if __ANDROID__
-                // Currently, experimental support is only available on Android
+#if __ANDROID__ || __IOS__ || __MACCATALYST__
+                // Experimental support for Session Replay is currently available on Android, iOS and Mac Catalyst.
                 options.Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate = 1.0;
                 options.Native.ExperimentalOptions.SessionReplay.SessionSampleRate = 1.0;
                 // 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;
+#if __ANDROID__
                 // Alternatively, the masking behaviour for entire classes of VisualElements can be configured here as
                 // an exception to the default behaviour.
                 // WARNING: In apps with complex user interfaces, consisting of hundreds of visual controls on a single
                 // page, this option may cause performance issues. In such cases, consider applying the
                 // sentry:SessionReplay.Mask="Unmask" attribute to individual controls instead.
                 options.Native.ExperimentalOptions.SessionReplay.UnmaskControlsOfType<Button>();
+#endif
 #endif
 
                 options.SetBeforeScreenshotCapture((@event, hint) =>

samples/Sentry.Samples.Maui/Sentry.Samples.Maui.csproj

@@ -7,7 +7,7 @@
       On Windows, we'll also build for Windows 10.
     -->
     <TargetFrameworks>$(TargetFrameworks);net9.0-android</TargetFrameworks>
-    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0;net9.0-ios18.0;net9.0-maccatalyst18.0</TargetFrameworks>
+    <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('windows'))">$(TargetFrameworks);net9.0-windows10.0.19041.0</TargetFrameworks>
     <TargetFrameworks Condition="$([MSBuild]::IsOSPlatform('OSX'))">$(TargetFrameworks);net9.0-ios18.0;net9.0-maccatalyst18.0</TargetFrameworks>
     <OutputType>Exe</OutputType>
     <RootNamespace>Sentry.Samples.Maui</RootNamespace>

scripts/patch-cocoa-bindings.cs

@@ -114,6 +114,7 @@
         "SentryDsn",
         "SentryEvent",
         "SentryException",
+        "SentryExperimentalOptions",
         "SentryFeedback",
         "SentryFeedbackAPI",
         "SentryFrame",
@@ -155,7 +156,10 @@
         "SentryUser",
         "SentryViewScreenshotOptions",
         "SentryViewScreenshotProvider"
-    );
+    )
+    // Rename and retarget the experimental options property
+    .RenameProperty("SentryOptions", "_swiftExperimentalOptions", "Experimental")
+    .ChangePropertyType("SentryOptions", "Experimental", "SentryExperimentalOptions");
 
 var formatted = CodeFormatter.Format(nodes, new AdhocWorkspace());
 File.WriteAllText(args[0], formatted.ToFullString() + "\n");
@@ -388,6 +392,31 @@ public static CompilationUnitSyntax VerifyProperty(
             .Where(node => node.Identifier.Matches(property) && node.HasParent(type));
         return root.ReplaceNodes(nodes, (node, _) => node.WithAttributeLists(node.AttributeLists.RemoveAttribute("Verify", verify)));
     }
+
+    public static CompilationUnitSyntax RenameProperty(
+        this CompilationUnitSyntax root,
+        string type,
+        string from,
+        string to)
+    {
+        var nodes = root.DescendantNodes()
+            .OfType<PropertyDeclarationSyntax>()
+            .Where(node => node.Identifier.Matches(from) && node.HasParent(type));
+        return root.ReplaceNodes(nodes, (node, _) => node.WithIdentifier(SyntaxFactory.Identifier(to)));
+    }
+
+    public static CompilationUnitSyntax ChangePropertyType(
+        this CompilationUnitSyntax root,
+        string type,
+        string property,
+        string newType)
+    {
+        var nodes = root.DescendantNodes()
+            .OfType<PropertyDeclarationSyntax>()
+            .Where(node => node.Identifier.Matches(property) && node.HasParent(type));
+        return root.ReplaceNodes(nodes, (node, _) => node.WithType(SyntaxFactory.ParseTypeName(newType)));
+    }
+
 }
 
 internal static class SyntaxNodeExtensions

src/Sentry.Bindings.Cocoa/ApiDefinitions.cs

@@ -1611,7 +1611,7 @@ interface SentryOptions
 
     // @property (readonly, nonatomic) NSObject * _Nonnull _swiftExperimentalOptions;
     [Export("_swiftExperimentalOptions")]
-    NSObject _swiftExperimentalOptions { get; }
+    SentryExperimentalOptions Experimental { get; }
 }
 
 // typedef void (^SentryProfilingConfigurationBlock)(SentryProfileOptions * _Nonnull);
@@ -2126,6 +2126,36 @@ interface SentryUser : SentrySerializable
     nuint Hash { get; }
 }
 
+// @interface SentryExperimentalOptions : NSObject
+[BaseType(typeof(NSObject), Name = "_TtC6Sentry25SentryExperimentalOptions")]
+[Internal]
+interface SentryExperimentalOptions
+{
+    // @property (nonatomic) BOOL enableDataSwizzling;
+    [Export("enableDataSwizzling")]
+    bool EnableDataSwizzling { get; set; }
+
+    // @property (nonatomic) BOOL enableFileManagerSwizzling;
+    [Export("enableFileManagerSwizzling")]
+    bool EnableFileManagerSwizzling { get; set; }
+
+    // @property (nonatomic) BOOL enableUnhandledCPPExceptionsV2;
+    [Export("enableUnhandledCPPExceptionsV2")]
+    bool EnableUnhandledCPPExceptionsV2 { get; set; }
+
+    // @property (nonatomic) BOOL enableSessionReplayInUnreliableEnvironment;
+    [Export("enableSessionReplayInUnreliableEnvironment")]
+    bool EnableSessionReplayInUnreliableEnvironment { get; set; }
+
+    // @property (nonatomic) BOOL enableLogs;
+    [Export("enableLogs")]
+    bool EnableLogs { get; set; }
+
+    // -(void)validateOptions:(NSDictionary<NSString *,id> * _Nullable)options;
+    [Export("validateOptions:")]
+    void ValidateOptions([NullAllowed] NSDictionary<NSString, NSObject> options);
+}
+
 // @interface SentryFeedback : NSObject
 [BaseType(typeof(NSObject), Name = "_TtC6Sentry14SentryFeedback")]
 [DisableDefaultCtor]

src/Sentry/Internal/ReplaySession.cs

@@ -25,6 +25,10 @@ public SentryId? ActiveReplayId
             // Check to see if a Replay ID is available
             var replayId = JavaSdk.ScopesAdapter.Instance?.Options?.ReplayController?.ReplayId?.ToSentryId();
             return (replayId is { } id && id != SentryId.Empty) ? id : null;
+#elif __IOS__
+            string? nativeId = null;
+            SentryCocoaSdk.ConfigureScope(scope => nativeId = scope.ReplayId);
+            return (nativeId is { } id) ? SentryId.Parse(id) : null;
 #else
             return null;
 #endif

src/Sentry/Platforms/Cocoa/SentryOptions.cs

@@ -267,6 +267,104 @@ public void AddInAppInclude(string prefix)
             InAppIncludes ??= new List<string>();
             InAppIncludes.Add(prefix);
         }
+
+        /// <summary>
+        /// Options for experimental features in the native Sentry Cocoa SDK.
+        /// </summary>
+        public class NativeExperimentalOptions
+        {
+            /// <summary>
+            /// Session Replay options.
+            /// </summary>
+            public NativeSentryReplayOptions SessionReplay { get; set; } = new();
+        }
+
+        /// <summary>
+        /// Session Replay options for the native Sentry Cocoa SDK.
+        /// </summary>
+        public class NativeSentryReplayOptions
+        {
+            /// <summary>
+            /// <para>
+            /// Forces enabling of session replay in unreliable environments.
+            /// </para>
+            /// <para>
+            /// Due to internal changes with the release of Liquid Glass on iOS 26.0, the masking of text and images can
+            /// not be reliably guaranteed. Therefore the SDK uses a defensive programming approach to disable the
+            /// session replay integration by default, unless the environment is detected as reliable.
+            /// </para>
+            /// <para>
+            /// Indicators for reliable environments include:
+            /// <list type="bullet">
+            ///   <item>
+            ///     <description>Running on an older version of iOS that doesn't have Liquid Glass (iOS 18 or earlier)</description>
+            ///   </item>
+            ///   <item>
+            ///     <description><c>UIDesignRequiresCompatibility</c> is explicitly set to <c>YES</c> in <c>Info.plist</c></description>
+            ///   </item>
+            ///   <item>
+            ///     <description>The app was built with Xcode &lt; 26.0 (DTXcode &lt; 2600)</description>
+            ///   </item>
+            /// </list>
+            /// </para>
+            /// <para>
+            /// Important: This flag allows to re-enable the session replay integration on iOS 26.0 and later, but please be aware that text and images may not be masked as expected.
+            /// </para>
+            /// </summary>
+            /// <remarks>
+            /// See https://github.com/getsentry/sentry-cocoa/issues/6389
+            /// </remarks>
+            public bool EnableSessionReplayInUnreliableEnvironment { get; set; } = false;
+
+            /// <summary>
+            /// The sample rate for sessions that had an error or crash.
+            /// Value must be between 0.0 and 1.0.
+            /// A value of 0.0 disables session replay for errored sessions.
+            /// A value of 1.0 captures session replay for all errored sessions.
+            /// </summary>
+            public double? OnErrorSampleRate { get; set; }
+            /// <summary>
+            /// The sample rate for all sessions.
+            /// Value must be between 0.0 and 1.0.
+            /// A value of 0.0 disables session replay for all sessions.
+            /// A value of 1.0 captures session replay for all sessions.
+            /// </summary>
+            public double? SessionSampleRate { get; set; }
+            /// <summary>
+            /// Whether to mask all images in the session replay by default.
+            /// </summary>
+            public bool MaskAllImages { get; set; } = true;
+            /// <summary>
+            /// Whether to mask all text in the session replay by default.
+            /// </summary>
+            public bool MaskAllText { get; set; } = true;
+
+            /// <summary>
+            /// When enabled, reduces the impact of Session Replay on the main thread and potential frame drops. This is
+            /// the default and recommended setting, but if you are experiencing issues then you can opt out by setting
+            /// to <c>false</c>.
+            /// </summary>
+            /// <remarks>Defaults to <c>true</c></remarks>
+            public bool EnableViewRendererV2 { get; set; } = true;
+
+            /// <summary>
+            /// <para>
+            /// Enables faster rendering of views at the cost of some visual fidelity.
+            /// </para>
+            /// <para>
+            /// See: https://blog.sentry.io/boosting-session-replay-performance-on-ios-with-view-renderer-v2/
+            /// </para>
+            /// </summary>
+            /// <remarks>Defaults to <c>false</c></remarks>
+            public bool EnableFastViewRendering { get; set; } = false;
+
+            internal bool IsSessionReplayEnabled => OnErrorSampleRate > 0.0 || SessionSampleRate > 0.0;
+        }
+
+        /// <summary>
+        /// ExperimentalOptions
+        /// </summary>
+        public NativeExperimentalOptions ExperimentalOptions { get; set; } = new();
     }
 
     // We actually add the profiling integration automatically in InitSentryCocoaSdk().

src/Sentry/Platforms/Cocoa/SentrySdk.cs

@@ -145,6 +145,29 @@ private static void InitSentryCocoaSdk(SentryOptions options)
         // nativeOptions.DefaultIntegrations
         // nativeOptions.EnableProfiling  (deprecated)
 
+        // Session Replay options for the Cocoa SDK
+        if (options.Native.ExperimentalOptions.SessionReplay.IsSessionReplayEnabled)
+        {
+            // For replay to work on iOS, session tracking must be enabled in the Cocoa SDK
+            options.AutoSessionTracking = false;
+            nativeOptions.EnableAutoSessionTracking = true;
+
+            // SDK users must explicitly opt-in to Session Replay in unreliable environments
+            nativeOptions.Experimental.EnableSessionReplayInUnreliableEnvironment =
+                options.Native.ExperimentalOptions.SessionReplay.EnableSessionReplayInUnreliableEnvironment;
+
+            var sessionSampleRate = (float)(options.Native.ExperimentalOptions.SessionReplay.SessionSampleRate ?? 0f);
+            var onErrorSampleRate = (float)(options.Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate ?? 0f);
+            var cocoaReplayOptions = new Sentry.CocoaSdk.SentryReplayOptions();
+            cocoaReplayOptions.SessionSampleRate = sessionSampleRate;
+            cocoaReplayOptions.OnErrorSampleRate = onErrorSampleRate;
+            cocoaReplayOptions.MaskAllText = options.Native.ExperimentalOptions.SessionReplay.MaskAllText;
+            cocoaReplayOptions.MaskAllImages = options.Native.ExperimentalOptions.SessionReplay.MaskAllImages;
+            cocoaReplayOptions.EnableViewRendererV2 = options.Native.ExperimentalOptions.SessionReplay.EnableViewRendererV2;
+            cocoaReplayOptions.EnableFastViewRendering = options.Native.ExperimentalOptions.SessionReplay.EnableFastViewRendering;
+            nativeOptions.SessionReplay = cocoaReplayOptions;
+        }
+
         // Set hybrid SDK name
         SentryCocoaHybridSdk.SetSdkName("sentry.cocoa.dotnet");
 

test/Sentry.Tests/Platforms/iOS/BindableSentryOptionsTests.cs

@@ -6,7 +6,8 @@ namespace Sentry.Tests.Platforms.Cocoa;
 public class BindableSentryOptionsTests : BindableTests<SentryOptions.NativeOptions>
 {
     public BindableSentryOptionsTests()
-    : base(nameof(SentryOptions.NativeOptions.UrlSessionDelegate))
+    : base(nameof(SentryOptions.NativeOptions.UrlSessionDelegate),
+        nameof(SentryOptions.NativeOptions.ExperimentalOptions))
     {
     }