Flutter
Detailed technical documentation on the RudderStack Flutter SDK to send events from your Flutter applications to various destinations.
Last updated
Was this helpful?
Detailed technical documentation on the RudderStack Flutter SDK to send events from your Flutter applications to various destinations.
Last updated
Was this helpful?
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.
We've released a new, beta version of the Flutter SDK (v2) with an enhanced architecture that also supports the web.
If you are using an older version of the Flutter SDK (<1.2.0), then refer to the SDK v1 guide. Note that this SDK version will soon be deprecated.
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.
For more information on the data plane URL and where to get it, refer to this RudderStack Dashboard Overview section.
It is also recommended to set up the Flutter development environment in your system.
The RudderStack Flutter SDK is migrated to Null Safety starting from version 1.0.2.
The recommended way to install the Flutter SDK is through pub
.
Follow the steps below to add the SDK as a dependency:
Open pubspec.yaml
and add rudder_sdk_flutter
under dependencies
section, as shown:
Navigate to your application's root folder and install all the required dependencies with the following command:
After adding the SDK as a dependency, you need to set up the SDK.
To import the SDK, use the following snippet:
Then, add the following code snippet in your application:
The initialize
method has the following signature:
writeKey
String
Required
Your Flutter source write key.
config
RudderConfig
Optional
Contains the RudderStack client configuration
Check the Configuring your RudderStack client section below for a complete list of the configurable parameters.
You can configure your client based on the following parameters by passing them in the RudderConfigBuilder
object of your rudderClient.initialize()
call.
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
https://api.rudderlabs.com
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.
For a detailed explanation of the identify
call, refer to the RudderStack API Specification guide.
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:
The identify
method has the following signature:
userId
String
Required
Includes the developer identity for the user.
traits
RudderTraits
Optional
Contains information related to the user traits.
options
RudderOption
Optional
Extra options for the identify
event.
identify
callYou can obtain the user traits after making an identify
call as shown:
You can record the users' activity through the track
method. Each user action is called an event.
For a detailed explanation of the track
call, refer to the RudderStack API Specification guide.
A sample track
event is shown below:
The track
method has the following signature:
name
String
Required
Contains the name of the event you want to track.
properties
RudderProperty
Optional
Contains the extra properties you want to send along with the event.
options
RudderOption
Optional
Contains the extra event options.
RudderStack automatically tracks the following optional events:
Application Installed
Application Updated
Application Opened
Application Backgrounded
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.
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.
For a detailed explanation of the screen
call, refer to the RudderStack API Specification guide.
A sample screen
event is as shown:
The screen
method has the following signature:
screenName
String
Required
Name of the screen viewed by the user.
properties
RudderProperty
Optional
Extra property object that you want to pass along with the screen
call.
options
RudderOption
Optional
Extra options to be passed along with screen
event.
The group
call associates a user to a specific organization.
For a detailed explanation of the group
call, refer to the RudderStack API Specification guide.
A sample group
event is shown below:
The group
method has the following signature:
groupId
String
Required
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.
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 a detailed explanation of the alias
call, refer to the RudderStack API Specification guide.
A sample alias
call is as shown:
The alias
method has the following signature:
newId
String
Required
The new userId
you want to assign to the user.
options
RudderOption
Optional
Extra options to be passed along with alias
event.
RudderStack replaces the old userId
with the newUserId
and persists this identification across the sessions.
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.
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:
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:
The optOut
API is available in the Flutter SDK starting from version 1.0.6
.
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 whitelisting or blacklisting them.
Refer to the Client-side Event Filtering guide for more information on this feature.
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:
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 exactly match the names as listed in the RudderStack dashboard.
You can pass the destinations to the SDK in the following two ways:
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).
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.
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:
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:
RudderStack collects the advertisement ID only if autoCollectAdvertId
is set to true
during the SDK initialization, as shown:
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()
:
The id
parameter that you pass in the putAdvertisingId
method is assigned as the AAID (for Android) or as the IDFA (for iOS).
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:
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.
You should 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.
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:
Then, turn on the logging by changing your rudderClient
initialization as shown:
You can set the log level to one of the following values:
NONE
ERROR
WARN
INFO
DEBUG
VERBOSE
traits
after making an identify
call?You can get the user traits after making an identify
call in the following way:
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.
This parameter should be changed only if you are self-hosting the control plane. Check the section section below for more information. The SDK will add /sourceConfig
along with this URL to fetch the configuration.