Flutter SDK Installation and Setup

Install and set up the Flutter SDK.

6 minute read

This guide walks you through the SDK installation and initialization steps in detail.

Prerequisites

Set up the Flutter development environment in your system.
Sign up for RudderStack Cloud.
Set up a Flutter source in your RudderStack Cloud dashboard. Note the Write Key for this source:

Note the data plane URL present in your RudderStack dashboard.

Installing the SDK

Starting from v1.0.2, the RudderStack Flutter SDK is migrated to Null Safety.

Follow these steps to add the Flutter SDK through pub:

Open pubspec.yaml and add rudder_sdk_flutter under dependencies section:

dependencies:
  rudder_sdk_flutter: ^2.0.1

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

flutter pub get

If you are using Proguard full mode to optimize your app, add the lines specified in the FAQ to your Android ProGuard rules.

Installing the SDK for the web

To install and use the Flutter SDK in your web app, follow the above steps to add the Flutter SDK. Additionally, copy the following snippet in the <head> section of your web page:

<script>
rudderanalytics = window.rudderanalytics = [];
for (var methods = ["load", "page", "track", "identify", "alias", "group", "ready", "reset", "getAnonymousId", "setAnonymousId"], i = 0; i < methods.length; i++) {
  var method = methods[i];
  rudderanalytics[method] = function(a) {
    return function() {
      rudderanalytics.push([a].concat(Array.prototype.slice.call(arguments)))
    }
  }(method)
}
</script>

<script src="https://cdn.rudderlabs.com/v1/rudder-analytics.min.js"></script>

Not all Flutter SDK APIs are applicable for the web. The following APIs will have no effect on your web app:
optOut
putDeviceToken
putAdvertisingId

Initializing the SDK

Import the SDK using the following snippet:

import 'package:rudder_sdk_flutter_platform_interface/platform.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';

Add the following code in your application:

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

Replace the write keyThe write key (or source write key) is a unique identifier for your source. RudderStack uses this key to send events from a source to the specified destination. and data plane URLThe data plane URL is the location where events are routed and sent to the RudderStack backend for processing. You can find this URL in the home page of your RudderStack dashboard. with their actual values.

The initialize method has the following signature:

Name	Type	Description
`writeKey` Required	String	Flutter source’s write key.
`config`	`RudderConfig`	RudderStack client configuration.

SDK initialization options

You can configure the SDK behavior using the RudderConfig object passed to the rudderClient.initialize() call during initialization.

You can create the object of RudderConfig class by either:

Directly calling its constructor using the parameters documented below, or
Using the RudderConfigBuilder class APIs as per your requirement

`RudderConfig` constructor parameter	`RudderConfigBuilder` class API	Type	Description	Default value
`dataPlaneUrl`	`withDataPlaneUrl()`	String	The data plane URL.	`https://hosted.rudderlabs.com`
`flushQueueSize`	`withFlushQueueSize()`	int	Number of events in a batch request to the server.	`30`
`isDebug`	`withDebug()`	bool	When enabled, sets the log level as `debug`. For more information, refer to the Debugging section.	`false`
`logLevel`	`withLogLevel()`	int	Controls the logs you want to see from the Flutter SDK.	`RudderLogger.RudderLogLevel.NONE`
`mobileConfig`	`withMobileConfig()`	MobileConfig	Refer to the `mobileConfig` parameters section below.	-
`webConfig`	`withWebConfig()`	WebConfig	Refer to the `webConfig` parameters section below.	-
`controlPlaneUrl`	`withControlPlaneUrl()`	String	This parameter should be changed only if you are self-hosting the control plane. Refer to the Self-hosted control plane section for more information. The SDK will add `/sourceConfig` along with this URL to fetch the configuration.	`https://api.rudderlabs.com`

mobileConfig parameters

The mobileConfig object contains the mobile-specific configuration parameters for the Flutter SDK.

