Flutter

The RudderStack Flutter SDK lets you track event data from your Flutter applications and send it to your specified destinations via RudderStack.

Refer to the Flutter GitHub Repository to get a more hands-on understanding of the SDK and the related codebase.

SDK setup requirements

To set up the RudderStack Flutter SDK, you need the following prerequisites:

You will need to set up a RudderStack Account.
Once signed up, you need to set up a Flutter source in the dashboard. You should then see a Write Key for this source, as shown:

You will also need a data plane URL.

For more information on the data plane URL and where to get it, refer to this RudderStack Dashboard Overview section.

It is also recommended to set up the Flutter development environment in your system.

The RudderStack Flutter SDK is migrated to Null Safety starting from version 1.0.2.

Installing the RudderStack Flutter SDK

The recommended way to install the Flutter SDK is through pub.

Follow the steps below to add the SDK as a dependency:

Open pubspec.yaml and add rudder_sdk_flutter under dependencies section, as shown:

dependencies:
  rudder_sdk_flutter: ^2.0.1

Navigate to your application's root folder and install all the 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 the APIs provided in the Flutter SDK are applicable for the web. Refer to the SDK API unavailable for web section for more information.

Initializing the RudderStack client

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

To import the SDK, use the following snippet:

import 'package:rudder_sdk_flutter_platform_interface/platform.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';

Then, add the following code snippet in your application:

final RudderController rudderClient = RudderController.instance;
RudderLogger.init(RudderLogger.VERBOSE);
RudderConfigBuilder builder = RudderConfigBuilder();
builder.withDataPlaneUrl(<DATA_PLANE_URL>);
builder.withTrackLifecycleEvents(true);
rudderClient.initialize(<WRITE_KEY>,config: builder.build());

The initialize method has the following signature:

Name	Type	Presence	Description
`writeKey`	String	Required	Your Flutter source write key.
`config`	`RudderConfig`	Optional	Contains the RudderStack client configuration.

Refer to the Configuring your RudderStack client section below for a complete list of the configurable parameters.

Configuring your RudderStack client

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

Parameter	Type	Description	Default value
`dataPlaneUrl`	String	Your data plane URL.	`https://hosted.rudderlabs.com`
`flushQueueSize`	Integer	Number of events in a batch request to the server.	`30`
`isDebug`	Boolean	When enabled, sets the log level as `debug`. For more information, refer to the Debugging section below.	`false`
`logLevel`	Integer	Controls the logs you want to see from the Flutter SDK.	`RudderLogger.RudderLogLevel.NONE`
`mobileConfig`	Object	Refer to the `mobileConfig` parameters section below.	-
`webConfig`	Object	Refer to the `webConfig` parameters section below.	-
`controlPlaneUrl`	String	This parameter should be changed only if you are self-hosting the control plane. Check the section Self-hosted control plane section below 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.

Parameter	Type	Description	Default value
`dbThresholdCount`	Integer	Number of events to be saved in the SQLite database. Once this limit is reached, the older events are deleted from the database.	`10000`
`sleepTimeout`	Integer	Minimum waiting time to flush the events to the server.	`10 seconds`
`configRefreshInterval`	Integer	Fetches the config from the dashboard after this specified time.	`2`
`trackLifecycleEvents`	Boolean	Determines if the SDK will capture application life cycle events automatically.	`true`
`autoCollectAdvertId`	Boolean	Determines if the SDK will collect the advertisement ID.	`false`
`recordScreenViews`	Boolean	When 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.

Parameter	Type	Description	Default value
`destSDKBaseURL`	String	The SDK loads the integration from this path.
`useBeacon`	Boolean	If enabled, the SDK sends the event payloads via the `navigator.sendBeacon()` utility	`False`
`secureCookie`	Boolean	If enabled, the SDK sends the cookie to the storage backend via HTTPS.	`False`
`loadIntegration`	Boolean	If disabled, the destination SDKs are not fetched by the SDK.	`True`
`cookieConsentManagers`	Object	Refer to the cookieConsentManager section for more information.	-
`beaconFlushQueueInterval`	Integer	The SDK flushes the queue after this time interval (in milliseconds).	600000
`maxBeaconItems`	Integer	The SDK flushes the queue when this number of events is reached.	10
`maxItems`	Integer	Maximum number of events kept in the storage.	100
`maxAttempts`	Integer	Maximum number of attempts the SDK makes to send the event to the destination.	10
`backoffFactor`	Integer	Refers to the exponential base.	2
`minRetryDelay`	Integer	The minimum delay expected before the SDK retries sending an event (in ms)	1000
`maxRetryDelay`	Integer	The upper limit on the maximum delay for retrying an event (in ms)	360000

