growthbook-flutter

KO | EN

gitlite — search

#hacktoberfest #go #rust #docker #java #windows #kubernetes #awesome-list #security #pytorch #mcp #ios #openai #open-source

growthbook-flutter

(★ 12)

GrowthBook Flutter SDK

growthbook-flutter 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# GrowthBook Flutter SDK

![GrowthBook Flutter SDK](https://docs.growthbook.io/images/hero-flutter-sdk.png)

[![pub package](https://img.shields.io/pub/v/growthbook_sdk_flutter.svg)](https://pub.dev/packages/growthbook_sdk_flutter)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
![Platform](https://img.shields.io/badge/platform-flutter-blue)
![Dart](https://img.shields.io/badge/dart-%230175C2.svg?style=flat&logo=dart&logoColor=white)

**🎯 Feature flags • 🧪 A/B testing • 📊 Analytics integration**

[Quick Start](#-quick-start) • [Features](#-features) • [Documentation](#-documentation) • [Examples](#-examples) • [Resources](#-resources)

</div>

## Overview

GrowthBook is an open source feature flagging and experimentation platform. This Flutter SDK allows you to use GrowthBook with your Flutter based mobile application.

**Platform Support:**

- 📱 **Android** 21+ • **iOS** 12+ 
- 📺 **tvOS** 13+ • ⌚ **watchOS** 7+
- 🖥️ **macOS** • **Windows** • **Linux**
- 🌐 **Web** (Flutter Web)

---

## ✨ Features

- **Lightweight** - Minimal performance impact
- **Type Safe** - Full Dart/Flutter type safety
- **Caching** - Smart caching with TTL and stale-while-revalidate
- **Cross-platform** - Works on Android, iOS, Web, Desktop

### 🏗️ **Core Capabilities**

- **Feature Flags** - Toggle features on/off without code deployments
- **A/B Testing** - Run experiments with statistical significance  
- **Targeting** - Advanced user segmentation, variation weights and targeting rules
- **Tracking** - Use your existing event tracking (GA, Segment, Mixpanel, custom)
- **Real-time Updates** - Features update instantly via streaming

### 🎯 **Advanced Features**

- **Sticky Bucketing** - Consistent user experiences across sessions
- **Remote Evaluation** - Server-side evaluation for enhanced security
- **Multi-variate Testing** - Test multiple variations simultaneously
- **Rollout Management** - Gradual feature rollouts with traffic control

## 📋 Supported Features

| Feature | Support | Since Version |
|---------|---------|---------------|
| ✅ **Feature Flags** | Full Support | All versions |
| ✅ **A/B Testing** | Full Support | All versions |
| ✅ **Sticky Bucketing** | Full Support | ≥ v3.8.0 |
| ✅ **Remote Evaluation** | Full Support | ≥ v3.7.0 |
| ✅ **Streaming Updates** | Full Support | ≥ v3.4.0 |
| ✅ **Prerequisites** | Full Support | ≥ v3.2.0 |
| ✅ **Encrypted Features** | Full Support | ≥ v3.1.0 |
| ✅ **v2 Hashing** | Full Support | ≥ v3.1.0 |
| ✅ **SemVer Targeting** | Full Support | ≥ v3.1.0 |
| ✅ **TTL Caching** | Full Support | ≥ v3.9.10 |

> 📖 **[View complete feature support matrix →](https://docs.growthbook.io/lib/flutter#supported-features)**

---

## 🚀 Quick Start

> 📖 **[View official installation guide →](https://docs.growthbook.io/lib/flutter#installation)**

### 1. Installation

Add to your `pubspec.yaml`:

```yaml
dependencies:
  growthbook_sdk_flutter: ^3.9.10
```

### 2. Basic Setup

> 📖 **[View complete usage guide →](https://docs.growthbook.io/lib/flutter#quick-usage)**

```dart
import 'package:growthbook_sdk_flutter/growthbook_sdk_flutter.dart';

// Initialize the SDK
final sdk = await GBSDKBuilderApp(
  apiKey: "sdk_your_api_key",
  hostURL: "https://growthbook.io",
  attributes: {
    'id': 'user_123',
    'email': 'user@example.com',
    'country': 'US',
  },
  growthBookTrackingCallBack: (trackData) {
    // Track experiment exposures
    final experiment = trackData.experiment;
    final result = trackData.experimentResult;
    print('Experiment: ${experiment.key}, Variation: ${result.variationID}');
  },
).initialize();

// Use feature flags
final welcomeMessage = sdk.feature('welcome_message');
if (welcomeMessage.on) {
  print('Feature is enabled: ${welcomeMessage.value}');
}

// Run A/B tests
final buttonExperiment = GBExperiment(key: 'button_color_test');
final result = sdk.run(buttonExperiment);
final buttonColor = result.value ?? 'blue'; // Default color
```

### 3. Widget Integration

```dart
class MyHomePage extends StatelessWidget {
  final GrowthBookSDK sdk;
  
  @override
  Widget build(BuildContext context) {
    final newDesign = sdk.feature('new_homepage_design');
    
    return Scaffold(
      body: newDesign.on 
        ? NewHomepageWidget() 
        : ClassicHomepageWidget(),
    );
  }
}
```

---

## Analytics

```dart
final sdk = await GBSDKBuilderApp(
  apiKey: "your_api_key",
  growthBookTrackingCallBack: (trackData) {
    final experiment = trackData.experiment;
    final result = trackData.experimentResult;

// Google Analytics
    FirebaseAnalytics.instance.logEvent(
      name: 'experiment_viewed',
      parameters: {
        'experiment_id': experiment.key,
        'variation_id': result.variationID,
        'variation_name': result.key,
      },
    );
    
    // Mixpanel
    Mixpanel.track('Experiment Viewed', {
      'Experiment ID': experiment.key,
      'Variation ID': result.variationID,
    });
    
    // Custom analytics
    YourAnalytics.trackExperiment(experiment, result);
  },
).initialize();
```

---

## 📚 Documentation

### Configuration Options

```dart
final sdk = await GBSDKBuilderApp(
  // Required
  apiKey: "sdk_your_api_key",
  hostURL: "https://growthbook.io",
  
  // User Context
  attributes: {
    'id': 'user_123',
    'email': 'user@example.com',
    'plan': 'premium',
    'country': 'US',
  },
  
  // Performance & Caching
  ttlSeconds: 300,              // Cache TTL (default: 60s)
  backgroundSync: true,         // Real-time updates
  
  // Testing & QA
  qaMode: false,                // Disable randomization for QA
  forcedVariations: {           // Force specific variations
    'button_test': 1,
  },
  
  // Analytics Integration
  growthBookTrackingCallBack: (trackData) {
    // Send to your analytics platform
    final experiment = trackData.experiment;
    final result = trackData.experimentResult;
    analytics.track('Experiment Viewed', {
      'experiment_id': experiment.key,
      'variation_id': result.variationID,
      'variation_name': result.key,
    });
  },
  
  // Advanced Features
  remoteEval: false,            // Server-side evaluation
  encryptionKey: "...",         // For encrypted features
).initialize();
```

### Configuring Log Level

The SDK logs internal events (feature evaluation skips, cache errors, refresh
attempts) through a `logger` package instance. Verbosity is controlled by
`GrowthBookSDK.setLogLevel(...)`, which accepts an SDK-owned `GBLogLevel` enum:

```dart
import 'package:growthbook_sdk_flutter/growthbook_sdk_flutter.dart';

void main() {
  // Configure once at app startup — before initializing the SDK.
  GrowthBookSDK.setLogLevel(GBLogLevel.debug);

runApp(const MyApp());
}
```

Available levels: `verbose`, `debug`, `info`, `warning` (default), `error`, `off`.

> ⚠️ **Process-global**: log level is shared across all `GrowthBookSDK` instances
> in the same process. Set it once at app startup rather than per-instance.
> If you run multiple SDK instances, they will share the same verbosity.

### Feature Flag Usage

> 📖 **[View detailed feature usage guide →](https://docs.growthbook.io/lib/flutter#using-features)**

```dart
// Boolean flags
final isEnabled = sdk.feature('new_feature').on;

// String values
final welcomeText = sdk.feature('welcome_message').value ?? 'Welcome!';

// Number values  
final maxItems = sdk.feature('max_items').value ?? 10;

// JSON objects
final config = sdk.feature('app_config').value ?? {
  'theme': 'light',
  'animations': true,
};

// Check feature source
final feature = sdk.feature('premium_feature');
switch (feature.source) {
  case GBFeatureSource.experiment:
    print('Value from A/B test');
    break;
  case GBFeatureSource.force:
    print('Forced value');
    break;
  case GBFeatureSource.defaultValue:
    print('Default value');
    break;
}
```

### Experiments - A/B Testing

> 📖 **[View inline experiments guide →](https://docs.growthbook.io/lib/flutter#running-inline-experiments)**

```dart
// Define experiment
final experiment = GBExperiment(
  key: 'checkout_button_test',
  variations: ['🛒 Buy Now', '💳 Purchase', '✨ Get It Now'],
  weights: [0.33, 0.33, 0.34], // Traffic distribution
);

// Run experiment
final result = sdk.run(experiment);

// Use result
Widget buildButton() {
  final buttonText = result.value ?? '🛒 Buy Now';
  return ElevatedButton(
    onPressed: () => handlePurchase(),
    child: Text(buttonText),
  );
}

// Track conversion
if (purchaseCompleted) {
  // Your analytics will receive this via trackingCallBack
}
```

### User Attributes & Targeting

```dart
// Update user attributes dynamically
sdk.setAttributes({
  'plan': 'enterprise',
  'feature_flags_enabled': true,
  'last_login': DateTime.now().toIso8601String(),
});

// Target users with conditions
// Example: Show feature only to premium users in US
// This is configured in GrowthBook dashboard, not in code
```

### Condition Operators

The SDK supports the following operators in targeting conditions:

#### Comparison

| Operator | Description |
|----------|-------------|
| `$eq` | Equal to |
| `$ne` | Not equal to |
| `$lt` | Less than |
| `$lte` | Less than or equal |
| `$gt` | Greater than |
| `$gte` | Greater than or equal |

#### Membership

| Operator | Description |
|----------|-------------|
| `$in` | Value is in array |
| `$nin` | Value is not in array |
| `$all` | Array contains all values |
| `$ini` | Value is in array (case-insensitive string comparison) |
| `$nini` | Value is not in array (case-insensitive string comparison) |
| `$alli` | Array contains all values (case-insensitive string comparison) |

> For `$ini`, `$nini`, and `$alli`: string values are compared after lowercasing; non-string values (numbers, booleans, null) are compared as-is.

#### Regex

| Operator | Description |
|----------|-------------|
| `$regex` | Matches regex (case-sensitive) |
| `$notRegex` | Does not match regex (case-sensitive) |
| `$regexi` | Matches regex (case-insensitive) |
| `$notRegexi` | Does not match regex (case-insensitive) |

#### Other

| Operator | Description |
|----------|-------------|
| `$exists` | Attribute exists (`true`) or is absent (`false`) |
| `$type` | Attribute type matches string (`"string"`, `"number"`, `"boolean"`, `"array"`, `"object"`, `"null"`) |
| `$not` | Negates a condition |
| `$size` | Array length matches condition |
| `$elemMatch` | At least one array element matches condition |
| `$vgt` / `$vlt` / `$vgte` / `$vlte` / `$veq` / `$vne` | Semantic version comparison |

```dart
// Example: case-insensitive membership
// Matches users where country is "us", "US", "Us", etc.
final condition = {
  'country': {'\$ini': ['US', 'CA', 'GB']}
};

// Example: case-insensitive regex
// Matches "Hello", "hello", "HELLO", etc.
final condition2 = {
  'greeting': {'\$regexi': '^hello'}
};
```

---

## 🔧 Advanced Features

### Smart Caching Strategy

The SDK implements an intelligent caching system for optimal performance:

```dart
final sdk = await GBSDKBuilderApp(
  apiKey: "your_api_key",
  ttlSeconds: 300, // Cache TTL: 5 minutes
  backgroundSync: true, // Enable background refresh
).initialize();
```

#### **How it works:**

1. **🚀 Instant Response** - Serve cached features immediately
2. **🔄 Background Refresh** - Fetch updates in the background  
3. **⚡ Stale-While-Revalidate** - Show cached data while updating
4. **📊 Smart Invalidation** - Refresh only when needed

#### **Benefits:**

- ✅ **Zero loading delays** for feature flags
- ✅ **Always up-to-date** with background sync
- ✅ **Reduced API calls** with intelligent caching
- ✅ **Offline resilience** with cached fallbacks

### Sticky Bucketing

> 📖 **[Learn about sticky bucketing →](https://docs.growthbook.io/app/sticky-bucketing)**

Ensure consistent user experiences across sessions:

```dart
class MyAppStickyBucketService extends GBStickyBucketService {
  @override
  Future<Map<String, String>?> getAllAssignments(
    Map<String, dynamic> attributes,
  ) async {
    // Retrieve from local storage
    final prefs = await SharedPreferences.getInstance();
    final json = prefs.getString('gb_sticky_assignments');
    return json != null ? jsonDecode(json) : null;
  }
  
  @override
  Future<void> saveAssignments(
    Map<String, dynamic> attributes,
    Map<String, String> assignments,
  ) async {
    // Save to local storage
    final prefs = await SharedPreferences.getInstance();
    await prefs.setString('gb_sticky_assignments', jsonEncode(assignments));
  }
}

// Use with SDK
final sdk = await GBSDKBuilderApp(
  apiKey: "your_api_key",
  stickyBucketService: MyAppStickyBucketService(),
).initialize();
```

### Remote Evaluation

The Flutter SDK may be run in Remote Evaluation mode. This mode brings the security benefits of a backend SDK to the front end by evaluating feature flags exclusively on a private server. Using Remote Evaluation ensures that any sensitive information within targeting rules or unused feature variations are never seen by the client.

You must enable Remote Evaluation in your SDK Connection settings. Cloud customers are also required to self-host a GrowthBook Proxy Server or a custom remote evaluation backend.

To use Remote Evaluation, add the remoteEval: true property to your SDK instance.

```dart
final sdk = await GBSDKBuilderApp(
  apiKey: "your_api_key",
  remoteEval: true, // Enable remote evaluation
  attributes: userAttributes,
).initialize();

// Features are evaluated server-side
// Sensitive targeting rules never reach the client
```

### Real-time Updates

The GrowthBook SDK supports streaming with Server-Sent Events (SSE). When enabled, changes to features within GrowthBook will be streamed to the SDK in realtime as they are published. This is only supported on GrowthBook Cloud or if running a GrowthBook Proxy Server.

```dart
final sdk = await GBSDKBuilderApp(
  apiKey: "your_api_key",
  backgroundSync: true, // Enable streaming updates
).initialize();

// Features automatically update when changed in GrowthBook
// No need to restart the app or refresh manually
```

### Tracking Plugins

Plugins observe SDK lifecycle events (feature evaluated, experiment viewed) and can implement custom side effects such as forwarding events to an analytics backend. The SDK ships with `GrowthBookTrackingPlugin`, which batches events and sends them to the GrowthBook ingest endpoint.

```dart
import 'package:growthbook_sdk_flutter/growthbook_sdk_flutter.dart';

Future<void> main() async {
  final sdk = await GBSDKBuilderApp(
    apiKey: 'sdk-xxx',
    hostURL: 'https://cdn.growthbook.io',
    growthBookTrackingCallBack: (_) {},
  )
      .addPlugin(GrowthBookTrackingPlugin())
      .initialize();

runApp(MyApp(sdk: sdk));
}
```

#### Custom configuration

```dart
final trackingPlugin = GrowthBookTrackingPlugin(
  config: GrowthBookTrackingPluginConfig(
    ingestorHost: 'https://ingest.growthbook.io',
    batchSize: 50,
    batchTimeout: Duration(seconds: 30),
  ),
);

await GBSDKBuilderApp(...)
    .addPlugin(trackingPlugin)
    .initialize();
```

#### Lifecycle — always await `dispose()`

Tracking plugins buffer events in memory to reduce network overhead. **You must call `await sdk.dispose()` when the SDK instance is no longer needed** so buffered events are flushed and any resources (timers, HTTP clients) are released. Without this, queued tracking events will be dropped during app shutdown.

```dart
class _MyAppState extends State<MyApp> {
  late final GrowthBookSDK sdk;

@override
  void initState() {
    super.initState();
    _initSdk();
  }

Future<void> _initSdk() async {
    sdk = await GBSDKBuilderApp(...)
        .addPlugin(GrowthBookTrackingPlugin())
        .initialize();
  }

@override
  void dispose() {
    // Flushes pending tracking events and releases plugin resources
    sdk.dispose();
    super.dispose();
  }
}
```

For CLI tools, server processes, or short-lived isolates, wrap SDK usage in a `try`/`finally`:

```dart
final sdk = await GBSDKBuilderApp(...).addPlugin(GrowthBookTrackingPlugin()).initialize();
try {
  // ... SDK usage
} finally {
  await sdk.dispose();
}
```

#### Custom plugins

Extend `GrowthBookPlugin` to implement your own tracking, logging, or analytics forwarding:

```dart
class MyAnalyticsPlugin extends GrowthBookPlugin {
  @override
  void initialize(String clientKey) {
    // one-time setup (e.g. start a periodic flush timer)
  }

@override
  void onFeatureEvaluated(String id, GBFeatureResult result, Map<String, dynamic>? attributes) {
    // forward to your analytics
  }

@override
  void onExperimentViewed(GBExperiment experiment, GBExperimentResult result, Map<String, dynamic>? attributes) {
    // forward to your analytics
  }

@override
  Future<void> close() async {
    // flush any buffered state, release resources
  }
}
```

> ⚠️ Plugin errors are isolated per plugin — a throw in one plugin's callback does not affect other plugins or SDK evaluation. If you need stronger delivery guarantees than best-effort batching, implement retry/requeue with bounded storage inside your plugin's `close()` method.

---

## 💡 Examples

### E-commerce App

```dart
class ProductPage extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    final sdk = context.read<GrowthBookSDK>();
    
    // Feature flags
    final showReviews = sdk.feature('show_product_reviews').on;
    final freeShipping = sdk.feature('free_shipping_threshold').value ?? 50.0;
    
    // A/B test for pricing display
    final pricingExperiment = GBExperiment(key: 'pricing_display_test');
    final pricingResult = sdk.run(pricingExperiment);
    
    return Scaffold(
      body: Column(
        children: [
          ProductImage(),
          ProductTitle(),
          
          // Dynamic pricing display based on A/B test
          if (pricingResult.value == 'with_discount')
            PricingWithDiscount()
          else
            StandardPricing(),
            
          // Conditional features
          if (showReviews) ProductReviews(),
          if (freeShipping > 0) FreeShippingBanner(threshold: freeShipping),
          
          AddToCartButton(),
        ],
      ),
    );
  }
}
```

### Gradual Feature Rollout

```dart
class NewFeatureService {
  final GrowthBookSDK sdk;
  
  NewFeatureService(this.sdk);
  
  bool get isNewDashboardEnabled {
    final feature = sdk.feature('new_dashboard_v2');
    
    // Feature is rolled out gradually:
    // 0% → 5% → 25% → 50% → 100%
    // Configured in GrowthBook dashboard
    return feature.on;
  }
  
  Widget buildDashboard() {
    return isNewDashboardEnabled 
      ? NewDashboardWidget()
      : LegacyDashboardWidget();
  }
}
```

---

## 🛠️ Development

### Local Development Setup

#### **1. Clone and Setup**

```bash
# Clone the repository
git clone https://github.com/growthbook/growthbook-flutter.git
cd growthbook-flutter

# Install dependencies
flutter pub get

# Generate code (for json_serializable)
dart run build_runner build --delete-conflicting-outputs
```

#### **2. Run Tests**

```bash
# Run all tests
flutter test

# Run tests with coverage
flutter test --coverage

# Run specific test file
flutter test test/features/feature_test.dart
```

#### **3. Code Generation**

The SDK uses `json_serializable` for JSON parsing. When you modify model classes with `@JsonSerializable()`, run:

```bash
# Watch for changes and auto-generate
dart run build_runner watch

# One-time generation
dart run build_runner build --delete-conflicting-outputs
```

#### **4. Linting and Formatting**

```bash
# Check linting
dart analyze

# Format code
dart format .

# Fix auto-fixable issues
dart fix --apply
```

#### **5. Building Examples**

```bash
cd example
flutter pub get
flutter run
```

### Testing

```dart
// Mock SDK for testing
class MockGrowthBookSDK implements GrowthBookSDK {
  final Map<String, dynamic> mockFeatures;
  
  MockGrowthBookSDK({required this.mockFeatures});
  
  @override
  GBFeatureResult feature(String key) {
    final value = mockFeatures[key];
    return GBFeatureResult(
      value: value,
      on: value == true,
      source: GBFeatureSource.force,
    );
  }
}

// Use in tests
void main() {
  testWidgets('shows new feature when enabled', (tester) async {
    final mockSDK = MockGrowthBookSDK(
      mockFeatures: {'new_feature': true},
    );
    
    await tester.pumpWidget(MyApp(sdk: mockSDK));
    
    expect(find.text('New Feature'), findsOneWidget);
  });
}
```

### Build Integration

```dart
// Different configurations for different environments
final sdk = await GBSDKBuilderApp(
  apiKey: kDebugMode 
    ? "sdk_dev_your_dev_key"
    : "sdk_prod_your_prod_key",
  hostURL: kDebugMode 
    ? "https://growthbook-dev.yourcompany.com"
    : "https://growthbook.yourcompany.com",
  qaMode: kDebugMode, // Disable randomization in debug
).initialize();
```

### Contributing

We welcome contributions! Here's how to get started:

1. **Fork the repository** and create a feature branch
2. **Make your changes** following our coding conventions
3. **Add tests** for any new functionality
4. **Ensure all tests pass**: `flutter test`
5. **Format code**: `dart format .`
6. **Submit a pull request** with a clear description

#### **Pull Request Guidelines:**

- ✅ Include tests for new features
- ✅ Update documentation if needed
- ✅ Follow existing code style
- ✅ Keep commits atomic and well-described
- ✅ Reference any related issues

#### **Release Process:**

- Uses automated releases via **release-please**
- Follow conventional commits: `feat:`, `fix:`, `docs:`, etc.
- Automatic version bumping and changelog generation

---

## 🔗 Resources

- 📖 **[Official Documentation](https://docs.growthbook.io/)**
- 🎯 **[GrowthBook Dashboard](https://app.growthbook.io/)**
- 💬 **[Community Slack](https://slack.growthbook.io/)**
- 🐛 **[Report Issues](https://github.com/growthbook/growthbook-flutter/issues)**
- 📦 **[pub.dev Package](https://pub.dev/packages/growthbook_sdk_flutter)**

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 Acknowledgments

Originally contributed by the team at [Alippo](https://alippo.com/). The core GrowthBook platform remains open-source and free forever.

---

**Made with ❤️ by the GrowthBook community**

[⭐ Star on GitHub](https://github.com/growthbook/growthbook-flutter) • [🐦 Follow on Twitter](https://twitter.com/growthbook)

</div>

growthbook-flutter

growthbook-flutter 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

growthbook-flutter

growthbook-flutter 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README