Use RudderStack’s Flutter SDK to send events to various destinations.

RudderStack’s Flutter SDK lets you track and send the events from your Flutter apps to the specified destinations.

Github Badge

Refer to the Flutter SDK’s GitHub Repository for the implementation-specific details.

SDK setup requirements

  1. It is recommended to set up the Flutter development environment in your system.
  2. Sign up to RudderStack Cloud.
  3. Set up a Flutter source in the dashboard. You should be able to see the write key for this source:
Flutter source write key

You will also need the data plane URL. Refer to the Dashboard Overview guide for more information on the data plane URL and where to find it.

Installing the RudderStack Flutter SDK

Starting from v1.0.2, the RudderStack Flutter SDK is migrated to Null Safety.

The recommended way to install the Flutter SDK is through pub. Follow these steps to add the SDK as a dependency:

  1. Open pubspec.yaml and add rudder_sdk_flutter under dependencies section:
  rudder_sdk_flutter: ^2.0.1
  1. Navigate to your application’s root folder and install all required dependencies with the following command:
flutter pub get

Installing the SDK for the web

To install and use the Flutter SDK in your web app, follow the above steps to add the Flutter SDK. Additionally, you need to install the RudderStack script in the <head> section of your web page.

Not all Flutter SDK APIs are applicable for the web. The following APIs will have no effect on your web app:

Initializing the RudderStack client

After adding the SDK as a dependency, you need to set up the SDK.

  1. To import the SDK, use the following snippet:
import 'package:rudder_sdk_flutter_platform_interface/platform.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';
  1. Then, add the following code snippet in your application:
final RudderController rudderClient = RudderController.instance;
RudderConfigBuilder builder = RudderConfigBuilder();
rudderClient.initialize(<WRITE_KEY>,config: builder.build());

The initialize method has the following signature:

writeKeyStringRequiredYour Flutter source write key.
configRudderConfigOptionalContains the RudderStack client configuration.

Self-hosted control plane

If you are self-hosting RudderStack and using the Control plane lite utility to host your own control plane, then follow the steps in this section and specify the controlPlaneUrl parameter in your RudderConfigBuilder that points to the hosted configuration file.

You should not pass the controlPlaneUrl parameter during SDK initialization if you are using RudderStack Cloud. This parameter is supported only if you are using the open source Control plane lite utility to set up your own control plane.

SDK initialization options

You can configure your client based on the following parameters by passing them in the RudderConfigBuilder object of your rudderClient.initialize() call.

Default value
dataPlaneUrlStringYour data plane URL.https://hosted.rudderlabs.com
flushQueueSizeIntegerNumber of events in a batch request to the server.30
isDebugBooleanWhen enabled, sets the log level as debug. For more information, refer to the Debugging section below.false
logLevelIntegerControls the logs you want to see from the Flutter SDK.RudderLogger.RudderLogLevel.NONE
mobileConfigObjectRefer to the mobileConfig parameters section below.-
webConfigObjectRefer to the webConfig parameters section below.-
controlPlaneUrlStringThis parameter should be changed only if you are self-hosting the control plane. Refer to the Self-hosted control plane section for more information. The SDK will add /sourceConfig along with this URL to fetch the configuration.https://api.rudderlabs.com

mobileConfig parameters

mobileConfig contains only the mobile-specific configuration parameters for the Flutter SDK.

ParameterTypeDescriptionDefault value
dbThresholdCountIntegerNumber of events to be saved in the SQLite database. Once this limit is reached, the older events are deleted from the database.10000
sleepTimeoutIntegerMinimum waiting time to flush the events to the server.10 seconds
configRefreshIntervalIntegerFetches the config from the dashboard after this specified time.2
trackLifecycleEventsBooleanDetermines if the SDK will capture application life cycle events automatically.true
autoCollectAdvertIdBooleanDetermines if the SDK will collect the advertisement ID.false
recordScreenViewsBooleanWhen enabled, the SDK automatically records the screens viewed by the user.false

