userpilot_flutter 1.0.0
userpilot_flutter: ^1.0.0 copied to clipboard
Plugin package to bridge the native Userpilot SDKs in a Flutter application.
Userpilot Flutter Plugin #
Userpilot Flutter Plugin enables you to capture user insights and deliver personalized in-app experiences in real time. With just a one-time setup, you can immediately begin leveraging Userpilot’s analytics and engagement features to understand user behaviors and guide their journeys in-app.
This document provides a step-by-step walkthrough of the installation and initialization process, as well as instructions on using the SDK’s public methods.
🚀 Getting Started #
Prerequisites #
Android
Your application's build.gradle
must have a compileSdkVersion
of 34+ and minSdkVersion
of 21+, and use Android Gradle Plugin (AGP) 8+.
android {
compileSdkVersion 34
defaultConfig {
minSdkVersion 21
}
}
Due to the SDK usage of Jetpack Compose, it is required to either:
- apply
kotlin-android
plugin in app's build.gradle file.plugins { id 'com.android.application' id 'kotlin-android' }
- OR Update Android Gradle Plugin 8.4.0+
Related Google issue regarding usage of the Jetpack Compose dependency versions 1.6+
iOS
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.
# Podfile
platform :ios, '13.0'
Installation #
Add userpilot_flutter
as a dependency in your pubspec.yaml file.
dependencies:
userpilot_flutter: <latest_version>
Then, install the dependency by running flutter pub get
from the terminal.
Android
Replace FlutterActivity
with FlutterFragmentActivity
in your MainActivity
inside example Android app.
Replace legacy theme Theme.Black.NoTitleBar
with Theme.AppCompat.NoActionBar
in your style inside example Android app.
One Time Setup #
Initializing the SDK
An instance of the Userpilot SDK should be initialized when your app launches.
import 'package:userpilot_flutter/userpilot_flutter.dart';
UserpilotOptions options = UserpilotOptions();
options.logging = true;
options.useInAppBrowser = true;
Userpilot.initialize("ACCOUNT_TOKEN", options);
To use Userpilot, initialize it once in your Application class. This ensures the SDK is ready as soon as your app starts. Update your Application class. Replace <APP_TOKEN> with your Application Token, which can be fetched from your Environments Page.
Identifying Users #
This method is used to identify unique users and companies (groups of users) and set their properties. Once identified, all subsequent tracked events and screens will be attributed to that user.
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.
Method:
// Identify a user
Userpilot.identify(String userId, Map<String, Object>? properties, Map<String, Object>? company);
Example:
userpilot.identify(
"<USER_ID>",
{"name" : "John Doe", "email" to "user@example.com", "created_at" to "2019-10-17", "role" to "Admin"}, {"id" to "<COMPANY_ID>", "name": "Acme Labs", "created_at": "2019-10-17", "plan" to "Free"}
);
Properties Guidelines
- Key
id
is required in company properties, to identify a unique company. - Userpilot supports String, Numeric, and Date types.
- Make sure you’re sending date values in ISO8601 format.
- If you are planning to use Userpilot’s localization features, make sure you are passing user property
locale_code
with a value that adheres to ISO 639-1 format. - Userpilot’s reserved properties’ have pre-determined types and improve 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 signed up date.
- Use key
Notes
- Make sure your User ID source is consistent across all of your platform installations (Web, Android, and iOS).
- While properties are optional, they are essential in Userpilot’s segmentation capabilities. We encourage you to set the properties with the people who are responsible for Userpilot integration.
Tracking 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.
Method:
Userpilot.screen(String title);
Example:
userpilot.screen("Profile");
Tracking 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.
Method:
Userpilot.track(String name, [Map<String, Object>? properties]);
Example:
userpilot.track("Added to Cart", {"itemId" : "sku_456", "price" : 29.99})
Logging Out
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.
Method:
logout()
Example:
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.
Method:
anonymous()
Example:
userpilot.anonymous()
Notes
- Anonymous users are counted towards your Monthly Active Users usage. You should take your account’s MAU limit into consideration before applying this method.
Trigger Experience
Triggers a specific experience programmatically using it's ID. This API allows you to manually initiate an experience within your application.
userpilot.triggerExperience(String experienceId)
To end current active experience
userpilot.endExperience()
SDK callbacks
Userpilot SDK provides three types of callbacks:
- Navigation Listener
- Analytics Listener
- Experience Listener
Navigation Listener is called when a deep link is triggered from an experience or notification. It holds the custom deep link URL to be handled by the client app. Params: url: String
Analytics Listener is called when an event is triggered by the client app. Params: analytic: String value: String properties: Map<String, Any>
Experience Listener is called when an event is triggered by an experience.
onExperienceStateChanged → id: Int, state: String onExperienceStepStateChanged → id: Int, state: String, experienceId: Int, step: Int, totalSteps: Int Note: Both onExperienceStateChanged and onExperienceStepStateChanged events are sent under the key UserpilotExperienceEvent.
StreamSubscription<UserpilotExperience>? experienceSubscription;
StreamSubscription<UserpilotAnalytic>? analyticsSubscription;
StreamSubscription<UserpilotNavigation>? navigationSubscription;
@override
void initState() {
super.initState();
_initializeUserpilot();
experienceSubscription = Userpilot.onExperienceEvent.listen(
_handleExperienceEvent,
onError: _handleError,
);
analyticsSubscription = Userpilot.onAnalyticEvent.listen(
_handleAnalyticsEvent,
onError: _handleError,
);
navigationSubscription = Userpilot.onNavigationEvent.listen(
_handleNavigationEvent,
onError: _handleError,
);
}
@override
void dispose() {
experienceSubscription?.cancel();
analyticsSubscription?.cancel();
navigationSubscription?.cancel();
super.dispose();
}
void _handleExperienceEvent(UserpilotExperience event) {
print('Experience Event: ${event.state}, ID: ${event.id}');
}
void _handleAnalyticsEvent(UserpilotAnalytic event) {
print('Analytics Event: ${event.analytic}, Value: ${event.value}');
}
void _handleNavigationEvent(UserpilotNavigation event) {
print('Navigation Event URI: ${event.uri}');
}
Push Notification #
Userpilot SDK supports handling push notifications to help you deliver targeted messages and enhance user engagement. For setup instructions, and integration details, please refer to the Push Notification Guide.
📝 Documentation #
Full documentation is available at Userpilot
🎬 Examples #
The example
directory in this repository contains full example iOS/Android app to providing references for correct installation and usage of the Userpilot API.
📄 License #
This project is licensed under the MIT License. See LICENSE for more information.