Dart Client SDK

Set Up the SDK

1. Install the SDK

   With Dart:

   bash

   Copy

   dart pub add statsig
   

   With Flutter:

   bash

   Copy

   flutter pub add statsig
   

   If you are using Flutter, be sure to add Statsig as part of the app lifecycle 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. These keys are safe to embed in a client application.Along with the key, pass in a User Object with the attributes you'd like to target later on in a gate or experiment.

   dart

   Copy

   import 'package:statsig/statsig.dart';
   
   await Statsig.initialize('client-sdk-key', StatsigUser(userId: "a-user-id"));
   

Use the SDK

Checking a Feature Flag/Gate

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:

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

// 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 be logged with the event:

// 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

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.

In addition to userID, the following top-level fields are available on StatsigUser: 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:

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

Private attributes

To prevent sensitive user PII from being logged, 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, if you have feature gates that should only pass for users with emails ending in "@statsig.com" but don't want to log email addresses to Statsig, add the key-value pair { email: "my_user@statsig.com" } to privateAttributes on the user.

Statsig Options

Lifecycle and advanced usage

Shutting Statsig Down

To save data and battery usage and prevent logged events from being dropped, the SDK keeps event logs in client cache and flushes them periodically. Because of this, some events may not have been sent when your app shuts down.

To ensure all logged events are flushed or saved locally, call shutdown when your app is closing:

await Statsig.shutdown();

Flutter lifecycle hooks

Mobile apps can be closed by the operating system when they're no longer in the foreground. To ensure all events are logged before the operating system closes the app, add Statsig to the app lifecycle events. This flushes all pending events when an app state change is detected.

Something like the following:

// 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.

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

FAQs

How do I run experiments for logged out users?