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

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

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:

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

Copy
dependencies:
  rudder_sdk_flutter: ^1.2.0

2. Navigate to your application's root folder and install all the required dependencies with the following command:

Copy
flutter pub get

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:

Copy
import 'package:rudder_sdk_flutter/RudderClient.dart';
import 'package:rudder_sdk_flutter/RudderConfig.dart';
import 'package:rudder_sdk_flutter/RudderLogger.dart';

2. Then, add the following code snippet in your application:

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

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.

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.

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.

A sample identify event is as shown:

Copy
RudderTraits traits = RudderTraits();
traits.putBirthdayDate(new DateTime.now());
traits.putEmail("abc@123.com");
traits.putFirstName("Alex");
traits.putLastName("Keener");
traits.putGender("M");
traits.putPhone("1234567890");

Address address = Address();
address.putCity("New Orleans");
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:

Obtaining user traits after making an identify call

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

Copy
Map context = await rudderClient.getRudderContext();
print(context["traits"]);

Track

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

A sample track event is shown below:

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

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.

A sample screen event is as shown:

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

The screen method has the following signature:

Group

The group call associates a user to a specific organization.

A sample group event is shown below:

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

Alias

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

A sample alias call is as shown:

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

The alias method has the following signature:

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.

Copy
rudderClient.reset();

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

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:

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

Copy
rudderClient.optOut(false);

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.

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:

Copy
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);

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

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

Copy
RudderProperty property = RudderProperty();
property.put("test_key_1", "test_key_1");
rudderClient.track("test_track_event", properties: property, options: options);

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:

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

Copy
rudderClient.putAnonymousId(<ANONYMOUS_ID>);

Setting the advertisement ID

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

Copy
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 listed below:

• id : Your Android advertisement ID (AAID) or your iOS advertisement ID (IDFA).

The following snippet highlights the use of putAdvertisingId():

Copy
rudderClient.putAdvertisingId(<ADVERTISING_ID>);

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. RudderStack sets the token under context.device.token.

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

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

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:

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

Copy
import 'package:rudder_sdk_flutter/RudderLogger.dart';

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

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

Copy
Map context = await rudderClient.getRudderContext();
print(context["traits"]);

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.