A/B Testing Flutter SDK

dependencies:
  abrova_ab_testing:
    hosted: https://center.abrova.ir/api/packages/abrova/pub
    version: ^0.2.3

flutter pub get

<uses-permission android:name="android.permission.INTERNET" />

import 'dart:convert';

import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:abrova_ab_testing/abrova_ab_testing.dart';

/// Calls YOUR backend, which mints the token with your server secret.
/// Returns null while no one is signed in.
Future<String?> fetchAbrovaToken() async {
  if (yourSessionToken == null) return null;
  final res = await http.post(
    Uri.parse('https://your-api.example.com/abrova-token'),
    headers: {'Authorization': 'Bearer $yourSessionToken'}, // your app's own login session
  );
  return jsonDecode(res.body)['token'] as String;
}

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaAbTesting.init(
    AbrovaAbTestingConfig(
      apiKey: 'YOUR_API_KEY',
      tokenProvider: fetchAbrovaToken, // required for variants, events and flags
      debug: true,                     // Enable debug logging
      // flushInterval: 10000,         // Your own send interval in ms. Leave it out to follow the console
      maxQueueSize: 100,               // Maximum events to queue
    ),
    callback: (event, data) {
      print('AbrovaAbTesting event: $event, data: $data');
    },
  );

  runApp(const MyApp());
}

// Call this after your user signs in
Future<void> onSignedIn(String userId) async {
  await AbrovaAbTesting.instance.setUserId(userId);   // the id your server puts in the token
  await AbrovaAbTesting.instance.refreshUserToken();  // asks tokenProvider again now
}

// Call this after your user signs out
Future<void> onSignedOut() async {
  await AbrovaAbTesting.instance.clearUserId();
}

curl -X POST https://auth.abrova.ir/users/token \
  -H "x-api-key: $ABROVA_API_KEY" \
  -H "x-server-secret: $ABROVA_SERVER_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"userId": "user-123", "expiresIn": 3600}'
# → { "token": "eyJhbGciOi…", "userId": "user-123", "expiresIn": 3600, "expiresAt": "…" }

final ab = AbrovaAbTesting.instance;

ab.isAwaitingUserToken;            // true while there is no user token
ab.onAwaitingUserToken(() { });    // called each time the SDK starts waiting

// After sign-in
await ab.refreshUserToken();       // with a tokenProvider: asks it again now
await ab.setUserToken(token);      // without one: hand the token over

// After sign-out
await ab.clearUserId();            // or setUserToken(null)

// Set user ID (e.g., after login)
await AbrovaAbTesting.instance.setUserId('user-123');

// Forget the user (after logout)
await AbrovaAbTesting.instance.clearUserId();

// Get current user ID
final userId = AbrovaAbTesting.instance.getUserId();

// Set user attributes for targeting
AbrovaAbTesting.instance.setUserAttributes({
  'plan': 'premium',
  'country': 'US',
  'age': 25,
  'is_beta_user': true,
});

// Get variant for an experiment
final variant = await AbrovaAbTesting.instance.getVariant(
  'checkout-button-color',
  defaultVariant: 'control', // returned while the service has not assigned one
);

// Use the variant
switch (variant) {
  case 'Variant A':
    buttonColor = Colors.green;
    break;
  case 'Variant B':
    buttonColor = Colors.blue;
    break;
  default:
    buttonColor = Colors.grey; // control
}

// Get variant config as a Map
final config = await AbrovaAbTesting.instance.getVariantConfig('checkout-button-color');

// Access config values
final buttonText = config?['buttonText'] as String? ?? 'Buy Now';
final buttonColorHex = config?['buttonColor'] as String? ?? '#6B7280';

// Get all cached experiments
final experiments = AbrovaAbTesting.instance.getExperiments();
for (final experiment in experiments) {
  print('${experiment.key}: ${experiment.status}');
}

final sdk = AbrovaAbTesting.instance;

// Track view
await sdk.trackView('checkout-button-color');

// Track click
await sdk.trackClick('checkout-button-color');

// Track conversion with optional value
await sdk.trackConversion('checkout-button-color', value: 300000);

// Track custom event
await sdk.trackCustomEvent(
  'checkout-button-color',
  'add_to_cart',
  properties: {
    'product_id': 'SKU123',
    'quantity': 2,
  },
);

final sdk = AbrovaAbTesting.instance;

// Add to cart
await sdk.trackAddToCart('checkout-flow', value: 200000, productId: 'SKU123');

// Remove from cart
await sdk.trackRemoveFromCart('checkout-flow', value: 200000, productId: 'SKU123');

// Begin checkout
await sdk.trackBeginCheckout('checkout-flow', value: 600000);

// Purchase
await sdk.trackPurchase('checkout-flow',
  value: 600000,
  transactionId: 'txn_abc123',
  properties: {'currency': 'Toman'},
);

final sdk = AbrovaAbTesting.instance;

