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.
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:
You will also need your Data-Plane URL
. The following screenshot shows the data plane URL for the managed hosting mode:
It would also help if you have the Flutter Development Environment set up on your system.
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.0
Navigate to your Application's root folder and install all the required dependencies with:
flutter pub get
If the AndroidManifest.xml
of your Flutter application contains android:name
attribute in the <application>
tag then please remove it from there and it at <manifest>
tag as following:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"package="YOUR_PACKAGE_NAME"xmlns:tools="http://schemas.android.com/tools"tools:replace="name"android:name="YOUR_APPLICATION_NAME">
Make sure you add both xmlns:tools
& tools:replace
keys in your <manifest>
tag along with android:name
key.
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:
import 'package:rudder_sdk_flutter/RudderClient.dart';
Add the following code somewhere in your application.
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:
Name | Data Type | Required | Description |
|
| Yes | Your Flutter |
|
| No | Contains the RudderStack Client configuration |
Check the Configuring your RudderStack Client section below for a full list of configurable parameters.
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:
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 | Data Type | Required | Description |
|
| Yes | Contains the name of the event you want to track |
|
| No | Contains the extra data properties you want to send along with the event |
|
| No | Contains the extra event options |
We automatically track the following optional events:
Application Installed
Application Updated
Application Opened
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.
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.
On the Android devices, the deviceId
is assigned during the first boot. It remains consistent across the applications and installs. It changes only after factory reset.
On the iOS devices, According to the Apple documentation, if the device has multiple apps from the same vendors, all those apps will be assigned the same deviceId
. If all the applications from a vendor are uninstalled, then on next install the app will be assigned a new deviceId
.
An example 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 | Required | Description |
|
| Yes | Includes the developer identity for the user |
|
| No | Contains information related to the user traits |
|
| No | Extra options for the |
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:
Name | Data Type | Required | Description |
|
| Yes | Name of the screen viewed. |
|
| No | Extra property object that you want to pass along with the |
|
| No | Extra options to be passed along with |
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:
Name | Data Type | Required | Description |
|
| Yes | An ID of the organization with which you want to associate your user |
|
| No | Any other traits of the organization you want to pass along with the |
|
| No | Extra options to be passed along with |
RudderStack doesn't persist the traits for the group across the sessions.
The alias
call associates the user with a new identification.
An example of alias
event is as shown:
RudderClient.alias("new_user_id", options: null);
The alias
method has the following signature:
Name | Data Type | Required | Description |
|
| Yes | The new |
|
| No | Extra options to be passed along with |
We replace the old userId
with the newUserId
and we persist that identification across the sessions.
You can use the reset
method to clear the persisted traits
for the identify
call. This is required for Logout
operations.
RudderClient.reset();
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);
We use the deviceId
as anonymousId
by default. You can use the following method to override and use your own anonymousId
with the SDK.
You need to call setAnonymousId
method before calling getInstance
An example of setting the anonymousId
is as below
RudderClient.setAnonymousId(<ANONYMOUS_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)
On Android
device you need to call setAdvertisingId
method before calling getInstance
An example of how to use setAdvertisingId
is as shown:
RudderClient.setAdvertisingId(<ADVERTISING_ID>);
The id
parameter you pass to the above method is assigned as AAID
if you are on android
device and as IDFA
if you are on a iOS
device.
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>);
You can configure your client based on the following parameters by passing them in the RudderConfigBuilder
object of your RudderClient.getInstance()
call.
Parameter | Type | Description | Default Value |
|
| Controls how much of the log you want to see from the Flutter SDK. |
|
|
| URL of your | |
|
| Number of events in a batch request to the server. |
|
|
| Number of events to be saved in the |
|
|
| Minimum waiting time to flush the events to the server. |
|
|
| It will fetch the config from |
|
|
| Whether SDK will capture application life cycle events automatically. |
|
|
| This 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 |
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 RudderStack Config Generator to host your own Control Plane, then follow this guide and specify controlPlaneUrl
in yourRudderConfig.Builder
that points to your hosted source configuration file.
You shouldn't pass the controlPlaneUrl
parameter during SDK initialization if you are using the dashboard from https://app.rudderstack.com. This parameter is supported only if you are using our open-source RudderStack Config Generator.
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:
NONE
ERROR
WARN
INFO
DEBUG
VERBOSE
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!