> ## 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.

# Flutter Plugin

> Install and configure the Userpilot Flutter Plugin

Install and initialize the Userpilot Flutter Plugin, identify users, track screens and events, and configure optional settings.

The Userpilot Flutter Plugin 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.

***

## Getting Started

### Android Requirements

Your application's `build.gradle` must have a `compileSdk` of 35+ and `minSdk` of 21+, and use Android Gradle Plugin (AGP) 8.6+.

```kotlin theme={null}
android {
    compileSdk 35

    defaultConfig {
        minSdk 21
    }
}
```

Due to the SDK's usage of Jetpack Compose, it is required to either:

1. Apply the `kotlin-android` plugin in your app's `build.gradle` file.

```kotlin theme={null}
plugins {  
    id 'com.android.application' 
    id 'kotlin-android' 
}
```

2. **Or** update to Android Gradle Plugin 8.4.0+.

> [*Related Google issue*](https://issuetracker.google.com/issues/328687152) regarding usage of Jetpack Compose dependency versions 1.6+.

### iOS Requirements

Your application must target iOS 13+ to install the SDK. Update the iOS project `.xcodeproj` to set the deployment target if needed (typically in `iOS/Runner.xcodeproj`). In the application's `Podfile`, include at least this minimum version:

```ruby theme={null}
# Podfile
platform :ios, '13.0'
```

## Installing the Library

Add `userpilot_flutter` as a dependency in your `pubspec.yaml` file. You can fetch the latest version from [pub.dev](https://pub.dev/packages/userpilot_flutter/).

```yaml theme={null}
dependencies:
  userpilot_flutter: <latest_version>
```

Then, install the dependency by running `flutter pub get` from the terminal.

**Notes**

* The Userpilot Flutter plugin now supports Swift Package Manager (SPM) for iOS integration.
* For detailed setup instructions, refer to the [Swift Package Manager guide for Flutter app developers](https://docs.flutter.dev/packages-and-plugins/swift-package-manager/for-app-developers).

**Android Configuration**

* Replace `FlutterActivity` with `FlutterFragmentActivity` in your `MainActivity`.
* Replace legacy theme `Theme.Black.NoTitleBar` with `Theme.AppCompat.NoActionBar` in your style.

## Initialize the SDK

Initialize Userpilot once in your application to ensure the SDK is ready as soon as your app starts. Replace `<APP_TOKEN>` with your Application Token from the [Environments Page](https://run.userpilot.io/environment).

```dart theme={null}
import 'package:userpilot_flutter/userpilot_flutter.dart';

UserpilotOptions options = UserpilotOptions();
options.logging = true;
 
Userpilot.initialize("<APP_TOKEN>", options);
```

## 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 to establish their identity for all future events.
* **On app launch for authenticated users:** If the user has a valid authenticated session, call `identify` at app launch.
* **Upon property updates:** Whenever user or company properties change.

```dart theme={null}
userpilot.identify(
    "<USER_ID>", 
    {
        "name": "John Doe",
        "email": "user@example.com", 
        "created_at": "2019-10-17", 
        "role": "Admin"
    },   
    {
        "id": "<COMPANY_ID>",
        "name": "Acme Labs", 
        "created_at": "2019-10-17", 
        "plan": "Free"
    }
);
```

**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. We encourage you to define properties with the people responsible for Userpilot integration.
</Tip>

## Track Screens (Required)

Calling `screen` is crucial for unlocking Userpilot's core engagement and analytics capabilities. When a user navigates to a particular screen, invoking `screen` records that view and triggers any eligible in-app experiences. Subsequent events are also attributed to the most recently tracked screen, providing context for richer analytical insights. For these reasons, we strongly recommend tracking all of your app's screen views.

```dart theme={null}
userpilot.screen("Profile");
```

## Send 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 with the event to provide specific context.

```dart theme={null}
userpilot.track("Added to Cart", {"itemId": "sku_456", "price": 29.99})
```

## 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.

```dart theme={null}
userpilot.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.

```dart theme={null}
userpilot.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. This API allows you to manually initiate an experience within your application.

```dart theme={null}
userpilot.triggerExperience("<EXPERIENCE_ID>")
```

End the current active experience:

```dart theme={null}
userpilot.endExperience()
```

## Configuration (Optional)

| **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/SFSafariViewController or use the system browser.<br /><br />**Default: false** |

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