// Scroll tracking
await sdk.trackScroll('landing-page', depth: 75.0);

// Form submission
await sdk.trackFormSubmit('signup-flow', formName: 'registration');

// Search
await sdk.trackSearch('search-experiment', query: 'flutter sdk');

// Share
await sdk.trackShare('referral-test', method: 'email');

final sdk = AbrovaAbTesting.instance;

// Sign up
await sdk.trackSignUp('onboarding-flow', method: 'google');

// Login
await sdk.trackLogin('auth-experiment', method: 'email');

// Logout
await sdk.trackLogout('auth-experiment');

final sdk = AbrovaAbTesting.instance;

// Video start
await sdk.trackVideoStart('video-experiment', videoId: 'vid_123');

// Video complete
await sdk.trackVideoComplete('video-experiment', videoId: 'vid_123');

// Track any event type with full control
await AbrovaAbTesting.instance.track(
  'my-experiment',
  EventType.custom,
  eventName: 'my_custom_event',
  eventValue: 42.0,
  properties: {'key': 'value'},
);

final sdk = AbrovaAbTesting.instance;

// Check if feature is enabled
final isEnabled = await sdk.isFeatureEnabled('new-checkout-flow');

if (isEnabled) {
  return NewCheckoutPage();
} else {
  return OldCheckoutPage();
}

// Get feature flag value (for multivariate flags)
final bannerText = await sdk.getFeatureValue(
  'banner-text',
  defaultValue: 'Welcome!',
);

// Get all feature flags
final flags = await sdk.getFeatureFlags();
for (final flag in flags) {
  print('${flag.key}: ${flag.enabled}');
}

// Refresh flags from server
await sdk.refreshFeatureFlags();

await AbrovaFeatureFlags.init(
  AbrovaFeatureFlagsConfig(
    apiKey: 'YOUR_API_KEY',
    tokenProvider: fetchAbrovaToken,
  ),
);

await AbrovaFeatureFlags.instance.setUserId('user-123');

if (await AbrovaFeatureFlags.instance.isEnabled('dark-mode')) {
  // Show dark mode
}

final maxUpload = await AbrovaFeatureFlags.instance.getValue(
  'max-upload-size',
  defaultValue: 10,
);

class _MyAppState extends State<MyApp> with WidgetsBindingObserver {
  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused) {
      // Flush events before app goes to background
      AbrovaAbTesting.instance.flush();
    }
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    AbrovaAbTesting.instance.dispose();
    super.dispose();
  }
}

// Flush events immediately
await AbrovaAbTesting.instance.flush();

// Check pending event count
final pending = await AbrovaAbTesting.instance.getPendingEventCount();
print('Pending events: $pending');

// Check connectivity
final isOnline = AbrovaAbTesting.instance.isOnline;
print('Online: $isOnline');

// Refresh experiments from server
await AbrovaAbTesting.instance.refreshExperiments();

// Wipe all SDK state, including unsent events. You must call init() again afterwards.
// To switch users, call setUserId() on login and clearUserId() on logout instead.
await AbrovaAbTesting.instance.reset();

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  await AbrovaAbTesting.init(
    AbrovaAbTestingConfig(
      apiKey: 'YOUR_API_KEY',
      tokenProvider: fetchAbrovaToken, // see Initialization
      debug: true,
    ),
  );

  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(home: const CheckoutPage());
  }
}

class CheckoutPage extends StatefulWidget {
  const CheckoutPage({super.key});

  @override
  State<CheckoutPage> createState() => _CheckoutPageState();
}

class _CheckoutPageState extends State<CheckoutPage> with WidgetsBindingObserver {
  String _variant = 'control';
  bool _newCheckoutEnabled = false;
  bool _loading = true;

  @override
  void initState() {
    super.initState();
    WidgetsBinding.instance.addObserver(this);
    _init();
  }

  @override
  void dispose() {
    WidgetsBinding.instance.removeObserver(this);
    super.dispose();
  }

  @override
  void didChangeAppLifecycleState(AppLifecycleState state) {
    if (state == AppLifecycleState.paused) {
      AbrovaAbTesting.instance.flush();
    }
  }

  Future<void> _init() async {
    final sdk = AbrovaAbTesting.instance;

    // Set the signed-in user (the token from fetchAbrovaToken is for this user)
    await sdk.setUserId('user-123');
    sdk.setUserAttributes({'plan': 'premium', 'country': 'US'});

    // Get experiment variant (the default until the service has assigned one)
    final variant = await sdk.getVariant(
      'checkout-button-style',
      defaultVariant: 'control',
    );

    // Check feature flag
    final newCheckout = await sdk.isFeatureEnabled('new-checkout-flow');

    setState(() {
      _variant = variant;
      _newCheckoutEnabled = newCheckout;
      _loading = false;
    });

    // Track view
    await sdk.trackView('checkout-button-style');
  }