Identify

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

For a detailed explanation of the identify call, refer to the RudderStack API Specification guide.

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

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 a factory reset of the device.

According to the Apple documentation, if the iOS device has multiple apps from the same vendor, all the apps will be assigned the same deviceId. If all the applications from a vendor are uninstalled and then reinstalled, then they will be assigned a new deviceId.

A sample identify event is as shown:

RudderTraits traits = RudderTraits();
traits.putBirthdayDate(new DateTime.now());
traits.putEmail("abc@123.com");
traits.putFirstName("First");
traits.putLastName("Last");
traits.putGender("m");
traits.putPhone("5555555555");

Address address = Address();
address.putCity("City");
address.putCountry("USA");
traits.putAddress(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("test_user_id", traits: traits, options: null);

The identify method has the following signature:

Name	Data Type	Presence	Description
`userId`	String	Required	Includes the developer identity for the user.
`traits`	`RudderTraits`	Optional	Contains information related to the user traits.
`options`	`RudderOption`	Optional	Extra 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();
print(context["traits"]);

For web apps, the getRudderContext API returns the user traits and anonymous ID only.

Track

You can record the users' activity through the track method. Each user action is called an event.

For a detailed explanation of the track call, refer to the RudderStack API Specification guide.

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");
property.put("test_key_2",childProperty);
rudderClient.track("test_track_event", properties: property);

The track method has the following signature:

Name	Type	Presence	Description
`name`	String	Required	Contains the name of the event you want to track.
`properties`	`RudderProperty`	Optional	Contains the extra properties you want to send along with the event.
`options`	`RudderOption`	Optional	Contains the extra event options.

RudderStack automatically tracks the following optional events:

Application Installed
Application Updated
Application Opened
Application Backgrounded

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

Screen

You can use the screen call to record whenever the user views a screen on their mobile device along with the properties associated with that event.

For a detailed explanation of the screen call, refer to the RudderStack API Specification guide.

For 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:

Name	Type	Presence	Description
`screenName`	String	Required	Name of the screen viewed by the user.
`category`	String	Optional	Defines the page(web) or screen(mobile) category.
`properties`	`RudderProperty`	Optional	Extra property object that you want to pass along with the `screen` call.
`options`	`RudderOption`	Optional	Extra options to be passed along with `screen` event.

Group

The group call associates a user to a specific organization.

For a detailed explanation of the group call, refer to the RudderStack API Specification guide.

A sample group event is shown below:

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

The group method has the following signature:

Name	Type	Presence	Description
`groupId`	String	Required	The ID of the organization with which you want to associate your user.
`groupTraits`	`RudderTraits`	Optional	Any other organization traits you want to pass along with the `group` call.
`options`	`RudderOption`	Optional	Extra options to be passed along with `group` event.

RudderStack doesn't persist the group traits across the sessions.

Alias

The alias call lets you merge different identities of a known user.

alias is an advanced method that lets you change the tracked user's ID explicitly. This method is useful when managing identities for some of the downstream destinations.

For a detailed explanation of the alias call, refer to the RudderStack API Specification guide.

A sample alias call is as shown:

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

The alias method has the following signature:

Name	Type	Presence	Description
`newId`	String	Required	The new `userId` you want to assign to the user.
`options`	`RudderOption`	Optional	Extra options to be passed along with `alias` event.

RudderStack replaces the old userId with the newUserId and persists this identification across the sessions.

Reset

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.

rudderClient.reset();

This functionality is not available for the web. For more information, refer to the SDK API unavailable for web section below.

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 following snippet highlights the use of the optOut API to disable user tracking:

rudderClient.optOut(true);

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, as shown:

rudderClient.optOut(false);

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

Filtering events

When sending events to a destination via the 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 the 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);

The keyword All in the above snippet represents all the destinations connected to a source. Its value is set to true by default.

Make sure the destination names that you pass while specifying the destinations exactly match the names as 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 the event calls made using the SDK to the specified destination(s).

