iws_experiments 1.0.0

A Flutter package for managing A/B testing and feature experiments with pre-built UI components and API integration.

IWS Experiments

A Flutter package for managing A/B testing and feature experiments in your applications. This package provides an easy-to-use interface to fetch experiments, evaluate feature flags, toggle user participation, and display experiment lists with pre-built UI components.

Features

• Experiment Management: Fetch and manage experiments from your API.
• Feature Flag Evaluation: Easily check if an experiment or feature is enabled (isFeatureEnabled).
• User Participation: Toggle user participation in specific experiments with optimistic UI updates.
• Ready-to-use Widgets: Pre-built UI components (ExperimentList, ExperimentListTile) with pull-to-refresh, retry button, and Dark Mode theming.
• Customizable UI: Custom builders for loading, empty, and error states.
• Runtime Configuration & DI: Initialize API credentials dynamically at runtime or via environment variables, with dependency injection support for unit testing.
• Typed Exceptions: Catch specific domain errors (IwsApiKeyMissingException, IwsApiException, IwsNetworkException).
• Device Information: Automatic device information tracking for experiments.
• Type-safe Models: Robust experiment models with JSON serialization, copyWith, equality, and safe parsing.

Getting started

Prerequisites

• Flutter SDK >= 3.38.1
• Dart SDK ^3.10.0

Installation

Add this to your package's pubspec.yaml file:

dependencies:
  iws_experiments: ^1.0.0

Then run:

flutter pub get

Configuration

You can configure your API credentials in two ways:

Option A: Runtime Initialization (Recommended)

Initialize the SDK in your main() function:

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

void main() {
  WidgetsFlutterBinding.ensureInitialized();

  // Initialize with your API key
  IwsExperiments.initialize(
    apiKey: 'your_api_key_here',
    // Optional custom authority or base path:
    // authority: 'ws.interaad.com.ar',
    // basePath: 'api/sdk/',
  );

  runApp(const MyApp());
}

Option B: Compile-time Environment Variable

Pass your API key as a compile-time argument when running or building your app:

flutter run --dart-define=IWS_API_KEY=your_api_key_here

Usage

Feature Flags & Experiments

Checking if a Feature is Enabled

import 'package:iws_experiments/iws_experiments.dart';

// Evaluate if a feature is enabled for a specific user
final isDarkModeEnabled = await IwsExperiments().isFeatureEnabled(
  'dark_mode_feature',
  userIdentifier: 'user_123',
  defaultValue: false,
);

if (isDarkModeEnabled) {
  // Show new feature
}

Fetching Experiments

import 'package:iws_experiments/iws_experiments.dart';

// Fetch all experiments
final experiments = await IwsExperiments().fetchExperiments();

// Fetch experiments for a specific user
final userExperiments = await IwsExperiments().fetchExperiments(
  userIdentifier: 'user_123',
);

// Get a single experiment by code
final experiment = await IwsExperiments().getExperiment(
  'checkout_redesign',
  userIdentifier: 'user_123',
);

Toggling Experiment Participation

import 'package:iws_experiments/iws_experiments.dart';
import 'package:iws_device_info/iws_device_info.dart';

// Toggle user participation in an experiment
await IwsExperiments().toggleExperimentUsage(
  experimentCode: 'new_ui_experiment',
  userIdentifier: 'user_123',
  active: true,
  appVersionCode: 100,
);

Using Pre-built Widgets

ExperimentList Widget

Display a list of all experiments with built-in pull-to-refresh, retry on failure, and smooth optimistic toggling:

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

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

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Experimentos')),
      body: ExperimentList(
        userIdentifier: 'user_123',
        onExperimentUpdated: (experiment, active) {
          debugPrint('Experimento ${experiment.name} actualizado: $active');
        },
      ),
    );
  }
}

ExperimentListTile Widget

Display an individual experiment card tile with switch and error feedback:

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

class SingleExperimentView extends StatelessWidget {
  final Experiment experiment;

  const SingleExperimentView({super.key, required this.experiment});

  @override
  Widget build(BuildContext context) {
    return ExperimentListTile(
      experiment: experiment,
      userIdentifier: 'user_123',
      onToggle: (active) {
        debugPrint('Estado: $active');
      },
    );
  }
}

Error Handling

The package provides typed domain exceptions for precise error handling:

try {
  final experiments = await IwsExperiments().fetchExperiments();
} on IwsApiKeyMissingException catch (e) {
  debugPrint('Falta configurar la API Key: ${e.message}');
} on IwsApiException catch (e) {
  debugPrint('Error del servidor (${e.statusCode}): ${e.message}');
} on IwsNetworkException catch (e) {
  debugPrint('Fallo de conexión: ${e.message}');
} catch (e) {
  debugPrint('Error inesperado: $e');
}

Contributing

This is proprietary software. For questions or support, please contact the package maintainers.

License

Proprietary software. See LICENSE file for details.