Parameter	Type	Description	Default value
`dbCountThreshold`	int	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`	int	Minimum waiting time to flush the events to the server.	`10 seconds`
`configRefreshInterval`	int	Fetches the config from the dashboard after this specified time.	`2`
`trackLifecycleEvents`	bool	Determines if the SDK will capture application life cycle events automatically.	`true`
`autoCollectAdvertId`	bool	Determines if the SDK will collect the advertisement ID.	`false`
`recordScreenViews`	bool	When enabled, the SDK automatically records the screens viewed by the user.	`false`
`dbEncryption`	`RudderDBEncryption`	Specify whether to encrypt/decrypt the database using the specified key. See Encrypting RudderStack databases for more information.	-

webConfig parameters

The webConfig object contains the configuration parameters for using the SDK in the Flutter web applications.

Parameter	Type	Description	Default value
`destSDKBaseURL`	String	The SDK loads the integration from this path.
`useBeacon`	bool	If enabled, the SDK sends the event payloads via the `navigator.sendBeacon()` utility	`False`
`secureCookie`	bool	If enabled, the SDK sends the cookie to the storage backend via HTTPS.	`False`
`loadIntegration`	bool	If disabled, the destination SDKs are not fetched by the SDK.	`True`
`cookieConsentManagers`	Object	Refer to the cookieConsentManager section for more information.	-
`beaconFlushQueueInterval`	int	The SDK flushes the queue after this time interval (in milliseconds).	600000
`maxBeaconItems`	int	The SDK flushes the queue when this number of events is reached.	10
`maxItems`	int	Maximum number of events kept in the storage.	100
`maxAttempts`	int	Maximum number of attempts the SDK makes to send the event to the destination.	10
`backoffFactor`	int	Refers to the exponential base.	2
`minRetryDelay`	int	The minimum delay expected before the SDK retries sending an event (in ms)	1000
`maxRetryDelay`	int	The upper limit on the maximum delay for retrying an event (in ms)	360000

You can also enable or disable events for specific destinations while initializing the SDK.

Self-hosted control plane

If you are self-hosting RudderStack and using the Control plane lite utility to host your own control plane, then follow the steps in this section and specify the controlPlaneUrl parameter in your RudderConfigBuilder that points to the hosted 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.

FAQ

Do I need to add anything to my Android ProGuard rules?

If you are using Proguard full mode to optimize your app, add the following lines to your Android ProGuard rules:

// Reporter Module
-keep class com.rudderstack.android.ruddermetricsreporterandroid.models.LabelEntity { *; }
-keep class com.rudderstack.android.ruddermetricsreporterandroid.models.MetricEntity { *; }
-keep class com.rudderstack.android.ruddermetricsreporterandroid.models.ErrorEntity { *; }

// Required for the usage off TypeToken class in Utils.converToMap, Utils.convertToList
-keep class com.google.gson.reflect.TypeToken { *; }
-keep class * extends com.google.gson.reflect.TypeToken

// Required for the serialization of SourceConfig once it is downloaded.
-keep class com.google.gson.internal.LinkedTreeMap { *; }
-keep class * implements java.io.Serializable { *; }
-keep class com.rudderstack.rudderjsonadapter.RudderTypeAdapter { *; }
-keep class * extends com.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.
-dontwarn net.sqlcipher.Cursor
-dontwarn net.sqlcipher.database.SQLiteDatabase$CursorFactory
-dontwarn net.sqlcipher.database.SQLiteDatabase
-dontwarn net.sqlcipher.database.SQLiteOpenHelper
-keep class com.rudderstack.android.sdk.core.persistence.DefaultPersistenceProviderFactory { *; }

// Required for the usage of annotations across reporter and web modules
-dontwarn com.fasterxml.jackson.annotation.JsonIgnore
-dontwarn com.squareup.moshi.Json
-dontwarn com.fasterxml.jackson.annotation.JsonProperty

// Required for Device Mode Transformations
-keep class com.rudderstack.android.sdk.core.TransformationResponse { *; }
-keep class com.rudderstack.android.sdk.core.TransformationResponseDeserializer { *; }

Was this page helpful?

Glad to hear it! Please tell us how we can improve.

Sorry to hear that. Please tell us how we can improve.

Questions? Contact us by email or on Slack