webConfig parameters

webConfig holds the configuration parameters for using the SDK in the Flutter web applications.

ParameterTypeDescriptionDefault value
destSDKBaseURLStringThe SDK loads the integration from this path.
useBeaconBooleanIf enabled, the SDK sends the event payloads via the navigator.sendBeacon() utilityFalse
secureCookieBooleanIf enabled, the SDK sends the cookie to the storage backend via HTTPS.False
loadIntegrationBooleanIf disabled, the destination SDKs are not fetched by the SDK.True
cookieConsentManagersObjectRefer to the cookieConsentManager section for more information.-
beaconFlushQueueIntervalIntegerThe SDK flushes the queue after this time interval (in milliseconds).600000
maxBeaconItemsIntegerThe SDK flushes the queue when this number of events is reached.10
maxItemsIntegerMaximum number of events kept in the storage.100
maxAttemptsIntegerMaximum number of attempts the SDK makes to send the event to the destination.10
backoffFactorIntegerRefers to the exponential base.2
minRetryDelayIntegerThe minimum delay expected before the SDK retries sending an event (in ms)1000
maxRetryDelayIntegerThe upper limit on the maximum delay for retrying an event (in ms)360000


The identify call lets you identify a visiting user and associate them to their actions. It also lets you record the traits about them like their name, email address, etc.

For unidentified users, RudderStack captures the deviceId and uses that as the anonymousId for identification. This way, you can track the users across the application installation. To attach more information to the user, you can use the identify method.

How RudderStack sets deviceId on Android and iOS

  • On the Android devices, the deviceId is assigned during the first boot. It remains consistent across the applications and installs. This can be changed only after factory resetting the device.
  • According to the Apple documentation, if the iOS device has multiple apps from the same vendor, all apps are assigned the same deviceId. If all applications from a vendor are uninstalled and then reinstalled, then they are assigned a new deviceId.

Once a user is identified, RudderStack persists all user information and passes it to the successive track or screen calls. To reset the user identification, you can use the reset method.

A sample identify event is as shown:

RudderTraits traits = RudderTraits();
traits.putBirthdayDate(new DateTime.now());

Address address = Address();

traits.put("boolean", true);
traits.put("integer", 50);
traits.put("float", 120.4);
traits.put("long", 1234);
traits.put("string", "hello");
traits.put("date", new DateTime.now().millisecondsSinceEpoch);

rudderClient.identify("1hKOmRA4GRlm", traits: traits, options: null);

The identify method has the following signature:

NameData TypePresenceDescription
userIdStringRequiredIncludes the developer identity for the user.
traitsRudderTraitsOptionalContains information related to the user traits.
optionsRudderOptionOptionalExtra options for the identify event.

Obtaining user traits after making an identify call

You can obtain the user traits after making an identify call as shown:

Map context = await rudderClient.getRudderContext();

For the web apps, the getRudderContext API returns the user’s traits and anonymousId.


The track call lets you track the user actions along with any properties associated with them.

A sample track event is shown below:

RudderProperty property = RudderProperty();
property.put("test_key_1", "test_key_1");
RudderProperty childProperty = RudderProperty();
childProperty.put("test_child_key_1", "test_child_value_1");
rudderClient.track("test_track_event", properties: property);

The track method has the following signature:

nameStringRequiredContains the name of the event you want to track.
propertiesRudderPropertyOptionalContains the extra properties you want to send along with the event.
optionsRudderOptionOptionalContains the extra event options.

Tracking lifecycle events

RudderStack automatically tracks the following optional application lifecycle events:

You can disable these events by calling withTrackLifeCycleEvents(false) in the RudderConfigBuilder object while initializing the SDK. However, it is highly recommended to keep them enabled.


The screen call is the mobile equivalent of the page call. It lets you record the screen views on your mobile app along with other relevant information about the screen.

For the web apps, the SDK internally calls the page API with the provided parameters.

A sample screen event is as shown:

