Flutter - GrowthBook Documentation

This SDK supports the following versions:

Android version 21 & above
iOS version 12 & Above
Apple TvOS version 13 & Above
Apple WatchOS version 7 & Above

Installation

Add this to your pubspec.yaml file

growthbook_sdk_flutter: ^4.0.0

Quick Usage

Create a GrowthBookSDK instance with GBSDKBuilderApp, set attributes, then evaluate features or run experiments.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123", // Client key from GrowthBook
  hostURL: "https://cdn.growthbook.io", // or your Proxy URL
  attributes: {
    "id": "123",
    "env": "dev",
    "betaUser": true,
  },
  growthBookTrackingCallBack: (exp, result) {
    // Track exposures
  },
).initialize();

final feature = sdk.feature("my-feature");
if (feature.on) {
  // Feature is enabled
}

Using Features

The feature method takes a String feature name and returns a GBFeatureResult object with a few useful properties:

value (dynamic) - The assigned value of the feature
on (bool) - The value cast to a boolean
off (bool) - The value cast to a boolean and then negated
source (String) - Why the value was assigned to the user. One of “unknownFeature”, “defaultValue”, “force”, or “experiment”

When the source is “experiment”, there are 2 additional properties that tell you which experiment was used and more details about the result of the experiment:

experiment (GBExperiment)
experimentResult (GBExperimentResult)

Here are some examples:

GBFeatureResult feature = gb.feature("my-feature")

// Do something if feature is truthy
if (feature.on) { }

// Do something if feature is falsy
if (feature.off) { }

// Print the actual value of the feature
// (depending on the feature, might be a string, number, boolean, etc.)
print(feature.value)

// Print the experiment id used to assign the feature value
if (feature.source == "experiment") {
  Println(feature.experiment.key)
}

Attributes

Attributes define the current user and request “context” used for targeting rules and bucketing.

Common attributes

id (string): primary user identifier for consistent bucketing
deviceId (string): device/install-scoped fallback when user not logged in
country, locale (string)
plan, company, role (string)
loggedIn (bool)
appVersion (string, supports semver targeting)

Use setAttributes() method to set the user context.

sdk.setAttributes({
  "id": "123",
  "country": "US",
  "plan": "pro",
  "appVersion": "1.3.0",
});

What is the user context?

Identity: stable identifiers for bucketing (e.g., id, and optionally a logged-out fallback like deviceId).
Demographics and traits: e.g., country, company, plan, loggedIn.
App/runtime context: e.g., appVersion, platform, locale.
Request context (if applicable): e.g., url, path, device.

Data types supported include strings, numbers, booleans, and arrays/objects for JSON-based conditions.

On login, switch from deviceId to id (stable user id).
On logout, remove id and use deviceId until the next login.

// Logged-out (device-scoped)
sdk.setAttributes({
  "deviceId": "device-abc",
  "loggedIn": false,
});

// After login (user-scoped)
sdk.setAttributes({
  "id": "user-123",
  "loggedIn": true,
});

If using Remote Evaluation, consider limiting network calls to meaningful identity changes with cacheKeyAttributes and refreshing when identity changes:

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://gb-proxy.example.com",
  remoteEval: true,
  cacheKeyAttributes: ["id", "email"],
  attributes: {"deviceId": "device-abc"},
).initialize();

// Later, after login
sdk.setAttributes({
  "id": "user-123",
  "email": "user@example.com",
});
await sdk.refreshForRemoteEval();

Experimentation (A/B Testing)

To run the experiements with GrowthBook, use run method, which takes a GBExperiment object as an argument and returns a GBExperimentResult object:

var exp = GBExperiment()
exp.key = "my-experiment"
exp.variations = List.of("control", "variation")

var result = gb.run(exp)

// Either "control" or "variation"
print(result.value)

The GBExperiment class has two required properties - key and variations. There are also a number of optional properties:

