---
title: "Apple Native Options"
description: "Configure the embedded Sentry Cocoa SDK when using .NET for iOS, macOS, or Mac Catalyst."
url: https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options/
---

# Apple Native Options | Sentry for .NET for iOS, macOS, and Mac Catalyst

When you use the .NET for Apple platforms integration, Sentry embeds the [Sentry Cocoa SDK](https://docs.sentry.io/platforms/apple.md) to provide native crash reporting and other platform-specific features. The `options.Native` property exposes configuration for this embedded SDK.

```csharp
SentrySdk.Init(options =>
{
    options.Dsn = "___PUBLIC_DSN___";

    // Native Cocoa SDK options:
    options.Native.EnableAppHangTracking = true;
    options.Native.AttachScreenshot = true;
});
```

These options are also available in [MAUI](https://docs.sentry.io/platforms/dotnet/guides/maui.md) when targeting iOS or Mac Catalyst.

## [Screenshots](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#screenshots)

### [Native.AttachScreenshot](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.AttachScreenshot)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Automatically attaches a screenshot when the native Cocoa SDK captures an exception. Disabled by default.

See [Attach Screenshot](https://docs.sentry.io/platforms/apple/guides/ios/configuration/options.md#attachScreenshot).

## [App Hangs](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#app-hangs)

### [Native.EnableAppHangTracking](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableAppHangTracking)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Detects [App Hangs](https://docs.sentry.io/platforms/apple/configuration/app-hangs.md), which are periods where the main thread is unresponsive for longer than `AppHangTimeoutInterval`. Disabled by default.

### [Native.AppHangTimeoutInterval](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.AppHangTimeoutInterval)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(2)` |

The minimum duration the main thread must be unresponsive before it's classified as an App Hang. Avoid values below 100ms, which may generate excessive events. Default is 2 seconds.

Requires `EnableAppHangTracking` to be `true`.

See [App Hangs](https://docs.sentry.io/platforms/apple/configuration/app-hangs.md).

## [Breadcrumbs](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#breadcrumbs)

### [Native.EnableAutoBreadcrumbTracking](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableAutoBreadcrumbTracking)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Automatically adds breadcrumbs for various system events (network changes, low memory warnings, etc.). Enabled by default.

See [Automatic Breadcrumbs](https://docs.sentry.io/platforms/apple/enriching-events/breadcrumbs.md#automatic-breadcrumbs).

## [Performance](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#performance)

### [Native.EnableAutoPerformanceTracing](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableAutoPerformanceTracing)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Automatically tracks performance for `UIViewController` subclasses, HTTP requests, app start time, and slow/frozen frames. Enabled by default.

Requires performance monitoring to be configured (i.e. `TracesSampleRate` or `TracesSampler`).

See [Automatic Instrumentation](https://docs.sentry.io/platforms/apple/performance/instrumentation/automatic-instrumentation.md).

### [Native.EnableCoreDataTracing](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableCoreDataTracing)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Tracks performance of Core Data operations. Requires performance monitoring to be enabled.

See [Core Data Tracing](https://docs.sentry.io/platforms/apple/performance/instrumentation/automatic-instrumentation.md#core-data-tracing).

### [Native.EnableFileIOTracing](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableFileIOTracing)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Tracks performance of file IO reads and writes via `NSData`. Requires `EnableAutoPerformanceTracing` and `EnableSwizzling` to be enabled.

See [File I/O Tracing](https://docs.sentry.io/platforms/apple/performance/instrumentation/automatic-instrumentation.md#file-io-tracing).

### [Native.EnableNetworkTracking](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableNetworkTracking)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Tracks performance of HTTP requests and adds breadcrumbs for network activity. Requires `EnableAutoPerformanceTracing` and `EnableSwizzling` to be enabled.

See [Network Tracking](https://docs.sentry.io/platforms/apple/performance/instrumentation/automatic-instrumentation.md#network-tracking).

### [Native.EnableNetworkBreadcrumbs](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableNetworkBreadcrumbs)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Adds breadcrumbs for each network request. Requires `EnableAutoPerformanceTracing` and `EnableSwizzling` to be enabled.

### [Native.EnableUIViewControllerTracing](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableUIViewControllerTracing)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Automatically creates transactions for `UIViewController` subclasses.

See [UIViewController Tracing](https://docs.sentry.io/platforms/apple/performance/instrumentation/automatic-instrumentation.md#uiviewcontroller-tracing).

### [Native.EnableUserInteractionTracing](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableUserInteractionTracing)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Creates transactions for UI events such as button taps and switch toggles. Disabled by default.

See [User Interaction Tracing](https://docs.sentry.io/platforms/apple/performance/instrumentation/automatic-instrumentation.md#user-interaction-tracing).

### [Native.IdleTimeout](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.IdleTimeout)

| Type    | `TimeSpan`                |
| ------- | ------------------------- |
| Default | `TimeSpan.FromSeconds(3)` |

How long an idle transaction waits for new child spans after all existing spans finish. Only applies to UI event transactions.

### [Native.EnableTracing](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableTracing)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Enables tracing features on the embedded Cocoa SDK directly. When disabled, the .NET SDK still handles traces for managed code.

## [Swizzling](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#swizzling)

### [Native.EnableSwizzling](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.EnableSwizzling)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Controls whether the SDK uses [method swizzling](https://docs.sentry.io/platforms/apple/configuration/swizzling.md) to instrument the app automatically. When disabled, the following features are also disabled:

* Breadcrumbs for touch events and navigation
* Automatic instrumentation for `UIViewController`, HTTP requests, and file IO
* Automatic injection of the `sentry-trace` header for distributed tracing

## [Profiling](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#profiling)

Call `AddProfilingIntegration()` on `SentryOptions.Native` to enable native profiling on Apple platforms. This is automatically added by the SDK, but you can call it explicitly if needed.

```csharp
SentrySdk.Init(options =>
{
    options.Dsn = "___PUBLIC_DSN___";
    options.Native.AddProfilingIntegration();
});
```

## [Error Handling](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#error-handling)

### [Native.SuppressSignalAborts](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.SuppressSignalAborts)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Suppresses native `SIGABRT` errors from being captured by the Cocoa SDK.

When managed code results in a `NullReferenceException`, this also causes a `SIGABRT`. Without suppression, Sentry may capture duplicate events — one from managed code and one from the native SDK. Enabling this option prevents the native duplicate, but also suppresses genuine native `SIGABRT` crashes.

### [Native.SuppressExcBadAccess](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.SuppressExcBadAccess)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Suppresses native `EXC_BAD_ACCESS` errors from being captured by the Cocoa SDK.

`NullReferenceException` in managed code also triggers `EXC_BAD_ACCESS`. Enabling this option prevents native duplicates but may also suppress genuine native memory access errors.

## [Networking](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#networking)

### [Native.UrlSessionDelegate](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.UrlSessionDelegate)

| Type    | `NSUrlSessionDelegate?` |
| ------- | ----------------------- |
| Default | `null`                  |

Sets a custom delegate on the `NSURLSession` used for data transfer by the native Cocoa SDK.

## [Stack Traces](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#stack-traces)

Use this method to control which iOS modules are considered "in-app" in stack traces. Note that this uses iOS module names, not .NET namespaces.

### [Native.AddInAppInclude(prefix)](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.AddInAppInclude\(prefix\))

| Type | `method` |
| ---- | -------- |

Includes frames matching the given iOS module prefix as "in-app" in stack traces.

```csharp
options.Native.AddInAppInclude("MyApp");
```

See [In-App Include](https://docs.sentry.io/platforms/apple/configuration/options.md#inAppInclude).

## [Session Replay](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#session-replay)

Session Replay for Apple platforms is currently experimental and must be opted into.

### [Native.ExperimentalOptions.SessionReplay.SessionSampleRate](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.SessionSampleRate)

| Type    | `double?` |
| ------- | --------- |
| Default | `null`    |

Sample rate for all sessions, between `0.0` and `1.0`. Set to `0.0` or leave as `null` to disable session replay for regular sessions.

### [Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.OnErrorSampleRate)

| Type    | `double?` |
| ------- | --------- |
| Default | `null`    |

Sample rate for buffered replays that are triggered when an error occurs. The SDK keeps the previous minute of activity and continues until the session ends when an error is sampled.

### [Native.ExperimentalOptions.SessionReplay.MaskAllText](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.MaskAllText)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Masks all text content in session replay recordings to protect user privacy. Enabled by default.

### [Native.ExperimentalOptions.SessionReplay.MaskAllImages](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.MaskAllImages)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Masks all images in session replay recordings to protect user privacy. Enabled by default.

### [Native.ExperimentalOptions.SessionReplay.EnableViewRendererV2](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.EnableViewRendererV2)

| Type    | `bool` |
| ------- | ------ |
| Default | `true` |

Captures session replay on a background thread to avoid interfering with the main thread and reduce potential frame drops. This is a recommended setting; disable only if you encounter specific issues.

### [Native.ExperimentalOptions.SessionReplay.EnableFastViewRendering](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.EnableFastViewRendering)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Enables faster view rendering at the cost of some visual fidelity. Disabled by default.

### [Native.ExperimentalOptions.SessionReplay.EnableSessionReplayInUnreliableEnvironment](https://docs.sentry.io/platforms/dotnet/guides/apple/configuration/native-options.md#Native.ExperimentalOptions.SessionReplay.EnableSessionReplayInUnreliableEnvironment)

| Type    | `bool`  |
| ------- | ------- |
| Default | `false` |

Due to potential masking issues, session replay is disabled on iOS 26+ with Liquid Glass. If you [understand these issues](https://docs.sentry.io/platforms/apple/guides/ios/session-replay/troubleshooting.md#why-is-session-replay-not-running-on-ios-260) and want to force Session Replay to be enabled anyway, you can use this setting to enable it.

Enabling this option on iOS 26+ may result in PII (text and images) not being masked as expected.

See [sentry-cocoa#6389](https://github.com/getsentry/sentry-cocoa/issues/6389) for details.