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-beta.3 # x-release-please-version

Then run:

flutter pub get

Script inclusion(Web only)

The Flutter Experiment SDK uses Dart's JavaScript interoperability to enable the Experiment JavaScript SDK for Flutter Web. This requires that you make the SDK available within the global JavaScript scope. Add the following script tag to web/index.html in your Flutter project:

<script src="https://unpkg.com/@amplitude/experiment-js-client@1.20.1/dist/experiment.umd.js"></script>

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

EU data residency

To send traffic to Amplitude's EU servers, set serverZone to ServerZone.eu:

final config = ExperimentConfig(serverZone: ServerZone.eu);

That is all that is required: the SDK automatically routes to the EU hosts (api.lab.eu.amplitude.com and flag.lab.eu.amplitude.com). Only set serverUrl / flagsServerUrl when you need a custom proxy host; doing so overrides the automatic serverZone routing.

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.