rudderClient.initialize(<WRITE_KEY>,
                    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 as well as while making an event call, then the destinations specified at the event level only will be considered.

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 deviceId as anonymousId. You can use the following method to override and set your own anonymousId with the SDK, as shown:

rudderClient.putAnonymousId(<ANONYMOUS_ID>);

Setting the advertisement ID

This functionality is not available for the web. For more information, refer to the SDK API unavailable for web section below.

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

final RudderController rudderClient = RudderController.instance;
MobileConfig mobileConfig = MobileConfig(autoCollectAdvertId: true);
RudderLogger.init(RudderLogger.VERBOSE);
RudderConfigBuilder builder = RudderConfigBuilder();
builder.withDataPlaneUrl(<DATA_PLANE_URL>);
builder.withTrackLifecycleEvents(true);
rudderClient.initialize(<WRITE_KEY>,config: builder.build());

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

id : Your Android advertisingId (AAID) (or) your iOS advertisingId (IDFA).

An example of how to use putAdvertisingId is as shown:

rudderClient.putAdvertisingId(<ADVERTISING_ID>);

The id parameter that you pass in the putAdvertisingId method is assigned as the AAID if you are on an Android device, and as the IDFA if you are on an iOS device.

Setting the device token

This functionality is not available for the web. For more information, refer to the SDK API unavailable for web section below.

You can pass your device token for push notifications to be passed to the destinations which support the Push Notification feature. RudderStack sets the token under context.device.token.

An example of setting the device token is as shown below:

rudderClient.putDeviceToken(<DEVICE_TOKEN>);

Self-hosted control plane

In case you are using a device mode destination like Adjust, Firebase, etc., the Flutter SDK needs to fetch the required configuration from the control plane. If you are using the Control Plane Lite utility to host your own control plane, then follow this guide and specify controlPlaneUrl in your RudderConfig.Builder that points to your hosted source 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 API unavailable for web

The following Flutter SDK API are not available/applicable for the web:

optOut
putDeviceToken
putAdvertisingId

Calling these API in your web app will have no effect.

Debugging

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:

First, make sure you import RudderLogger by running the following command:

import 'package:rudder_sdk_flutter/RudderLogger.dart';

Then, turn on the logging by changing your rudderClient initialization as shown:

RudderConfigBuilder builder = RudderConfigBuilder();
builder.withDataPlaneUrl(DATA_PLANE_URL);
builder.withLogLevel(RudderLogger.VERBOSE);
rudderClient.initialize(WRITE_KEY,
                          config: builder.build());

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

NONE
ERROR
WARN
INFO
DEBUG
VERBOSE

FAQs

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();
print(context["traits"]);

For web apps, the getRudderContext API returns the user traits and anonymous ID only.

Contact us

For queries on any of the sections covered in this guide, you can contact us or start a conversation in our Slack community.

If you come across any issues while using the Flutter SDK, you can also open an issue on our GitHub issues page.

SDK setup requirements

Installing the RudderStack Flutter SDK

Installing the SDK for the web

Initializing the RudderStack client

Configuring your RudderStack client

mobileConfig parameters

webConfig parameters

Identify

Obtaining user traits after making an `identify` call

Track

Screen

Group

Alias

Reset

Filtering events

Enabling/disabling events for specific destinations

Method 1. Passing destinations while initializing the SDK

Method 2. Passing destinations while making event calls

External ID

Setting your own `anonymousId` using `putAnonymousId`

Setting the advertisement ID

Setting the device token

Self-hosted control plane

SDK API unavailable for web

Debugging

FAQs

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

Contact us

Flutter SDK v1

Contents

SDK setup requirements

Installing the RudderStack Flutter SDK

Installing the SDK for the web

Initializing the RudderStack client

Configuring your RudderStack client

mobileConfig parameters

webConfig parameters

Identify

Obtaining user traits after making an identify call

Track

Screen

Group

Alias

Reset

Enabling/disabling user tracking (GDPR support)

Filtering events

Enabling/disabling events for specific destinations

Method 1. Passing destinations while initializing the SDK

Method 2. Passing destinations while making event calls

External ID

Setting your own anonymousId using putAnonymousId

Setting the advertisement ID

Setting the device token

Self-hosted control plane

SDK API unavailable for web

Debugging

FAQs

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

Contact us

Flutter

Flutter SDK v1

@media (max-width: 1200px){.css-1x56nmx{display:none;}}Contents

Obtaining user traits after making an `identify` call

Setting your own `anonymousId` using `putAnonymousId`

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

Contents