Flutter SDK Installation and Setup

Install and set up the Flutter SDK.

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

Prerequisites

Flutter source write key

Installing the SDK

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

Follow these steps to add the Flutter SDK through pub:

  1. Open pubspec.yaml and add rudder_sdk_flutter under dependencies section:
dependencies:
  rudder_sdk_flutter: ^2.0.1
  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 Flutter SDK for web

warning

Note that the following Flutter SDK features are not available for the web:

  1. Install the Flutter SDK.
  2. Create a Flutter source in the RudderStack dashboard.
  3. Copy the installation snippet from the Web (Minified) or Web (Original) tab as per your requirement.
Flutter JavaScript snippet
  1. Paste the snippet in the <head> section of your web page.

Initializing the SDK

  1. Import the SDK using the following snippet:
import 'package:rudder_sdk_flutter_platform_interface/platform.dart';
import 'package:rudder_sdk_flutter/RudderController.dart';
  1. 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());

The initialize method has the following signature:

NameTypeDescription
writeKey
Required
StringFlutter source’s write key.
configRudderConfigRudderStack 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 parameterRudderConfigBuilder class APIType
Description
Default value
dataPlaneUrlwithDataPlaneUrl()StringThe data plane URL.https://hosted.rudderlabs.com
flushQueueSizewithFlushQueueSize()intNumber of events in a batch request to the server.30
isDebugwithDebug()boolWhen enabled, sets the log level as debug. For more information, refer to the Debugging section.false
logLevelwithLogLevel()intControls the logs you want to see from the Flutter SDK.RudderLogger.RudderLogLevel.NONE
mobileConfigwithMobileConfig()MobileConfigRefer to the mobileConfig parameters section below.-
webConfigwithWebConfig()WebConfigRefer to the webConfig parameters section below.-
controlPlaneUrlwithControlPlaneUrl()StringThis 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.

ParameterTypeDescriptionDefault value
dbCountThresholdintNumber of events to be saved in the SQLite database. Once this limit is reached, the older events are deleted from the database.10000
sleepTimeOutintMinimum waiting time to flush the events to the server.10 seconds
configRefreshIntervalintFetches the config from the dashboard after this specified time.2
trackLifecycleEventsboolDetermines if the SDK will capture application life cycle events automatically.true
autoCollectAdvertIdboolDetermines if the SDK will collect the advertisement ID.false
recordScreenViewsboolWhen enabled, the SDK automatically records the screens viewed by the user.false
dbEncryptionRudderDBEncryptionSpecify 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.

Note the following:

  • The webConfig object of the Flutter SDK supports all the load options currently supported by the JavaScript SDK except the following:

    • logLevel
    • integrations
    • configUrl
    • getSourceConfig
warning

The webConfig object does not support the following parameters anymore from the Flutter SDK v3.0.0:

  • maxRetryDelay, minRetryDelay
  • backoffFactor
  • maxAttempts, maxItems
  • maxBeaconItems
  • beaconFlushQueueInterval
  • autoSessionTracking
  • sessionTimeoutInMillis
  • cookieConsentManagers

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.

danger
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?

Add the following lines to your Android ProGuard rules if you are using Proguard full mode to optimize your app:

info

Add the below rules if you are using the Android SDK older than v1.20.0.

Note that the rules are bundled in the SDK itself from v1.20.0 onwards.

// 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 { *; }
-keep class com.rudderstack.android.sdk.core.TransformationRequest { *; }


Questions? Contact us by email or on Slack