key (String) - The unique identifier for this experiment
variations (dynamic[]) - Array of variations to decide between
weights (double[]) - How to weight traffic between variations. Must add to 1.
active (bool) - If set to false, always return the control (first variation)
coverage (double) - What percent of users should be included in the experiment (between 0 and 1, inclusive)
condition (GBCondition) - Optional targeting condition
namespace ([String, int, int]) - Adds the experiment to a namespace
force (int) - All users included in the experiment will be forced into the specific variation index
hashAttribute (String) - What user attribute should be used to assign variations (defaults to id)

The GBExperimentResult object returns the following properties:

inExperiment (bool)
variationId (int) - The array index of the assigned variation
value (dynamic) - The value of the assigned variation
hashAttribute (String) - The user attribute used to assign a variation
hashValue (String) - The value of the attribute used to assign a variation

Tracking & Subscriptions

Use growthBookTrackingCallBack to receive experiment exposure events whenever a user is assigned to a variation (via features or inline experiments). For feature usage events (non-experiment), wrap your feature(...) calls in a small utility to emit custom app analytics.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  growthBookTrackingCallBack: (exp, result) {
    // e.g., send to analytics
  },
).initialize();

To Subscribe :

final exposures = StreamController<Map<String, dynamic>>.broadcast();

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  growthBookTrackingCallBack: (exp, result) {
    exposures.add({
      "experimentKey": exp.key,
      "variationId": result.variationId,
      "featureId": result.featureId,
    });
  },
).initialize();

final sub = exposures.stream.listen((e) {
  // send to analytics
});

// Later, unsubscribe to avoid leaks
await sub.cancel();

When subscriptions fire vs. don’t fireWhen subscriptions fire vs. don’t fire

Fire: on first assignment per experiment key and after assignments change due to attribute updates or payload changes.
Don’t fire: repeated reads of the same assignment that hasn’t changed.

Efficient subscription patterns

Keep callbacks lightweight; offload heavy work to background tasks.
Coalesce multiple exposure events before sending to analytics to reduce overhead.
Include experiment.key, variationId, and optional featureId for correlation.

Unsubscribing and memory management

Remove any of your app-layer listeners in dispose().
Dispose the SDK instance when not needed (e.g., app shutdown) to release resources and close streams.

Loading Features

Built-in fetching and caching

If you pass a hostURL and apiKey into the builder, the SDK handles network requests, caching, retry/backoff, and decryption (when configured in your SDK connection). You can enable streaming updates with backgroundSync: true.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  backgroundSync: false,
).initialize();

// Manually refresh (e.g., on app start or navigation)
await sdk.refreshCache();

Custom integration (local evaluation)

If you prefer to control network and caching yourself, you can set a payload directly on the SDK. This enables fully local evaluation and offline-first behavior.

await sdk.setPayload({
  "features": {
    "feature-1": {"defaultValue": true},
    "feature-2": {"defaultValue": "blue"}
  }
});

Caching

The SDK persists downloaded feature payloads and related metadata. Configure TTL to control how long cached features are considered fresh before a background refresh.

To use Stale-While-Revalidate strategy with TTL and streaming:

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  ttlSeconds: 300,
  backgroundSync: true, // keep a live stream for fast updates
).initialize();

Manual refresh at lifecycle boundaries:

// App resume, significant navigation, pull-to-refresh, etc.
await sdk.refreshCache();

Identity or environment switch:

// Switch attributes to new identity, then refresh
sdk.setAttributes({"id": "new-user"});
await sdk.refreshCache();

// If you store sticky assignments yourself, clear the old user's keys
await myStickyStorage.clearForUser("old-user");

Web-specific caching considerations

For Flutter Web, ensure your CDN respects cache-control headers for GrowthBook endpoints.
Avoid overly aggressive service worker caching for evaluated payloads unless you manage invalidation carefully.

Real-time Updates (SSE)

Setup and lifecycle

