> ## Documentation Index
> Fetch the complete documentation index at: https://launchdarkly-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# .NET MAUI SDK observability reference

> This topic documents how to get started with the LaunchDarkly observability and session replay SDK for .NET MAUI.

> For the complete documentation index, see [llms.txt](/llms.txt). For the full documentation snapshot, see [llms-full.txt](/llms-full.txt).

<Note title="This LaunchDarkly observability plugin is available for early access">
  This LaunchDarkly observability plugin is currently available in Early Access, and APIs are subject to change until a 1.x version is released.
</Note>

## Overview

This topic documents how to get started with the LaunchDarkly observability and session replay SDK for .NET MAUI.

The .NET MAUI SDK supports **observability** for error monitoring and logging, and **session replay** for capturing UI snapshots. It provides cross-platform support for both Android and iOS through .NET MAUI's native platform bindings.

<Note title="SDK quick links">
  LaunchDarkly's SDKs are open source. In addition to this reference guide, we provide source, API reference documentation, and a sample application:
</Note>

| Resource | Location |
| - | - |
| GitHub repository | [LaunchDarkly.SessionReplay](https://github.com/launchdarkly/observability-sdk/tree/main/sdk/%40launchdarkly/mobile-dotnet) |
| Published package | [NuGet](https://www.nuget.org/packages/LaunchDarkly.SessionReplay) |

## Prerequisites and dependencies

This SDK requires:

* .NET 9.0 or .NET 10.0 with the MAUI workload installed
* Android SDK version 24 or higher (Android 7.0, Nougat)
* iOS 13.2 or higher

## Get started

Follow these steps to get started:

* [Install the SDK](#install-the-sdk)
* [Initialize the SDK](#initialize-the-sdk)
* [Configure observability options](#configure-observability-options)
* [Configure session replay](#configure-session-replay)
* [Configure session replay privacy options](#configure-session-replay-privacy-options)
* [Use custom masking](#use-custom-masking)
* [Explore supported features](#explore-supported-features)
* [Review observability data in LaunchDarkly](#review-observability-data-in-launchdarkly)

## Install the SDK

Add the `LaunchDarkly.SessionReplay` NuGet package to your MAUI project:

<CodeGroup>
  ```bash title=".NET CLI" theme={null}
      dotnet add package LaunchDarkly.SessionReplay
  ```

  ```xml title="PackageReference" theme={null}
      <PackageReference Include="LaunchDarkly.SessionReplay" Version="0.*" />
  ```
</CodeGroup>

After installing, run `dotnet clean` before building. This is especially important for iOS targets, as stale build artifacts can cause issues. If you encounter dependency resolution problems, run `dotnet restore` first:

<CodeGroup>
  ```bash title=".NET CLI" theme={null}
      dotnet restore
      dotnet clean
      dotnet build
  ```
</CodeGroup>

<Warning title="Visual Studio with Android SDK on Windows">
  Visual Studio on Windows can have issues installing the SDK due to the Android SDK being in a system-protected directory. If you encounter build errors related to Android SDK access, you may need to move the Android SDK to a user-writable location.

  For detailed instructions, read the [Android SDK relocation guide for Windows](https://github.com/launchdarkly/observability-sdk/blob/main/sdk/%40launchdarkly/mobile-dotnet/docs/move-android-sdk-windows.md).
</Warning>

Then, import the SDK namespaces in your code:

<CodeGroup>
  ```csharp title="C#" theme={null}
      using LaunchDarkly.SessionReplay;
      using LaunchDarkly.Sdk.Client;
      using LaunchDarkly.Sdk.Client.Integrations;
      using LaunchDarkly.Observability;
  ```
</CodeGroup>

## Initialize the SDK

Initialize the SDK by registering the `ObservabilityPlugin` and `SessionReplayPlugin` as plugins on the LaunchDarkly client configuration. You should call this during your app's startup, typically in `MauiProgram.cs`.

The observability and session replay features are registered as plugins using the `PluginConfigurationBuilder`. This integrates them directly with the LaunchDarkly client lifecycle.

<Warning title=".NET MAUI observability SDK credentials">
  The .NET MAUI observability SDK uses a mobile key. Keys are specific to each project and environment. They are available from **Project settings**, on the **Environments** list. To learn more about key types, read [Keys](/sdk/concepts/client-side-server-side#keys).

  Mobile keys are not secret and you can expose them in your client-side code without risk. However, never embed a server-side SDK key into a client-side application.
</Warning>

Here's how to initialize the SDK:

<CodeGroup>
  ```csharp title="MauiProgram.cs" theme={null}
      using LaunchDarkly.SessionReplay;
      using LaunchDarkly.Sdk.Client;
      using LaunchDarkly.Sdk.Client.Integrations;
      using LaunchDarkly.Observability;

      public static class MauiProgram
      {
          public static MauiApp CreateMauiApp()
          {
              var builder = MauiApp.CreateBuilder();
              builder.UseMauiApp<App>();

              var mobileKey = "example-mobile-key";

              var ldConfig = Configuration.Builder(mobileKey, ConfigurationBuilder.AutoEnvAttributes.Enabled)
                  .Plugins(new PluginConfigurationBuilder()
                      .Add(ObservabilityPlugin.Builder(new ObservabilityOptions(
                          isEnabled: true,
                          serviceName: "my-maui-app"
                      )).Build())
                      .Add(SessionReplayPlugin.Builder(new SessionReplayOptions(
                          isEnabled: true
                      )).Build())
                  ).Build();

              var context = LaunchDarkly.Sdk.Context.New("example-user-key");
              var client = LdClient.Init(ldConfig, context, TimeSpan.FromSeconds(10));

              return builder.Build();
          }
      }
  ```
</CodeGroup>

## Configure observability options

You can customize the observability behavior by passing an `ObservabilityOptions` object to `ObservabilityPlugin.Builder()`.

Here is an example:

<CodeGroup>
  ```csharp title="Observability options" theme={null}
      var ldConfig = Configuration.Builder(mobileKey, ConfigurationBuilder.AutoEnvAttributes.Enabled)
          .Plugins(new PluginConfigurationBuilder()
              .Add(ObservabilityPlugin.Builder(new ObservabilityOptions(
                  isEnabled: true,
                  serviceName: "my-maui-app",
                  serviceVersion: "1.2.0",
                  contextFriendlyName: "Example User"
              )).Build())
              .Add(SessionReplayPlugin.Builder(new SessionReplayOptions(
                  isEnabled: true
              )).Build())
          ).Build();
  ```
</CodeGroup>

The available `ObservabilityOptions` configuration options are:

* **ServiceName**: The service name for the application. Defaults to `"observability-maui"`.
* **ServiceVersion**: The version of the service. Defaults to `"0.1.0"`.
* **OtlpEndpoint**: The endpoint URL for the OTLP exporter. Defaults to LaunchDarkly's endpoint.
* **BackendUrl**: The backend URL for the observability service. Defaults to LaunchDarkly's backend.
* **ContextFriendlyName**: An optional friendly name for the user context, displayed in the LaunchDarkly UI.

For more information on plugin options, read [Configuration for client-side observability](/sdk/features/observability-config-client-side).

## Configure session replay

The .NET MAUI SDK supports session replay, which captures snapshots of your app's UI at regular intervals. This allows you to visually review user sessions in LaunchDarkly to better understand user behavior and diagnose issues.

Session replay is configured through the `SessionReplayOptions` object passed to `SessionReplayPlugin.Builder()`.

Here's how to configure session replay:

<CodeGroup>
  ```csharp title="Session replay options" theme={null}
      var ldConfig = Configuration.Builder(mobileKey, ConfigurationBuilder.AutoEnvAttributes.Enabled)
          .Plugins(new PluginConfigurationBuilder()
              .Add(ObservabilityPlugin.Builder(new ObservabilityOptions(
                  isEnabled: true,
                  serviceName: "my-maui-app"
              )).Build())
              .Add(SessionReplayPlugin.Builder(new SessionReplayOptions(
                  isEnabled: true,
                  privacy: new SessionReplayOptions.PrivacyOptions(
                      maskTextInputs: true,
                      maskWebViews: false,
                      maskLabels: false,
                      maskImages: false
                  )
              )).Build())
          ).Build();
  ```
</CodeGroup>

The available `SessionReplayOptions` configuration options are:

* **IsEnabled**: Enables or disables session replay. Defaults to `true`.
* **ServiceName**: The service name for session replay telemetry. Defaults to `"sessionreplay-dotnet"`.
* **Privacy**: Controls how UI elements are masked in the replay. To learn more, read [Configure session replay privacy options](#configure-session-replay-privacy-options).

## Configure session replay privacy options

The `PrivacyOptions` class controls how UI elements are masked during session replay. By default, text inputs are masked to protect user privacy.

Here's how to configure privacy settings:

<CodeGroup>
  ```csharp title="Privacy options" theme={null}
      var replay = new SessionReplayOptions(
          isEnabled: true,
          privacy: new SessionReplayOptions.PrivacyOptions(
              maskTextInputs: true,
              maskWebViews: false,
              maskLabels: false,
              maskImages: false,
              minimumAlpha: 0.02
          )
      );
  ```
</CodeGroup>

The available privacy options are:

* **MaskTextInputs**: When `true`, masks all text input fields. Defaults to `true`.
* **MaskWebViews**: When `true`, masks the contents of web views. Web views are rendered as blank rectangles in session replays. Defaults to `false`.
* **MaskLabels**: When `true`, masks all text labels. Defaults to `false`.
* **MaskImages**: When `true`, masks all images. Defaults to `false`.
* **MinimumAlpha**: Minimum alpha value for view visibility in recordings. Views with alpha below this threshold are not captured. Defaults to `0.02`.

### Common privacy configurations

For maximum privacy (recommended for production):

<CodeGroup>
  ```csharp title="Maximum privacy" theme={null}
      var privacy = new SessionReplayOptions.PrivacyOptions(
          maskTextInputs: true,
          maskWebViews: true,
          maskLabels: true,
          maskImages: true
      );
  ```
</CodeGroup>

For debugging or development, you can turn masking off:

<CodeGroup>
  ```csharp title="No masking" theme={null}
      var privacy = new SessionReplayOptions.PrivacyOptions(
          maskTextInputs: false,
          maskWebViews: false,
          maskLabels: false,
          maskImages: false
      );
  ```
</CodeGroup>

For selective masking, you can mask inputs but show regular text and images:

<CodeGroup>
  ```csharp title="Selective masking" theme={null}
      var privacy = new SessionReplayOptions.PrivacyOptions(
          maskTextInputs: true,
          maskWebViews: true,
          maskLabels: false,
          maskImages: false
      );
  ```
</CodeGroup>

For more information on session replay configuration, read [Configuration for session replay](/sdk/features/session-replay-config).

## Use custom masking

In addition to the privacy profile settings, you can explicitly mask or unmask individual MAUI views using the `LDMask()` and `LDUnmask()` extension methods. This gives you fine-grained control over which UI elements are captured in session replay recordings.

<CodeGroup>
  ```csharp title="Masking individual views" theme={null}
      using LaunchDarkly.SessionReplay;

      // Mask a sensitive field in session replay
      var passwordEntry = new Entry { Placeholder = "Password", IsPassword = true };
      passwordEntry.LDMask();

      // Unmask a field that would otherwise be masked by privacy settings
      var publicInfoLabel = new Label { Text = "Public information" };
      publicInfoLabel.LDUnmask();
  ```
</CodeGroup>

<Info title="Handler must be attached">
  The `LDMask()` and `LDUnmask()` methods work by accessing the underlying native platform view. The MAUI view's handler must be attached before calling these methods. Call them after the view has been added to the visual tree, such as in a page's `Appearing` event or after `Handler` is set.
</Info>

The `.LDMask()` and `.LDUnmask()` extension methods work on any MAUI `View`, and they apply the masking to the underlying native view on both Android and iOS.

## Explore supported features

The .NET MAUI observability SDK supports the following features. After the SDK is initialized, you can access these from within your application:

* [Configuration for client-side observability](/sdk/features/observability-config-client-side)
* [Configuration for session replay](/sdk/features/session-replay-config)
* [Logs](/sdk/features/observability-logs)

## Review observability data in LaunchDarkly

After you initialize the SDK, your application automatically starts sending observability data back to LaunchDarkly, including errors, logs, and session replay recordings. You can review this information in the LaunchDarkly user interface. To learn how, read [Observability](/home/observability).