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, toggle user participation, and display experiment lists with pre-built UI components.

Features

  • Experiment Management: Fetch and manage experiments from your API
  • User Participation: Toggle user participation in specific experiments
  • Ready-to-use Widgets: Pre-built UI components for displaying experiment lists
  • Device Information: Automatic device information tracking for experiments
  • Type-safe Models: Strongly typed experiment models with JSON serialization
  • API Integration: Seamless integration with the IWS API infrastructure

Getting started

Prerequisites

  • Flutter SDK >= 1.17.0
  • Dart SDK ^3.9.2

Installation

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

dependencies:
  iws_experiments: ^0.0.1

Then run:

flutter pub get

Configuration

Set your API key as an environment variable when running your app:

flutter run --dart-define=IWS_API_KEY=your_api_key_here

Or in your IDE's run configuration, add:

--dart-define=IWS_API_KEY=your_api_key_here

Usage

Basic Usage

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_code',
);

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_code',
  active: true,
);

Using Pre-built Widgets

ExperimentList Widget

Display a list of all experiments with built-in UI:

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

class ExperimentsScreen extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Experiments')),
      body: ExperimentList(
        userIdentifier: 'user_code',
        onExperimentUpdated: (experiment, active) {
          print('Experiment ${experiment.name} is now ${active ? "active" : "inactive"}');
        },
      ),
    );
  }
}

ExperimentListTile Widget

Display a single experiment with toggle functionality:

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

class SingleExperimentView extends StatelessWidget {
  final Experiment experiment;

  const SingleExperimentView({required this.experiment});

  @override
  Widget build(BuildContext context) {
    return ExperimentListTile(
      experiment: experiment,
      userIdentifier: 'user_code',
      onToggle: (active) {
        print('Experiment toggled: $active');
      },
    );
  }
}

Additional information

API Requirements

This package requires:

  • iws_http package for HTTP communication
  • iws_device_info package for device information
  • A valid API key from the IWS platform

Error Handling

The package throws exceptions when:

  • API key is missing or invalid
  • Network requests fail
  • Invalid data is received from the API

Always wrap API calls in try-catch blocks:

try {
  final experiments = await IwsExperiments().fetchExperiments();
} catch (e) {
  print('Error fetching experiments: $e');
}

Contributing

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

License

Proprietary software. See LICENSE file for details.

Libraries

iws_experiments