SDK Usage

The OpenFeature Provider Intellitoggle SDK enables Dart backends to evaluate feature flags using the OpenFeature API standard.

The OpenFeature Provider Intellitoggle SDK integrates seamlessly with OpenFeature Dart SDK and supports IntelliToggle’s advanced targeting, rule-based rollouts, and experimentation platform.

This page walks you through the typical usage patterns of the SDK.

1. Prerequisites

Dart language version >= 3.9.3

  • An Intellitoggle account and API key

  • Familiarity with feature flags

2. Installation

Add the OpenFeature Dart SDK and OpenFeature Provider IntelliToggle SDK to your project:

pubspec.yaml

dependencies:
  openfeature_dart_server_sdk: ^0.0.12
  openfeature_provider_intellitoggle: ^0.0.5

Then run:

dart pub get

3. Initialization

Before using Intellitoggle flags, you must configure the OpenFeature SDK with the Intellitoggle provider. This example shows how to initialize the SDK, set a global provider, create a client, and evaluate a flag.

import 'package:openfeature_dart_server_sdk/openfeature_dart_server_sdk.dart';
import 'package:openfeature_provider_intellitoggle/openfeature_provider_intellitoggle.dart';

void main() async {
  // Initialize provider with OAuth2 client secret
  final provider = IntelliToggleProvider(
    sdkKey: 'YOUR_CLIENT_SECRET',
    options: IntelliToggleOptions.production(),
  );

  // Set as global provider
  await OpenFeatureAPI().setProvider(provider);

  // Create client
  final client = IntelliToggleClient(
    FeatureClient(
      metadata: ClientMetadata(name: 'my-service'),
      hookManager: HookManager(),
    ),
  );
}

4. Basic Usage

Once the Intellitoggle provider is initialized and set as the global provider, using it in your application is straightforward.

The OpenFeature client exposes simple methods to evaluate feature flags and return either a default value or a value defined in the Intellitoggle platform.

Minimal evaluation:

final enabled = await client.getBooleanValue('new-api-endpoint', false);

Flag evaluation with targeting & context:

// Evaluate flags
final enabled = await client.getBooleanValue(
  'new-api-endpoint',
  false,
  targetingKey: 'user-123',
  evaluationContext: {
    'role': 'admin',
    'plan': 'enterprise',
    'region': 'us-east',
  },
);

print('Feature enabled: $enabled');

5. Advanced Usage

Beyond simple flag checks, the Intellitoggle provider supports advanced features that allow fine-grained targeting, dynamic contexts, and lifecycle event handling. These capabilities make it possible to model complex real-world scenarios such as organizations, devices, or services in addition to individual users.

5.1. Contextual Evaluation

You can pass both a targeting key and an evaluation context when resolving flags. This allows segmentation by user roles, plans, or regions.

// Evaluate a flag with user targeting and custom attributes
final enabled = await client.getBooleanValue(
  'new-api-endpoint',
  false,
  targetingKey: 'user-123',
  evaluationContext: {
    'role': 'admin',
    'plan': 'enterprise',
    'region': 'us-east',
  },
);

print('Feature enabled: $enabled');

5.2. Multi-Context Evaluation

Evaluate flags against multiple entities at once, such as a user and their organization.

final multiContext = client.createMultiContext({
  'user': {
    'targetingKey': 'user-123',
    'role': 'admin',
    'plan': 'enterprise',
  },
  'organization': {
    'targetingKey': 'org-456',
    'tier': 'premium',
    'industry': 'fintech',
  },
});

final config = await client.getObjectValue(
  'feature-config',
  {},
  evaluationContext: multiContext.attributes,
);

5.3. Custom Context Types

Define your own context kinds (e.g., device, service) with arbitrary attributes.

final deviceContext = client.createContext(
  targetingKey: 'device-789',
  kind: 'device',
  customAttributes: {
    'os': 'linux',
    'version': '5.4.0',
    'datacenter': 'us-west-2',
  },
);

final threshold = await client.getIntegerValue(
  'rate-limit',
  1000,
  evaluationContext: deviceContext.attributes,
);

5.4. Event Handling

The Intellitoggle provider emits lifecycle events you can subscribe to, such as readiness, configuration changes, and errors.

provider.events.listen((event) {
  switch (event.type) {
    case IntelliToggleEventType.ready:
      print('Provider ready');
      break;
    case IntelliToggleEventType.configurationChanged:
      print('Flags updated: ${event.data?['flagsChanged']}');
      break;
    case IntelliToggleEventType.error:
      print('Error: ${event.message}');
      break;
  }
});

5.5. Global Context

Set attributes that apply globally to all evaluations. This is useful for environment- or service-level context.

// Set global context for all flag evaluations
OpenFeatureAPI().setGlobalContext(
  OpenFeatureEvaluationContext({
    'environment': 'production',
    'service': 'api-gateway',
    'version': '2.1.0',
  })
);

6. Configuration Options

The IntelliToggleOptions class allows you to customize how the SDK interacts with the Intellitoggle service. You can use the built-in presets for production and development environments, or define your own custom configuration.

6.1. Production Configuration

Use this when deploying your application in a production environment.

final options = IntelliToggleOptions.production(
  baseUri: Uri.parse('https://api.intellitoggle.com'),
  timeout: Duration(seconds: 10),
  pollingInterval: Duration(minutes: 5),
);

6.2. Development Configuration

Use this during local development and testing. By default, it points to a localhost server.

final options = IntelliToggleOptions.development(
  baseUri: Uri.parse('http://localhost:8080'),
  timeout: Duration(seconds: 5),
);

6.3. Custom Configuration

For advanced scenarios, you can build a fully customized configuration object.

final options = IntelliToggleOptions(
  timeout: Duration(seconds: 15),
  enablePolling: true,
  pollingInterval: Duration(minutes: 2),
  enableStreaming: true,
  maxRetries: 5,
  enableLogging: true,
);

7. Provider Options

The IntelliToggleProvider accepts an IntelliToggleOptions object to control how the SDK connects to the Intellitoggle service and manages feature flag updates.

7.1. IntelliToggleOptions

Option Description Default

baseUri

API endpoint used to fetch flag configurations

https://api.intellitoggle.com

timeout

Maximum request duration before failing

10 seconds

enablePolling

Whether to poll periodically for configuration changes

true

pollingInterval

How often to poll for updates when polling is enabled

5 minutes

enableStreaming

Enables real-time updates from the service if supported

false

maxRetries

Number of retry attempts for failed requests

3

enableLogging

Enables verbose debug logging for troubleshooting

false

You can combine these options or define your own when creating the provider:

final provider = IntelliToggleProvider(
  sdkKey: 'YOUR_CLIENT_SECRET',
  options: IntelliToggleOptions(
    timeout: Duration(seconds: 15),
    enablePolling: true,
    pollingInterval: Duration(minutes: 2),
    enableStreaming: true,
    maxRetries: 5,
    enableLogging: true,
  ),
);

8. Resources