# Flutter SDK Installation and Setup This guide walks you through the SDK installation and initialization steps in detail. ## Prerequisites - Set up the [Flutter development environment](https://flutter.dev/docs/get-started/install) in your system. - Sign up for [RudderStack](https://app.rudderstack.com/signup). - [Set up a Flutter source]({{< ref "dashboard-guides/sources/_index.md#adding-a-source" >}}) in your [RudderStack dashboard](https://app.rudderstack.com/). Note the {{< glossary_tooltip "write-key" >}} for this source. - You will also need the [data plane URL]({{< ref "dashboard-guides/_index.md#connections" >}}) associated with your RudderStack workspace. ## Installing the SDK {{< info >}} Starting from v1.0.2, the RudderStack Flutter SDK is migrated to [Null Safety](https://dart.dev/null-safety). {{< /info >}} Follow these steps to add the Flutter SDK through [`pub`](https://pub.dev/packages/rudder_sdk_flutter): 1. Open `pubspec.yaml` and add `rudder_sdk_flutter` under `dependencies` section: ```yaml dependencies: rudder_sdk_flutter: ^2.0.1 ``` 2. Navigate to your application's root folder and install all the required dependencies with the following command: ```bash flutter pub get ``` If you are using Proguard full mode to optimize your app, add the lines specified in the [FAQ](#do-i-need-to-add-anything-to-my-android-proguard-rules) to your Android ProGuard rules. ### Installing Flutter SDK for web {{< info >}} Starting from v3.2.0, the Flutter Web SDK supports [WebAssembly (WASM)](https://docs.flutter.dev/platform-integration/web/wasm). {{< /info >}} 1. [Install](#installing-the-sdk) the Flutter SDK. 2. Create a [Flutter source]({{< ref "dashboard-guides/sources.md#adding-a-source" >}}) in the RudderStack dashboard. 3. Copy the installation snippet from the **Web (Minified)** or **Web (Original)** tab as per your requirement. {{< image src="images/event-stream-sources/flutter-js-snippet.webp" alt="Flutter JavaScript snippet" >}} 4. Paste the snippet in the `` section of your web page. {{< warning >}} The Flutter Web SDK **does not support** the following features: - [Manage user tracking (GDPR support)]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/features-and-usage.md#enablingdisabling-user-tracking-gdpr-support" >}}) - [Setting the device token]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/features-and-usage.md#setting-the-device-token" >}}) - [Setting the advertisement ID]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/features-and-usage.md#setting-the-advertisement-id" >}}) {{< /warning >}} ## Initializing the SDK 1. Import the SDK using the following snippet: ```dart import 'package:rudder_sdk_flutter_platform_interface/platform.dart'; import 'package:rudder_sdk_flutter/RudderController.dart'; ``` 2. Add the following code in your application: ```dart final RudderController rudderClient = RudderController.instance; RudderLogger.init(RudderLogger.VERBOSE); RudderConfigBuilder builder = RudderConfigBuilder(); builder.withDataPlaneUrl(); builder.withTrackLifecycleEvents(true); rudderClient.initialize(,config: builder.build()); ``` {{< warning >}} Replace the {{< glossary_tooltip "write-key" >}} and {{< glossary_tooltip "data-plane-url" >}} with their actual values. {{< /warning >}} 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 | Your {{< glossary_tooltip "data-plane-url" >}} | | `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]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/features-and-usage.md#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](#mobileconfig-parameters) section below. | - | | `webConfig` | `withWebConfig()` | WebConfig | Refer to the [`webConfig` parameters](#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](#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]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/features-and-usage.md#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]({{< ref "sources/event-streams/sdks/rudderstack-javascript-sdk/load-js-sdk.md" >}}) currently supported by the [JavaScript SDK]({{< ref "sources/event-streams/sdks/rudderstack-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` {{< /warning >}} - You can [enable or disable events for specific destinations]({{< ref "sources/event-streams/sdks/rudderstack-flutter-sdk/features-and-usage.md#enablingdisabling-events-for-specific-destinations" >}}) while [initializing the Flutter SDK](#initializing-the-sdk). ## Self-hosted control plane If you are self-hosting RudderStack and using the [Control plane lite](https://github.com/rudderlabs/config-generator#rudderstack-control-plane-lite) utility to host your own control plane, then follow the steps in [this section]({{< ref "/get-started/rudderstack-open-source/control-plane-lite.md#using-sdk-sources-set-up-in-self-hosted-control-plane" >}}) and specify the `controlPlaneUrl` parameter in your [`RudderConfigBuilder`](#sdk-initialization-options) that points to the hosted configuration file. {{< danger >}} You should not pass the `controlPlaneUrl` parameter during SDK initialization if you are using [RudderStack dashboard](https://app.rudderstack.com). This parameter is supported **only** if you are using the open source [Control plane lite](https://github.com/rudderlabs/config-generator#rudderstack-control-plane-lite) utility to set up your own control plane. {{< /danger >}} ## 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 {{< legacy-tooltip "android-java" >}} older than v1.20.0. Note that the rules are bundled in the SDK itself from v1.20.0 onwards. {{< /info >}} ```java // 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 { *; } ```