Use the RudderStack Flutter SDK to send events from your Flutter applications to various destinations.
12 minute read
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.
It is strongly recommended to update your Flutter SDK to the latest version to get all the features, including web support. Refer to the SDK documentation for more information.
SDK setup requirements
To set up the RudderStack Flutter SDK, you need the following prerequisites:
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
logLevel
Integer
Controls how much of the log you want to see from the Flutter SDK.
RudderLogger.RudderLogLevel.NONE
dataPlaneUrl
String
Your data plane URL.
https://hosted.rudderlabs.com
flushQueueSize
Integer
Number of events in a batch request to the server.
30
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
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
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 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 apps will be assigned the same deviceId. If all applications from a vendor are uninstalled and then reinstalled, then they will be assigned a new deviceId.
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.
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.
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();
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:
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:
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 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 destinations connected to a source. You can specify these destinations by creating an object as shown in the following snippet:
RudderOptionoptions=newRudderOption();// 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 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 event calls made using the SDK to the specified destination(s).
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.
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.
Setting a custom ID
You can pass a custom ID along with the standard userId in your identify calls. RudderStack adds this value under context.externalId.
RudderStack supports passing externalId only in the identify events. You must not pass this ID in other API calls like track, page, etc.
The following snippet shows how to add externalId to your identify event:
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():
rudderClient.putAdvertisingId(<ADVERTISING_ID>);
The id parameter that you pass in the putAdvertisingId method is assigned as the AAID (for Android) or as the IDFA (for iOS).
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:
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 the steps in this section and specify controlPlaneUrl in your RudderConfig.Builder that points to your hosted source configuration file.
Do 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.
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:
Do I need to add anything to my Android ProGuard rules?
If you are facing any event delivery issues in your production environment, verify if you have added the following line in your ProGuard rules:
// Reporter Module
-keepclasscom.rudderstack.android.ruddermetricsreporterandroid.models.LabelEntity{*;}-keepclasscom.rudderstack.android.ruddermetricsreporterandroid.models.MetricEntity{*;}-keepclasscom.rudderstack.android.ruddermetricsreporterandroid.models.ErrorEntity{*;}// Required for the usage off TypeToken class in Utils.converToMap, Utils.convertToList
-keepclasscom.google.gson.reflect.TypeToken{*;}-keepclass* extendscom.google.gson.reflect.TypeToken// Required for the serialization of SourceConfig once it is downloaded.
-keepclasscom.google.gson.internal.LinkedTreeMap{*;}-keepclass* implementsjava.io.Serializable{*;}-keepclasscom.rudderstack.rudderjsonadapter.RudderTypeAdapter{*;}-keepclass* extendscom.rudderstack.rudderjsonadapter.RudderTypeAdapter// Required to ensure the DefaultPersistenceProviderFactory is not removed by Proguard
// and works as expected even when the customer is not using encryption feature.
-dontwarnnet.sqlcipher.Cursor-dontwarnnet.sqlcipher.database.SQLiteDatabase$CursorFactory-dontwarnnet.sqlcipher.database.SQLiteDatabase-dontwarnnet.sqlcipher.database.SQLiteOpenHelper-keepclasscom.rudderstack.android.sdk.core.persistence.DefaultPersistenceProviderFactory{*;}// Required for the usage of annotations across reporter and web modules
-dontwarncom.fasterxml.jackson.annotation.JsonIgnore-dontwarncom.squareup.moshi.Json-dontwarncom.fasterxml.jackson.annotation.JsonProperty// Required for Device Mode Transformations
-keepclasscom.rudderstack.android.sdk.core.TransformationResponse{*;}-keepclasscom.rudderstack.android.sdk.core.TransformationResponseDeserializer{*;}
This site uses cookies to improve your experience while you navigate through the website. Out of
these
cookies, the cookies that are categorized as necessary are stored on your browser as they are as
essential
for the working of basic functionalities of the website. We also use third-party cookies that
help
us
analyze and understand how you use this website. These cookies will be stored in your browser
only
with
your
consent. You also have the option to opt-out of these cookies. But opting out of some of these
cookies
may
have an effect on your browsing experience.
Necessary
Always Enabled
Necessary cookies are absolutely essential for the website to function properly. This
category only includes cookies that ensures basic functionalities and security
features of the website. These cookies do not store any personal information.
This site uses cookies to improve your experience. If you want to
learn more about cookies and why we use them, visit our cookie
policy. We'll assume you're ok with this, but you can opt-out if you wish Cookie Settings.