IMPORTANT: This version of the Flutter SDK will soon be deprecated. We highly recommend upgrading to the latest SDK version by going to our GitHub repository. For the latest documentation, refer to this guide.
Github Badge

SDK setup requirements

To set up the RudderStack Flutter SDK, the prerequisites are as mentioned below:

Flutter source write key
  • You will also need a data plane URL. Refer to the Glossary for more information on the data plane URL and where to find it.
  • It is also recommended to set up the Flutter development environment in your system.
Starting from v1.0.2, the RudderStack Flutter SDK is migrated to Null Safety.

Installing the Flutter SDK

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

To add the SDK as a dependency, perform the following steps:

  • Open pubspec.yaml and add rudder_sdk_flutter under dependencies section:
dependencies:
rudder_sdk_flutter: ^1.0.5
  • Navigate to your Application's root folder and install all the required dependencies with:
flutter pub get

Initializing the RudderStack client

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

  • To import the SDK, refer to the following snippet:
import 'package:rudder_sdk_flutter/RudderClient.dart';
import 'package:rudder_sdk_flutter/RudderConfig.dart';
import 'package:rudder_sdk_flutter/RudderLogger.dart';
  • Add the following code somewhere in your application.
RudderLogger.init(RudderLogger.VERBOSE);
RudderConfigBuilder builder = RudderConfigBuilder();
builder.withDataPlaneUrl(DATA_PLANE_URL);
builder.withTrackLifecycleEvents(true);
RudderClient.getInstance(WRITE_KEY,config: builder.build());

The setup method has the following signature:

NameData TypeRequiredDescription
writeKeyStringYesYour Flutter source writeKey
configRudderConfigNoContains the RudderStack Client configuration

Check the Configuring your RudderStack client section below for a full list of the configurable parameters.

Track

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

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:

NameData TypeRequiredDescription
nameStringYesContains the name of the event you want to track
propertiesRudderPropertyNoContains the extra data properties you want to send along with the event
optionsRudderOptionNoContains the extra event options

We automatically track the following optional events:

  1. Application Installed
  2. Application Updated
  3. Application Opened
  4. Application Backgrounded

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

Identify

We capture the deviceId and use 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. 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:

NameData TypeRequiredDescription
userIdStringYesIncludes the developer identity for the user
traitsRudderTraitsNoContains information related to the user traits
optionsRudderOptionNoExtra options for the identify event

Screen

You can use the screen call to record whenever the user sees a screen on the mobile device. You can also send some extra properties along with this event.

An example of the screen event is as shown:

RudderProperty screenProperty = new RudderProperty();
screenProperty.put("foo", "bar");
RudderClient.screen("Main Activity",
properties: screenProperty, options: null);

The screen method has the following signature:

NameData TypeRequiredDescription
screenNameStringYesName of the screen viewed.
propertiesRudderPropertyNoExtra property object that you want to pass along with the screen call.
optionsRudderOptionNoExtra options to be passed along with screen event.

Group

The group call associates a user to a specific organization.

An example of group event is as shown:

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:

NameData TypeRequiredDescription
groupIdStringYesAn ID of the organization with which you want to associate your user
groupTraitsRudderTraitsNoAny other traits of the organization you want to pass along with the group call.
optionsRudderOptionNoExtra options to be passed along with group event.

RudderStack does not persist the traits for the group 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 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:

NameData TypeRequiredDescription
newIdStringYesThe new userId you want to assign to the user
optionsRudderOptionNoExtra options to be passed along with alias event.

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

Reset

You can use the reset method to clear the persisted traits for the identify call. This is required for Logout operations.

RudderClient.reset();

Enabling/disabling user tracking via the optOut API (GDPR Support)

RudderStack gives the users (e.g., 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.

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 should exactly match the names as listed here.

You can pass the destination(s) specified in the above snippet to the SDK in two ways:

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.getInstance(WRITE_KEY,
config: builder.build(),options: options);

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 standard userId in your identify calls. We add those values under context.externalId. The following code snippet shows a way to add externalId to your identify request.

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

Anonymous ID

We use the deviceId as anonymousId by default. You can use the following method to override and use your own anonymousId with the SDK.

An example of setting the anonymousId is as below

RudderClient.putAnonymousId(<ANONYMOUS_ID>);

Advertising ID

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

  • 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

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

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

RudderClient.putDeviceToken(<DEVICE_TOKEN>);

Configuring your RudderStack client

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

ParameterTypeDescriptionDefault Value
logLevelintControls how much of the log you want to see from the Flutter SDK.RudderLogger.RudderLogLevel.NONE
endPointUristringYour data plane URL.https://hosted.rudderlabs.com
flushQueueSizeintNumber of events in a batch request to the server.30
dbThresholdCountintNumber of events to be saved in the SQLite database. Once the limit is reached, older events are deleted from the DB.10000
sleepTimeoutintMinimum waiting time to flush the events to the server.10 seconds
configRefreshIntervalintFetches the config from the dashboard after this specified time.2 hours
trackLifecycleEventsbooleanWhether SDK will capture application life cycle events automatically.true
controlPlaneUrlstringThis parameter should be changed only if you are self-hosting the control plane. Check the section Self-hosted control plane below for more information. The SDK will add /sourceConfig along with this URL to fetch the configuration.https://api.rudderlabs.com

Self-hosted control plane

If 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 shouldn't pass the controlPlaneUrl parameter during SDK initialization if you are using the RudderStack dashboard from https://app.rudderstack.com. This parameter is supported only if you are using our open-source Control Plane Lite utility to set up your own control plane.

Debugging

If you run into any issues regarding the RudderStack Flutter SDK, you can turn on the VERBOSE or DEBUG logging to find out what the issue is.

First, make sure you import RudderLogger with the below command:

import 'package:rudder_sdk_flutter/RudderLogger.dart';

Then to turn on the logging, change your RudderClient initialization to the following:

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

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

  1. NONE
  2. ERROR
  3. WARN
  4. INFO
  5. DEBUG
  6. 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"]);

Contact us

For more information on the topics covered on this page, email us or start a conversation in our Slack community.