RudderProperty screenProperty = RudderProperty();
  screenProperty.put("browser", "Chrome");
  screenProperty.put("device", "Macbook Pro");
  rudderClient.screen("Walmart Cart",
      category: "home",
      properties: screenProperty,
      options: null);

The screen method has the following signature:

screenNameStringRequiredName of the screen viewed by the user.
categoryStringOptionalDefines the page(web) or screen(mobile) category.
propertiesRudderPropertyOptionalExtra property object that you want to pass along with the screen call.
optionsRudderOptionOptionalExtra options to be passed along with screen event.

Automatic screen recording

The recordScreenViews parameter records the screen views of the native Android activities or the iOS view controllers only, and not of the Flutter screen views.

To track the screen views of your Flutter app screens, follow these steps:

  1. Define the routes with their names to the Material App constructor of the entry widget.
  2. Register an instance of the custom navigation observer to the Material App constructor of the entry widget.

The following snippet includes the code for the above two steps:

import 'package:flutter/material.dart';
import 'home_screen.dart';
import 'screen2.dart';
import 'screen3.dart';
import 'my_route_observer.dart';

class MyApp extends StatelessWidget {
  const MyApp({Key? key}) : super(key: key);

  Widget build(BuildContext context) {
    return MaterialApp(
      theme: ThemeData(
        primarySwatch: Colors.blue,
// Step 2. Registering an instance of our custom navigation observer.
      navigatorObservers: [
      home: const HomeScreen(),
// Step 1. Defining the named routes
      routes: {
        'screen2': (context) => const Screen2(),
        'screen3': (context) => const Screen3(),

Future<void> main() async {
  runApp(const MyApp());
  1. Finally, add the below code for the custom navigation observer used above:
import 'package:flutter/material.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';

class MyRouteObserver extends RouteObserver<PageRoute<dynamic>> {
  void didPush(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPush(route, previousRoute);
    if (route is PageRoute && route.settings.name != null) {

  void didPop(Route<dynamic> route, Route<dynamic>? previousRoute) {
    super.didPop(route, previousRoute);
    if (previousRoute is PageRoute && route is PageRoute) {


The group call lets you link an identified user with a group, such as a company, organization, or an account. It also lets you record any custom traits or properties associated with that group.

RudderStack does not persist the group traits across the sessions.

A sample group event is shown below:

RudderTraits groupTraits = RudderTraits();
groupTraits.put("foo", "bar");
groupTraits.put("foo1", "bar1");
    groupTraits: groupTraits, options: null);

The group method has the following signature:

groupIdStringRequiredThe ID of the organization with which you want to associate your user.
groupTraitsRudderTraitsOptionalAny other organization traits you want to pass along with the group call.
optionsRudderOptionOptionalExtra options to be passed along with group event.


The alias call lets you merge different identities of a known user. It is an advanced method that lets you change the tracked user’s ID explicitly. You can use alias for managing the user’s identity in some of the downstream destinations.

When you make an alias call, RudderStack replaces the old user ID with the new user ID and persists this identification across the sessions.

RudderStack supports sending alias events only to select downstream destinations. Refer to the destination-specific documentation for more details.

A sample alias call is as shown:

rudderClient.alias("new_user_id", options: null);

The alias method has the following signature:

newIdStringRequiredThe new userId you want to assign to the user.
optionsRudderOptionOptionalExtra options to be passed along with alias event.


You can use the reset method to clear the persisted traits for the identify call. This is required for scenarios where the user logs out of a session.


Enabling/disabling user tracking (GDPR support)

This functionality is not available for the web.

RudderStack gives the users (for example, an EU user) the ability to opt out of tracking any user activity until the user gives their consent. You can do this by leveraging RudderStack’s optOut API.

The optOut API takes true or false as a Boolean value to enable or disable tracking user activities. This flag persists across device reboots.

The optOut API is available in the Flutter SDK starting from version 1.0.6.

The following snippet highlights the use of the optOut API to disable user tracking:


Once the user grants their consent, you can enable user tracking once again by using the optOut API with false as a parameter sent to it:


Filtering events

When sending events to a destination via device mode, you can explicitly specify the events to be discarded or allowed to flow through by allowlisting or denylisting them.

Refer to the Client-side Event Filtering guide for more information on this feature.

Enabling/disabling events for specific destinations

The Flutter SDK lets you enable or disable sending events to a specific destination or all destinations connected to a source. You can specify these destinations by creating an object as shown in the following snippet:

RudderOption options = new RudderOption();
// default value for `All` is true
options.putIntegration("All", false);
// specifying destination by its display name
options.putIntegration("Mixpanel", false);
// specifying destination by its Factory object
options.putIntegrationWithFactory(Appcenter(), true);

In the above snippet, the keyword All represents all destinations connected to a source. By default, its value is set to true.

Make sure the destination names that you pass while specifying the destinations match exactly with the names listed in the RudderStack dashboard.

You can pass the destinations to the SDK in the following two ways:

Method 1. Passing destinations while initializing the SDK

This is helpful when you want to enable/disable sending the events across all event calls made using the SDK to the specified destination(s).

                    config: builder.build(),options: options);

Method 2. Passing destinations while making event calls

This approach is helpful when you want to enable/disable sending only a particular event to the specified destination(s) or if you want to override the specified destinations passed with the SDK initialization for a particular event.

RudderProperty property = RudderProperty();
property.put("test_key_1", "test_key_1");
rudderClient.track("test_track_event", properties: property, options: options);
If you specify the destinations both while initializing the SDK and while making an event call, then the SDK considers only the destinations specified at the event level.

External ID

You can pass your custom userId along with the standard userId in your identify calls. RudderStack adds those values under context.externalId.

The following code snippet highlights how to add externalId to your identify event:

RudderOption option = RudderOption();
option.putExternalId("externalId", "some_external_id_1");
rudderClient.identify("testUserId", options: option);

Setting your own anonymousId using putAnonymousId

By default, RudderStack uses the deviceId as the user’s anonymousId. Use the following method to override and set your own anonymousId:


Setting the advertisement ID

This functionality is not available for the web.

RudderStack collects the advertisement ID only if autoCollectAdvertId is set to true during the SDK initialization:

final RudderController rudderClient = RudderController.instance;
MobileConfig mobileConfig = MobileConfig(autoCollectAdvertId: true);
RudderConfigBuilder builder = RudderConfigBuilder();
rudderClient.initialize(<WRITE_KEY>,config: builder.build());

You can use the putAdvertisingId method to pass your Android AAID and iOS IDFA respectively. The putAdvertisingId method accepts a string argument as described below:

  • <ADVERTISING_ID> : Your Android advertisingId (AAID) (or) your iOS advertisingId (IDFA).

An example of how to use putAdvertisingId is as shown:


Setting the device token

This functionality is not available for the web.

You can use your device token to pass push notifications to the destinations that support them. RudderStack sets this token under context.device.token. To set a custom device token, the SDK supports the putDeviceToken method.

An example of setting a custom device token is shown below:



If you run into any issues when using the Flutter SDK, you can turn on the VERBOSE or DEBUG logging to determine the issue. To do so, follow these steps:

  1. First, make sure you import RudderLogger by running the following command:
import 'package:rudder_sdk_flutter/RudderLogger.dart';
  1. Then, turn on the logging by changing your rudderClient initialization as shown:
RudderConfigBuilder builder = RudderConfigBuilder();
                          config: builder.build());

You can set the log level to one of the following values:

  • NONE
  • WARN
  • INFO


How do I get the user traits after making an identify call?

You can get the user traits after making an identify call in the following way:

Map context = await rudderClient.getRudderContext();

For the web apps, the getRudderContext API returns the user traits and anonymousId.

Do I need to add anything to my Android ProGuard rules?

If you are facing any event delivery issues in your production environment, verify if you have added the following line in your ProGuard rules:

-keep class com.rudderstack.android.** { *; }

Questions? Contact us by email or on Slack