  Future<void> _handleCheckout() async {
    final sdk = AbrovaAbTesting.instance;

    await sdk.trackClick('checkout-button-style');
    // ... process checkout ...
    await sdk.trackPurchase('checkout-button-style', value: 1000000, transactionId: 'txn_123');

    if (mounted) {
      ScaffoldMessenger.of(context).showSnackBar(
        const SnackBar(content: Text('Checkout complete!')),
      );
    }
  }

  @override
  Widget build(BuildContext context) {
    if (_loading) {
      return const Scaffold(body: Center(child: CircularProgressIndicator()));
    }

    return Scaffold(
      appBar: AppBar(title: const Text('Checkout')),
      body: Center(
        child: Column(
          mainAxisAlignment: MainAxisAlignment.center,
          children: [
            Text('Variant: $_variant'),
            Text('New checkout: $_newCheckoutEnabled'),
            const SizedBox(height: 24),
            ElevatedButton(
              onPressed: _handleCheckout,
              style: ElevatedButton.styleFrom(
                backgroundColor: _variant == 'Variant B' ? Colors.green : Colors.grey,
                padding: const EdgeInsets.symmetric(horizontal: 32, vertical: 16),
              ),
              child: const Text('Complete Purchase', style: TextStyle(fontSize: 18)),
            ),
          ],
        ),
      ),
    );
  }
}

// ── Initialization ──
static Future<AbrovaAbTesting> init(AbrovaAbTestingConfig config, {callback, baseUrl})
static AbrovaAbTesting get instance

// ── Configuration ──
AbrovaAbTestingConfig({required String apiKey, AbrovaTokenProvider? tokenProvider,
  String? userToken, bool debug, int? flushInterval, int maxQueueSize})
typedef AbrovaTokenProvider = FutureOr<String?> Function()   // null: no one signed in

// ── User Management ──
Future<void> setUserId(String userId)   // call on login
Future<void> clearUserId()              // call on logout
String? getUserId()
void setUserAttributes(Map<String, dynamic> attributes)

// ── User Token ──
bool get isAwaitingUserToken
void onAwaitingUserToken(void Function() callback)
Future<void> setUserToken(String? token)   // null = signed out
Future<void> refreshUserToken()            // ask tokenProvider again now
Future<void> setTokenProvider(AbrovaTokenProvider? provider)

// ── Experiments ──
Future<String> getVariant(String experimentKey, {String defaultVariant})
Future<Map<String, dynamic>?> getVariantConfig(String experimentKey)
Future<void> refreshExperiments()
List<Experiment> getExperiments()

// ── Event Tracking (17 types) ──
Future<void> trackView(String experimentKey)
Future<void> trackClick(String experimentKey)
Future<void> trackConversion(String experimentKey, {double? value})
Future<void> trackCustomEvent(String experimentKey, String eventName, {properties})
Future<void> trackScroll(String experimentKey, {double? depth, properties})
Future<void> trackFormSubmit(String experimentKey, {String? formName, properties})
Future<void> trackSearch(String experimentKey, {String? query, properties})
Future<void> trackShare(String experimentKey, {String? method, properties})
Future<void> trackAddToCart(String experimentKey, {double? value, String? productId})
Future<void> trackRemoveFromCart(String experimentKey, {double? value, String? productId})
Future<void> trackBeginCheckout(String experimentKey, {double? value, properties})
Future<void> trackPurchase(String experimentKey, {required double value, String? transactionId})
Future<void> trackVideoStart(String experimentKey, {String? videoId, properties})
Future<void> trackVideoComplete(String experimentKey, {String? videoId, properties})
Future<void> trackSignUp(String experimentKey, {String? method, properties})
Future<void> trackLogin(String experimentKey, {String? method, properties})
Future<void> trackLogout(String experimentKey, {properties})
Future<void> track(String experimentKey, EventType type, {eventName, eventValue, properties})

// ── Feature Flags ──
Future<bool> isFeatureEnabled(String featureKey, {bool defaultValue})
Future<dynamic> getFeatureValue(String featureKey, {dynamic defaultValue})
Future<List<FeatureFlag>> getFeatureFlags()
Future<void> refreshFeatureFlags()
AbrovaFeatureFlags get featureFlags

// ── Lifecycle ──
Future<void> flush()
Future<int> getPendingEventCount()
bool get isOnline
Future<void> reset()
void dispose()

enum EventType {
  view,           // 'view'
  click,          // 'click'
  conversion,     // 'conversion'
  custom,         // 'custom'
  scroll,         // 'scroll'
  formSubmit,     // 'form_submit'
  search,         // 'search'
  share,          // 'share'
  addToCart,       // 'add_to_cart'
  removeFromCart,  // 'remove_from_cart'
  beginCheckout,   // 'begin_checkout'
  purchase,        // 'purchase'
  videoStart,      // 'video_start'
  videoComplete,   // 'video_complete'
  signUp,          // 'sign_up'
  login,           // 'login'
  logout,          // 'logout'
}