Flutter

What is the RudderStack Flutter SDK?

The RudderStack Flutter SDK allows you to track event data from your Flutter app. After integrating this SDK with your app, you will also be able to send the event data to your preferred destination platforms supported by RudderStack.

You can check the SDK's GitHub codebase to get a more hands-on understanding of the SDK's architecture and working.

SDK Setup Requirements

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

• You will need to set up a RudderStack Account.
• Once signed up, your Flutter source writeKey will appear in the Dashboard, as shown:

Adding Flutter SDK

• You will also need your Data-Plane URL. The following screenshot shows the data plane URL for the managed hosting mode:

Data Plane URL

• It would also help if you have the Flutter Development Environment set up on your system.

Installing the RudderStack 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:

Copy
dependencies:
  rudder_sdk_flutter: ^1.0.5

• Navigate to your Application's root folder and install all the required dependencies with:

Copy
flutter pub get

Initializing the RudderStack Client

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

• Make sure to import the SDK wherever you use it with:

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

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

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

Track

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

An example of the track event is as shown:

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:

Identify

We capture deviceId and use that as the anonymousId for identifying the user. It helps to track the users across the application installation. To attach more information to the user, you can use the identify method.

Once you set the identify information to the user, it will also be passed to the successive track or screen calls. To reset the user identification, you can use the reset method.

An example identify event is as shown:

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

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:

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.

An example of group event is as shown:

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 associates the user with a new identification.

An example of alias event is as shown:

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

The alias method has the following signature:

We replace the old userId with the newUserId and we persist 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.

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

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

Enabling / Disabling Events for Specific Destinations

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

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 destination(s) specified in the above snippet to the SDK in two ways:

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

2. Passing the destinations while making any event call:

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

Copy
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

Copy
RudderClient.setAnonymousId(<ANONYMOUS_ID>);

Advertising ID

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

• id : Your Android advertisingId (AAID) (or) Your iOS advertisingId (IDFA)

An example of how to use setAdvertisingId is as shown:

Copy
RudderClient.setAdvertisingId(<ADVERTISING_ID>);

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

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

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 yourRudderConfig.Builder that points to your hosted source configuration file.

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:

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

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

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

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

Contact Us

In case of any queries, you can always contact us, or feel free to open an issue on our GitHub Issues page in case of any discrepancy. You can also start a conversation on our Slack channel; we will be happy to talk to you!