Initialization
- Enable backgroundSync: true when building the SDK instance.
- Optionally pass streamingRequestHeaders (e.g., auth) and Last-Event-Id to resume after restarts.
Refresh handler
- Use onFeaturesRefreshed to update UI or invalidate caches after new data is applied.
- The callback fires for both streaming updates and manual refreshes.
Teardown
- Dispose your SDK instance when your app shuts down. The connection will be closed automatically.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  backgroundSync: true,
  onFeaturesRefreshed: (success) {
    if (success) {
      // e.g., notify listeners / rebuild widgets
    } else {
      // network failure or payload issue
    }
  },
).initialize();

You can also add custom headers for secure requests:

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  requestHeaders: {"Authorization": "Bearer <token>"},
  streamingRequestHeaders: {
    "Authorization": "Bearer <token>",
    // Optionally resume after disconnects
    "Last-Event-Id": "<persisted-last-id>"
  },
  backgroundSync: true,
).initialize();

Network failures and reconnection

The SDK uses an exponential backoff strategy on streaming errors and attempts to auto-reconnect.
Provide stable connectivity hints to users only when necessary; otherwise allow background reconnection.
Persist and reuse the Last-Event-Id to avoid duplicate events on resume.

// Example: Persist last event id you receive from your stream handler
await storage.write(key: 'gb_last_event_id', value: lastEventId);
// Then pass it back during init via `streamingRequestHeaders` as shown above

Performance Considerations

Prefer streaming when you need near real-time flag updates (admin toggles, ops tooling).
Prefer polling/manual refresh when updates are infrequent or the app is latency- or battery-sensitive.
Background sync opens a single lightweight SSE connection; avoid running multiple SDK instances with streaming in the same app.

Remote Evaluation

See the Remote Evaluation overview for more information about what Remote Evaluation is, how it works, and deployment options.

Run GrowthBook in Remote Evaluation mode to evaluate flags on a private server (e.g., GrowthBook Proxy). Sensitive rules never reach the client.

Sticky Bucketing with Remote EvaluationIf you want Sticky Bucketing with Remote Evaluation, configure your remote backend (e.g., GrowthBook Proxy) with a persistent store (e.g., Redis). You do not need to provide a sticky service on the client.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://gb-proxy.yourcompany.com",
  remoteEval: true,
  // Optional: only trigger a new evaluation when selected attributes change
  cacheKeyAttributes: ["id", "email"],
  attributes: {"id": "123", "email": "user@example.com"},
).initialize();

// Manually trigger a remote evaluation when attributes change
sdk.setAttributes({"plan": "pro"});
await sdk.refreshForRemoteEval();

Remote vs local evaluation

Use remote evaluation when:
- You need to keep targeting rules and unused variations off-device for privacy/compliance.
- Payload size is large and you want device-optimized responses for the current user.
Use local evaluation when:
- You need offline-first behavior or minimal round trips.
- The full feature payload is small and regularly reused.

Configuration

Endpoint: Set hostURL to your GrowthBook Proxy or secured backend base URL.
Auth: Send authentication via requestHeaders to both fetching and remote eval endpoints.
Cache keys: Use cacheKeyAttributes to limit remote calls to only when relevant identity fields change.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://gb-proxy.example.com",
  remoteEval: true,
  cacheKeyAttributes: ["id", "email"],
  requestHeaders: {"Authorization": "Bearer <token>"},
  attributes: {"id": "u_123", "email": "u@example.com"},
).initialize();

Debugging Remote Evaluation

Verify required attributes are present before calling refreshForRemoteEval().
Log the response status/source from your SDK callbacks to confirm whether updates came from network or cache.
Check your proxy/server logs for rejected requests, auth failures, or schema mismatches.

Security considerations

Treat the apiKey as public. Protect sensitive data with server-side auth on your proxy.
Use short-lived tokens in requestHeaders when possible and rotate regularly.
Avoid putting PII directly in attributes unless hashed/secured per your policies.

Fallback strategies

