---
title: Dart Client SDK
description: "Statsig's SDK for Experimentation and Feature Flags in Dart & Flutter applications."
product: general
token_estimate: 2158
---
# Dart Client SDK

> For AI agents: a documentation index is available at [/llms.txt](/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

- **Package:** `statsig` ([pubdev](https://pub.dev/packages/statsig))
- **Latest version:** 1.2.9
- **Repository:** [dart-sdk](https://github.com/statsig-io/dart-sdk)

## Set up the SDK

1. **Install the SDK**

   With Dart:

   ```bash
   dart pub add statsig
   ```

   With Flutter:

   ```bash
   flutter pub add statsig
   ```

   > **Note:**
   >
   > If you are using **Flutter**, be sure to add Statsig as part of the [app lifecycle](#flutter-lifecycle-hooks) to avoid losing events.
2. **Initialize the SDK**

   Next, initialize the SDK with a client SDK key from the ["API Keys" tab on the Statsig console](https://console.statsig.com/api_keys). These keys are safe to embed in a client application.

   Along with the key, pass in a [User Object](#statsig-user) with the attributes you'd like to target later in a gate or experiment.

   ```dart
   import 'package:statsig/statsig.dart';

   await Statsig.initialize('client-sdk-key', StatsigUser(userId: "a-user-id"));
   ```

## Use the SDK

### Checking a Feature Flag/Gate

After the SDK is initialized, check a [**Feature Gate**](https://docs.statsig.com/feature-flags/overview). Feature Gates create logic branches in code that you can roll out to different users from the Statsig Console. Gates are always **CLOSED** or **OFF** (equivalent to `return false;`) by default.

```dart
if (Statsig.checkGate("new_homepage_design")) {
  // Gate is on, show new home page
} else {
  // Gate is off, show old home page
}
```

### Reading a Dynamic Config

Feature Gates work well for simple on/off switches with optional advanced user targeting. To send a different set of values (strings, numbers, and so on) to clients based on specific user attributes such as country, use **Dynamic Configs**. The API is similar to Feature Gates, but returns an entire JSON object you configure on the server, from which you can fetch typed parameters. For example:

```dart
var config = Statsig.getConfig("awesome_product_details");

// The 2nd parameter is the default value to be used in case the given parameter name does not exist on
// the Dynamic Config object. This can happen when there is a typo, or when the user is offline and the
// value has not been cached on the client.
var itemName = config.get("product_name", "Awesome Product v1");
var price = config.get("price", 10.0);
var shouldDiscount = config.get("discount", false);
```

### Getting a Layer/Experiment

**Layers/Experiments** support running A/B/n experiments. Statsig offers two APIs, but recommends [layers](https://docs.statsig.com/experiments/layers-overview) to enable quicker iterations with parameter reuse.

```dart
// Values via getLayer

var layer = Statsig.getLayer("user_promo_experiments");
var promoTitle = layer.getString("title", "Welcome to Statsig!");
var discount = layer.getDouble("discount", 0.1);

// or, via getExperiment

var titleExperiment = Statsig.getExperiment("new_user_promo_title");
var priceExperiment = Statsig.getExperiment("new_user_promo_price");

var promoTitle = titleExperiment.get("title", "Welcome to Statsig!");
var discount = priceExperiment.get("discount", 0.1);
```

### Logging an Event

After setting up a Feature Gate or an Experiment, you can track custom events to see how your new features or different experiment groups affect those events. Call the Log Event API for the event, and optionally provide a value and metadata object to log with the event:

```dart
// Provide a doubleValue argument for number values
Statsig.logEvent("purchase", doubleValue: 2.99, metadata: {"item_name": "remove_ads"});

// or provide a stringValue argument for string values
Statsig.logEvent("login", stringValue: "a.user@mail.com");
```

## Parameter Stores

Parameter Stores hold a set of parameters for your mobile app. These parameters can be remapped dynamically from a static value to a Statsig entity (Feature Gates, Experiments, and Layers). Remapping lets you decouple your code from the configuration in Statsig. Refer to [Param Stores](https://docs.statsig.com/client/concepts/parameter-stores) for more information.

```dart
var homepageStore = Statsig.getParameterStore("homepage");

var title = homepageStore.get("title", "Welcome");
var shouldShowUpsell = homepageStore.get("upsell_upgrade_now", false);
```

## Statsig User

You need to provide a StatsigUser object to check or get your configurations. Pass as much information as possible to take advantage of advanced gate and config conditions.

The `userID` field is required in most cases to provide a consistent experience for a given user (refer to [logged-out experiments](https://docs.statsig.com/guides/first-device-level-experiment) for how to run experiments for logged-out users).

In addition to `userID`, StatsigUser offers the following top-level fields: `email`, `ip`, `userAgent`, `country`, `locale`, and `appVersion`. You can also pass any key-value pairs in an object or dictionary to the `custom` field to create targeting based on them.

After the user logs in or their attributes change, call `updateUser` with the updated `userID` and any other updated user attributes:

```dart
await Statsig.updateUser(StatsigUser("a_new_user"));
```

### Private attributes

To prevent logging sensitive user PII, use the `privateAttributes` field on the StatsigUser object. Statsig uses any attribute set in `privateAttributes` only for evaluation and targeting, and removes it from logs before sending them to the server.

For example, suppose you have feature gates that should only pass for users with emails ending in "@statsig.com", but you don't want to log email addresses to Statsig. In that case, add the key-value pair `{ email: "my_user@statsig.com" }` to `privateAttributes` on the user.

## Statsig Options

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| initTimeout | int | No | — | Sets how long (in seconds) the Statsig client waits for the initial network request to respond before calling the completion block. If you call `checkGate`, `getConfig`, or `getExperiment` before the initial network request completes, the Statsig client returns either cached values (if any) or default values.If you always want to wait for the latest values fetched from the Statsig server, set this to `0` so the network request doesn't time out. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| api | string | No | — | The endpoint to use for all SDK network requests. Don't override this unless you have another API that implements the Statsig API endpoints. |

| Name | Type | Required | Default | Description |
| --- | --- | --- | --- | --- |
| environment | string | No | — | The environment tier to evaluate rules for the current user. Default is empty, which is the same as "production." On non-production tiers, events don't appear in downstream pulse results. |

## Lifecycle and advanced usage

## Shutting Statsig down

To save data and battery usage and avoid dropping logged events, the SDK keeps event logs in client cache and flushes them periodically. Because of this periodic flushing, the SDK may not have sent some events when your app shuts down.

To ensure the SDK flushes or saves all logged events locally, call `shutdown` when your app is closing:

```dart
await Statsig.shutdown();
```

## Flutter lifecycle hooks

The operating system can close mobile apps when they're no longer in the foreground. To ensure Statsig logs all events before the operating system closes the app, add Statsig to the app lifecycle events. This flushes all pending events when it detects an app state change.

Something like the following:

```dart
// An example App Lifecycle Observer
class StatsigLifecycleObserver extends WidgetsBindingObserver {
  @override
  void didChangeAppLifecycleState(AppLifecycleState state) async {
    switch (state) {
      case AppLifecycleState.resumed:
        await Statsig.initialize('client-sdk-key');
        break;
      case AppLifecycleState.paused:
        await Statsig.shutdown();
        break;
    }
  }
}

```

Then in your app code, add this observer to the WidgetsBinding instance.

```dart
@override
void initState() {
  super.initState();
  WidgetsBinding.instance.addObserver(StatsigLifecycleObserver());
}
```

## FAQs

### How do I run experiments for logged out users

Go to the guide on [device level experiments](https://docs.statsig.com/client/concepts/persistent_assignment).