Amplitude Experiment Flutter SDK

Warning This SDK is currently in alpha. APIs may change and there will likely be breaking changes leading up to the stable release.

This is Amplitude's official Experiment Flutter SDK for evaluating feature flags and running experiments across iOS, Android, and Web.

Installation

Add the package to your pubspec.yaml:

dependencies:
  amplitude_experiment: ^0.1.0-alpha.1

Then run:

flutter pub get

Quick Start

1. Initialize

With Amplitude Analytics — use this when your app already uses the Amplitude Analytics Flutter SDK. The Experiment SDK automatically shares user identity and tracks exposures through Analytics.

import 'package:amplitude_flutter/amplitude.dart';
import 'package:amplitude_flutter/configuration.dart';
import 'package:amplitude_experiment/amplitude_experiment.dart';

final amplitude = Amplitude(Configuration(apiKey: 'AMPLITUDE_API_KEY'));
await amplitude.isBuilt;

final experiment = await Experiment.initializeWithAmplitude(
  'DEPLOYMENT_KEY',
  ExperimentConfig(),
);

The Experiment instanceName must match the Amplitude Analytics instance name (case-sensitive) for automatic identity sharing to work. Both SDKs default to $default_instance, so no action is needed for single-instance usage.

Standalone — use this when your app does not use Amplitude Analytics. You provide user context explicitly and wire up your own exposure tracking.

import 'package:amplitude_experiment/amplitude_experiment.dart';

final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(),
);

2. Fetch variants

await experiment.fetch();

When using the standalone client, pass an ExperimentUser with identity and targeting properties:

final user = ExperimentUser(
  userId: 'user@company.com',
  deviceId: 'abcdefg',
  userProperties: {'premium': true},
);
await experiment.fetch(user);

3. Access a variant

final variant = await experiment.variant('flag-key');
if (variant.value == 'on') {
  // Flag is enabled
}

4. Track exposures

When using initializeWithAmplitude, exposure events are tracked automatically on variant() calls. To disable this, set automaticExposureTracking: false in the config and call exposure() manually:

await experiment.exposure('flag-key');

For standalone clients, implement ExposureTrackingProvider to route exposure events to your analytics:

class MyExposureTracker implements ExposureTrackingProvider {
  @override
  void track(Exposure exposure) {
    // Forward to your analytics provider
    analytics.track('\$exposure', {
      'flag_key': exposure.flagKey,
      'variant': exposure.variant,
    });
  }
}

final experiment = await Experiment.initialize(
  'DEPLOYMENT_KEY',
  ExperimentConfig(
    exposureTrackingProvider: MyExposureTracker(),
  ),
);

Configuration

All config fields have sensible defaults. Common options:

Option	Default	Description
`instanceName`	`$default_instance`	Name for this client instance
`fallbackVariant`	`null`	Variant returned when a flag has no value
`source`	`Source.localStorage`	Where to read flag data from
`serverZone`	`ServerZone.us`	Data center region (`us` or `eu`)
`automaticExposureTracking`	`true`	Track exposures on `variant()` calls
`fetchOnStart`	`true`	Fetch flags when `start()` is called

See ExperimentConfig API docs for the full list.

Learn More

Visit the Amplitude Experiment documentation for guides on creating flags, targeting users, and running experiments.