If remote eval fails, keep using the last known values from cache and retry later.
Consider a hybrid approach: bootstrap with a local payload and switch to remote eval when online.
Implement a user-visible retry or manual refresh action when business-critical.

Sticky Bucketing

Sticky bucketing ensures users see the same experiment variant across sessions. Read more about Sticky Bucketing Feature

Enable Sticky Bucketing on the experiment or feature rule in GrowthBook.
Provide a stable identity in attributes (e.g., id) after login; use a device-scoped fallback when logged out.
Use a globally unique id for logged-in users; avoid mutable identifiers.
For logged-out sessions, use a device/install identifier and switch to id on login.
When identity changes (login/logout), update attributes immediately to avoid cross-user assignment mixing.

Implement a GBStickyBucketService to persist assignments. Attach your GBStickyBucketService when building the SDK to persist assignments across sessions.

class MyAppStickyBucketService extends GBStickyBucketService {
  @override
  Future<Map<String, String>?> getAllAssignments(
    Map<String, dynamic> attributes,
  ) async {
    // Retrieve from local storage
    // ...
    return null;
  }

  @override
  Future<void> saveAssignments(
    Map<String, dynamic> attributes,
    Map<String, String> assignments,
  ) async {
    // Save to local storage
    // ...
  }
}

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  stickyBucketService: MyAppStickyBucketService(),
).initialize();

For Remote evaluations, if your Remote Eval backend (e.g., GrowthBook Proxy) is configured for sticky bucketing, persistence happens server-side and you do not need to provide a client service.

// Remote evaluation with server-side sticky (no client sticky service needed)
final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://gb-proxy.yourcompany.com",
  remoteEval: true,
  attributes: {"id": "user_123"},
).initialize();

Custom Sticky Bucketing Service configurations

Namespacing: use an environment-specific key prefix (e.g., prod_, staging_).
Storage backend: choose durable storage for your platform (SharedPreferences, secure storage, SQLite).
Migration: when changing storage layout, migrate existing assignment keys to preserve continuity.

Troubleshooting stale assignments

Logout or user-switch: clear assignments for the previous identity or use identity-specific keys.
Experiment retired/changed: allow non-sticky behavior to take effect; optionally prune retired experiment keys.
Unexpected variant: confirm which identity key is being used and verify read/write paths in your storage.

See the Flutter repo for examples and updates: growthbook-flutter.

Encrypted features

Configure SDK Connection to deliver encrypted features, provide the decryption key during initialization.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://cdn.growthbook.io",
  decryptionKey: "<your-32-byte-key>",
).initialize();

Or prefer using a Remote Evaluation backend (e.g., GrowthBook Proxy) that decrypts server-side. This keeps secrets off the device.

final sdk = await GBSDKBuilderApp(
  apiKey: "sdk-abc123",
  hostURL: "https://gb-proxy.yourcompany.com", // Proxy handles decryption
  remoteEval: true,
  attributes: {"id": "user_123"},
).initialize();

Performance optimizations

Track refresh times and payload sizes; reduce attribute surface area where possible.
Avoid multiple SDK instances with streaming enabled; prefer a single shared instance.
Use onFeaturesRefreshed to scope UI rebuilds and avoid unnecessary widget tree updates.

Memory usage patterns

Keep attribute maps small and reuse them when doing partial updates.
Periodically prune stale sticky assignments if you implement a custom store.
Avoid holding multiple SDK instances; share a single instance across the app.

Error handling and debugging

Debug logging configuration

// Simple logger wrapper for development
void gbLog(String message) {
  assert(() { // only in debug mode
    // ignore: avoid_print
    print('[GrowthBook] ' + message);
    return true;
  }());
}

// Example usage
gbLog('Initializing GrowthBook');

Common error scenarios and solutions

Initialization returned from cache only
- Ensure network connectivity and correct hostURL/apiKey.
- Call await sdk.refreshCache() on resume or via pull-to-refresh.
Unauthorized (401/403)
- Verify requestHeaders (e.g., Bearer token) and that your proxy/CDN forwards headers.
Decryption errors
- Confirm decryptionKey matches the SDK Connection and is valid; prefer server-side decryption.

