Flutter SDK

Using an AI assistant? See AI assistants for how to give it these docs.

1Installation#

Install from Abrova Center in two steps. First add the package to your pubspec.yaml with the Abrova Center address:

dependencies:
  abrova_flutter_flags:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.0

Then run:

flutter pub get

2Initialization#

Call AbrovaFlags.init once, before runApp. Use your public API key (ab_live_...).

import 'package:flutter/material.dart';
import 'package:abrova_flutter_flags/abrova_flutter_flags.dart';

Future<void> main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaFlags.init(const AbrovaFlagsConfig(
    apiKey: 'ab_live_xxx',
    environment: 'production', // leave out to use the Default values
  ));

  runApp(const MyApp());
}

init serves the values cached on the device right away and waits up to initTimeout (5 seconds) for the first answer from the network. If the network is slow, init returns anyway and the fetch continues in the background.

3Read flags#

Getters are synchronous and never throw. Each one takes the default to use when the flag is unknown, when no values are available yet, or when the flag has another type.

final flags = AbrovaFlags.instance;

if (flags.isEnabled('new-checkout')) {
  // Show the new checkout
}

final dark = flags.getBool('dark-mode', false);
final theme = flags.getString('theme', 'light');
final maxItems = flags.getNumber('max-items', 10);
final layout = flags.getJson('home-layout', {'columns': 2});

Details and reasons

Each typed getter has a ...Detail form that also tells you why you got the value.

final d = flags.getStringDetail('theme', 'light');
print('${d.value} ${d.enabled} ${d.variant} ${d.reason} ${d.version}');

getBoolDetail, getStringDetail, getNumberDetail and getJsonDetail check the flag type. getDetail(key, [defaultValue]) returns the stored value without a type check.

The constants are on AbrovaFlagReason (for example AbrovaFlagReason.notReady). isEnabled is true only for ON and VARIANT.

4Identify the user#

Tell the SDK who the user is and what you know about them. Targeting rules and percentage rollouts are evaluated against this context.

// After sign-in
await flags.identify('user-123', attributes: {
  'plan': 'pro',
  'country': 'IR',
  'beta': true,
});

// Replace all attributes
await flags.setAttributes({'plan': 'business'});

// Signed out, attributes stay
await flags.setUserId(null);

// Sign-out: clears the user id, the attributes and the cached values
await flags.reset();

• Each change fetches new values after a short pause (250 ms), so several calls in a row send one request.
• setAttributes and the attributes of identify replace the whole set. They do not merge.
• When the user id changes, the previous user's values are dropped at once. Until the new values arrive, getters return your defaults (reason NOT_READY).
• Attributes are strings, numbers, booleans, null, or lists of those. No nested maps. At most 100 attributes; a string holds at most 1,024 characters.

If you already know the user at start, pass userId and attributes in the config. The SDK then serves that user's cached values immediately and sends one request instead of two.

await AbrovaFlags.init(AbrovaFlagsConfig(
  apiKey: 'ab_live_xxx',
  environment: 'production',
  userId: currentUser?.id,
  attributes: {'plan': 'pro'},
));

Anonymous id

Every install gets a random anonymous id (a UUID). It is stored on the device and sent with every request, so a 10% rollout reaches about 10% of signed-out installs too. When a user id is set, rollouts use the user id instead.

The anonymous id survives reset(). Call resetAnonymousId() to replace it. Read it with flags.anonymousId.

5Updates and refresh#

// New values arrived
final sub = flags.onChange.listen((_) => setState(() {}));

// A request failed
flags.onError.listen((e) => debugPrint('${e.statusCode} ${e.code} ${e.message}'));

// Fetch now
await flags.refresh();

The SDK fetches values:

• on init,
• after identify, setUserId, setAttributes, reset and resetAnonymousId,
• when the app returns to the foreground and the last fetch is older than 15 minutes,
• on refresh(),
• on a timer, only if you set refreshIntervalSeconds.

6Offline and errors#

The last values are stored with shared_preferences and served at the next start, before the network answers. A failed request never clears them.

• Offline or server error: the last values keep being served. The SDK retries with a growing delay (up to 5 minutes).
• Rate limited (429): the SDK waits the time the service asks for, then retries.
• 401, 403 or 404 (wrong key, Flags not enabled for the project, unknown environment): automatic fetches stop until you call refresh() or restart the app. Check flags.lastError.
• Before the first values: flags.isReady is false and getters return your defaults. await flags.whenReady completes when values are available.

Call flags.close() when you no longer need the client.

Configuration Options#

Testing#

AbrovaFlags.create builds a client without touching AbrovaFlags.instance. Pass MemoryFlagsStorage() and your own http.Client (for example MockClient from package:http/testing.dart).

final flags = await AbrovaFlags.create(
  const AbrovaFlagsConfig(apiKey: 'ab_live_xxx'),
  storage: MemoryFlagsStorage(),
  httpClient: mockClient,
  observeAppLifecycle: false,
);

Upgrading from 0.1.x#

0.2.0 is a new API, and 0.1.x clients stop receiving flags. Update the package and change these calls:

• The class was renamed to AbrovaFlags, so it no longer clashes with AbrovaFeatureFlags in the Abrova A/B Testing Flutter SDK. You can import both packages.
• connectivity_plus and crypto are no longer needed by the SDK.
• Rollouts use a new bucketing method, so users are assigned to rollouts and variants again once.

Best Practices#