> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userpilot.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MAUI SDK

> Install and configure the Userpilot MAUI SDK

Install and initialize the Userpilot MAUI SDK, identify users, track screens and events, and configure optional settings.

The Userpilot MAUI SDK enables you to capture user insights and deliver personalized in-app experiences in real time. With a one-time setup, you can immediately begin leveraging Userpilot's analytics and engagement features to understand user behavior and guide their journeys in-app.

***

## Prerequisites

Before you begin, ensure your project meets the following requirements:

| **Requirement**       | **Version**      |
| --------------------- | ---------------- |
| .NET                  | 9.0 or higher    |
| iOS Deployment Target | 13.0 or higher   |
| Android Min SDK       | API 21 or higher |

***

## Installing the Library

### NuGet Package (Recommended)

Install the Userpilot MAUI SDK — a single package that automatically includes the correct platform bindings:

```xml theme={null}
<PackageReference Include="Userpilot.Maui" Version="<latest_version>" />
```

Replace `<latest_version>` with the [latest release version](https://www.nuget.org/packages/Userpilot.Maui).

Or via the .NET CLI:

```bash theme={null}
dotnet add package Userpilot.Maui
```

### Project Reference (Local Development)

Add a project reference to the appropriate binding project in your `.csproj` file:

```xml theme={null}
<!-- Android binding -->
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">
  <ProjectReference Include="path/to/Userpilot.Android.Binding/Userpilot.Android.Binding.csproj" />
</ItemGroup>

<!-- iOS binding -->
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'ios'">
  <ProjectReference Include="path/to/Userpilot.MaciOS.Binding/Userpilot.MaciOS.Binding.csproj" />
</ItemGroup>
```

For **Android**, add the required NuGet dependencies:

```xml theme={null}
<ItemGroup Condition="$([MSBuild]::GetTargetPlatformIdentifier('$(TargetFramework)')) == 'android'">
  <!-- Firebase Messaging — provides Firebase infrastructure classes.
       The native Userpilot SDK handles the messaging service, push display, and
       permission requests. This NuGet provides the underlying Firebase classes. -->
  <PackageReference Include="Xamarin.Firebase.Messaging" Version="124.1.1" />

  <!-- Required by native SDK (material components) -->
  <PackageReference Include="Xamarin.Google.Android.Material" Version="1.12.0.5" />
  <PackageReference Include="Xamarin.Kotlin.StdLib" Version="2.2.0.1" />

  <!-- ViewBinding - required by Userpilot SDK for UI layout inflation -->
  <PackageReference Include="Xamarin.AndroidX.DataBinding.ViewBinding" Version="8.5.0.1" />
</ItemGroup>
```

***

## Initialize the SDK

Initialize Userpilot during your app's launch sequence. Replace `<APP_TOKEN>` with your Application Token from the [Environments Page](https://run.userpilot.io/environment).

### iOS

```csharp theme={null}
bool success = Userpilot.UserpilotSdk.Setup(
    token: "<APP_TOKEN>",
    isLoggingEnabled: true,
    isDisableRequestPushPermission: false
);
```

### Android

```csharp theme={null}
var context = Android.App.Application.Context;

bool success = Userpilot.UserpilotSdk.Setup(
    context,
    token: "<APP_TOKEN>",
    isLoggingEnabled: true,
    isUseInAppBrowserEnabled: false,
    isDisableRequestPushNotificationsPermissions: false
);
```

### Cross-Platform Example

```csharp theme={null}
var token = "<APP_TOKEN>";

#if ANDROID
    var context = Android.App.Application.Context;
    bool success = Userpilot.UserpilotSdk.Setup(
        context, token,
        isLoggingEnabled: true,
        isUseInAppBrowserEnabled: false,
        isDisableRequestPushNotificationsPermissions: false
    );
#elif IOS
    bool success = Userpilot.UserpilotSdk.Setup(
        token,
        isLoggingEnabled: true,
        isDisableRequestPushPermission: false
    );
#endif
```

| **Parameter**                               | **Type**  | **Description**                                                                                                                |
| ------------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `logging`                                   | `Boolean` | Enable or disable logs for the SDK.<br /><br />**Default: false**                                                              |
| `disableRequestPushNotificationsPermission` | `Boolean` | Disable push notifications permission request by the SDK.<br /><br />**Default: false**                                        |
| `useInAppBrowser`                           | `Boolean` | Determines whether to open URLs inside CustomTabsIntent or use the system browser. Android only.<br /><br />**Default: false** |

***

## Identify Users (Required)

Identify unique users and companies (groups of users) alongside their properties. Once identified, all subsequent tracked events and screens will be attributed to that user.

<Warning>
  **Important**

  It's crucial to call the Userpilot identify function; without it, Userpilot won't be able to recognize your users, and mobile content won't be displayed to them.
</Warning>

**Recommended Usage:**

* **On user authentication (login):** Immediately call `Identify` when a user signs in.
* **On app launch for authenticated users:** If the user has a valid session, call `Identify` at app launch.
* **Upon property updates:** Whenever user or company properties change.

```csharp theme={null}
var userProperties = System.Text.Json.JsonSerializer.Serialize(new
{
    name = "John Doe",
    email = "user@example.com",
    created_at = "2019-10-17",
    role = "Admin"
});

var companyProperties = System.Text.Json.JsonSerializer.Serialize(new
{
    id = "<COMPANY_ID>",
    name = "Acme Labs",
    created_at = "2019-10-17",
    plan = "Free"
});

bool success = Userpilot.UserpilotSdk.Identify("<USER_ID>", userProperties, companyProperties);
```

**Properties Guidelines**

* The `id` key is required in company properties to identify a unique company.
* Userpilot supports String, Numeric, and Date types.
* Send date values in ISO8601 format.
* If you plan to use Userpilot's localization features, pass the user property `locale_code` with a value that adheres to ISO 639-1 format.
* Userpilot's reserved properties have pre-determined types and improve the profiles interface in the dashboard:
  * Use key `email` to pass the user's email.
  * Use key `name` to pass the user's or company's name.
  * Use key `created_at` to pass the user's or company's signup date.

<Tip>
  **Notes**

  * Make sure your User ID source is consistent across all platform installations (Web, Android, and iOS).
  * While properties are optional, they are essential for Userpilot's segmentation capabilities.
</Tip>

## Track Screens (Required)

Tracking screens is crucial for unlocking Userpilot's core engagement and analytics capabilities. Screen views are used to trigger eligible in-app experiences, improve targeting, and provide context for analytics by associating subsequent events with the currently active screen.

```csharp theme={null}
Userpilot.UserpilotSdk.Screen("Profile");
```

## Track Events

Log any meaningful action the user performs. Events can be button clicks, form submissions, or any custom activity you want to analyze. Optionally, you can pass metadata as a JSON string.

```csharp theme={null}
var properties = System.Text.Json.JsonSerializer.Serialize(new
{
    itemId = "sku_456",
    price = 29.99
});

Userpilot.UserpilotSdk.Track("Added to Cart", properties);
```

## Logout

When a user logs out, call `Logout` to clear the current user context. This ensures subsequent events are no longer associated with the previous user.

```csharp theme={null}
Userpilot.UserpilotSdk.Logout();
```

## Anonymous Users

If a user is not authenticated, call `Anonymous` to track events without a user ID. This is useful for pre-signup flows or guest user sessions.

```csharp theme={null}
Userpilot.UserpilotSdk.Anonymous();
```

<Warning>
  Anonymous users are counted towards your Monthly Active Users usage. You should take your account's MAU limit into consideration before applying this API.
</Warning>

## Experiences

Trigger a specific experience programmatically using its ID:

```csharp theme={null}
Userpilot.UserpilotSdk.TriggerExperience("<EXPERIENCE_ID>");
```

End the current active experience:

```csharp theme={null}
Userpilot.UserpilotSdk.EndExperience();
```

<Frame>
  [**For any questions or concerns please reach out to support@userpilot.com**](mailto:support@userpilot.com)
</Frame>