Feature evaluation debugging techniques

final res = sdk.feature('checkout_v2');
gbLog('feature=checkout_v2 value=${res.value} source=${res.source}');

if (res.source == 'experiment') {
  gbLog('exp=' + (res.experiment?.key ?? 'n/a') + ' varId=${res.experimentResult?.variationId}');
}

Inspect attributes used during evaluation:

// Keep your own copy of the attributes you set
final currentAttrs = {"id": "123", "country": "US"};
sdk.setAttributes(currentAttrs);
gbLog('attrs=' + currentAttrs.toString());

Network connectivity troubleshooting

try {
  await sdk.refreshCache();
  gbLog('Refresh succeeded');
} catch (e) {
  gbLog('Refresh error: ' + e.toString());
}

If streaming is enabled, rely on auto-reconnect with backoff. Allow a manual refresh UI if business-critical.

Platform-specific considerations

Web vs mobile behavior differences

SSE support and networking may differ in browsers; validate CORS and service worker behavior for Flutter Web.
Storage persistence differs (IndexedDB/localStorage on Web vs SharedPreferences/Secure Storage on mobile).
For Web, prefer IndexedDB for larger storage; be careful with quota and private browsing modes.
For Mobile: use SharedPreferences or secure storage for sticky assignments; consider SQLite for large datasets.

iOS/Android specific considerations

iOS backgrounding may pause network activity; prefer manual refresh on foreground via app lifecycle hooks.
Android Doze/App Standby can throttle background sync; design UX that tolerates delayed updates.

Do not rely on continuous streaming while the app is fully backgrounded; on resume, call refreshCache() and rely on backoff reconnects. See Flutter SDK repo: https://github.com/growthbook/growthbook-flutter

​Installation

​Quick Usage

​Using Features

​Attributes

​Common attributes

​What is the user context?

​Identity changes (login/logout)

​Experimentation (A/B Testing)

​Tracking & Subscriptions

​Efficient subscription patterns

​Unsubscribing and memory management

​Loading Features

​Built-in fetching and caching

​Custom integration (local evaluation)

​Caching

​Web-specific caching considerations

​Real-time Updates (SSE)

​Setup and lifecycle

​Network failures and reconnection

​Performance Considerations

​Remote Evaluation

​Remote vs local evaluation

​Configuration

​Debugging Remote Evaluation

​Security considerations

​Fallback strategies

​Sticky Bucketing

​Custom Sticky Bucketing Service configurations

​Troubleshooting stale assignments

​Encrypted features

​Performance optimizations

​Memory usage patterns

​Error handling and debugging

​Debug logging configuration

​Common error scenarios and solutions

​Feature evaluation debugging techniques

​Network connectivity troubleshooting

​Platform-specific considerations

​Web vs mobile behavior differences

​iOS/Android specific considerations

​Supported Features

Installation

Quick Usage

Using Features

Attributes

Common attributes

What is the user context?

Identity changes (login/logout)

Experimentation (A/B Testing)

Tracking & Subscriptions

Efficient subscription patterns

Unsubscribing and memory management

Loading Features

Built-in fetching and caching

Custom integration (local evaluation)

Caching

Web-specific caching considerations

Real-time Updates (SSE)

Setup and lifecycle

Network failures and reconnection

Performance Considerations

Remote Evaluation

Remote vs local evaluation

Configuration

Debugging Remote Evaluation

Security considerations

Fallback strategies

Sticky Bucketing

Custom Sticky Bucketing Service configurations

Troubleshooting stale assignments

Encrypted features

Performance optimizations

Memory usage patterns

Error handling and debugging

Debug logging configuration

Common error scenarios and solutions

Feature evaluation debugging techniques

Network connectivity troubleshooting

Platform-specific considerations

Web vs mobile behavior differences

iOS/Android specific considerations

Supported Features