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:

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.