Understanding Flavors

A concise guide to Digia UI flavors, initialization strategies, and recommended use cases.

Digia UI Flavors

Flavors in Digia UI SDK control how your app loads and manages configurations throughout different stages of development and deployment. Each flavor is designed for specific use cases and environments.

Overview

Flavors determine:

• Where configuration is loaded from (server, cache, or local assets)

• When configuration updates are fetched

• How the app behaves in different environments

• What strategy is used for initialization and caching

Available Flavors

1. Debug Flavor

Purpose: Development and testing environments where you need real-time configuration updates.

Flavor.debug(
  branchName: 'feature-branch',  // Optional
  environment: Environment.production,
)

Key Features

• Real-time Updates - Loads configuration from the server in real-time

• Immediate Testing - See configuration changes immediately without rebuilding

• Branch Support - Optionally load from specific branches for feature development (Available only on Teams plan and above)

• Development Focused - Perfect for active development workflows

Parameters

• branchName (optional) - Specify a specific branch to load configuration from. Defaults to main

• environment - Target environment

Use Cases

• Active development and debugging

• Testing new features before merging

• Rapid prototyping and iteration

• QA testing with live configuration changes

---

2. Staging Flavor

Purpose: Pre-Release testing environments when your changes are stable and can be handed to QA.

Flavor.staging(
  environment: Environment.production,
)

Key Features

• Remote Updates - Can still receive configuration updates from server

• Testing Focused - Ideal for final testing before production release

• Stable Configuration - More stable than debug, less static than release

Parameters

• environment - Target environment

Use Cases

• Final QA testing before production deployment

• User acceptance testing (UAT)

• Performance testing with production-like setup

• Client demos and previews

---

3. Versioned Flavor

Purpose: Loading specific configuration versions for consistency and rollback scenarios.

Flavor.versioned(
  version: 42,  // Required: specific version number
  environment: Environment.production,
)

Key Features

• Version Control - Load exact configuration versions

• Consistency - Ensure all users see the same configuration

• Rollback Support - Easily revert to previous working versions

• A/B Testing - Different app versions can load different configurations

Parameters

• version (required) - Specific version number to load

• environment (optional) - Target environment (defaults to production)

Use Cases

• A/B testing with different configuration versions

• Rollback scenarios when issues are discovered

• Maintaining consistency across different app releases

• Gradual feature rollouts

Example

// Load specific version
Flavor.versioned(
  version: 42,
  environment: Environment.production,
)

// Load version for testing environment
Flavor.versioned(
  version: 35,
  environment: Environment.development,
)

---

4. Release Flavor

Purpose: Production deployments with local assets for optimal performance and reliability.

Flavor.release(
  initStrategy: NetworkFirstStrategy(timeoutInMs: 3000),
  appConfigPath: 'assets/app_config.json',
  functionsPath: 'assets/functions.json',
)

⚠️ Note: Release flavor only works with the production environment and therefore does not have an option to choose environment. It is automatically configured for Environment.production.

Key Features

• Local Assets - Default Configuration loaded from app bundle to provide complete fallback

• Optimal Performance - No network dependency for initial load

• Maximum Reliability - Works even without internet connection

• Production Only - Exclusively designed for production environments

Parameters

• initStrategy (required) - Strategy for initializing and caching configuration

• appConfigPath (required) - Path to the app configuration asset file. Assets can be downloaded from Digia dashboard Release page.

• functionsPath (required) - Path to the functions configuration asset file

Dont forget to add the following in your Pubspec.yaml after putting above files in the assets folder

 # To add assets to your application, add an assets section, like this:
  assets:
    - assets/

Init Strategies

NetworkFirstStrategy

NetworkFirstStrategy(timeoutInMs: 3000)

• Tries to fetch fresh configuration from network first. Your users will always see what you intended on the next app open

• Falls back to cache if network fails

• Falls back to local assets if cache fails

• Best for apps that need the latest updates but require reliability

CacheFirstStrategy

CacheFirstStrategy()

• Uses cached configuration first for immediate app startup

• Falls back to local assets if cache unavailable

• Updates cache in background during current session

• First App Open: App loads with existing cached configuration while fetching latest updates in background

• Second App Open: Users see the latest changes from previous background update

• Best for apps prioritizing fast startup times

LocalFirstStrategy

LocalFirstStrategy()

• Uses local assets only

• No network requests for configuration

• Maximum reliability and performance

• Best for apps that rarely need configuration updates

Use Cases

• Static app releases

• Apps requiring maximum performance and reliability

Example

// Release flavor with network priority
Flavor.release(
  initStrategy: NetworkFirstStrategy(timeoutInMs: 3000),
  appConfigPath: 'assets/app_config.json',
  functionsPath: 'assets/functions.json',
)

// Release flavor with cache priority
Flavor.release(
  initStrategy: CacheFirstStrategy(),
  appConfigPath: 'assets/app_config.json',
  functionsPath: 'assets/functions.json',
)

// Release flavor with local-only strategy
Flavor.release(
  initStrategy: LocalFirstStrategy(),
  appConfigPath: 'assets/app_config.json',
  functionsPath: 'assets/functions.json',
)

Environment Options

Environments in Digia UI work similar to Postman environments for APIs. They define different sets of environment variables that your APIs and configurations will use based on the selected environment.

class Environment {
  static const local = Environment._('local');
  static const development = Environment._('development');
  static const production = Environment._('production');
  
  // Can also create custom environments
  static custom(String name) => Environment.custom(name);
}

• Local - Uses local environment variables and configurations for local development

• Development - Uses development server environment variables and API endpoints

• Production - Uses production environment variables and live API endpoints

Important: Flavor and Environment are two different concepts:

• Flavor determines HOW configuration is loaded (from server, cache, or assets)

• Environment determines WHICH environment variables and API endpoints are used

Choosing the Right Combination

Local Development

• Purpose: Active development on local machine with local services

• Recommended: Debug Flavor + Local Environment

• Configuration Source: Real-time from server

• API Environment: Local endpoints and variables

Development Server Testing

• Purpose: Testing with development servers and APIs

• Recommended: Debug Flavor + Development Environment

• Configuration Source: Real-time from server

• API Environment: Development server endpoints and variables

Staging/QA Testing

• Purpose: Pre-production testing with production-like setup

• Recommended: Staging Flavor + Development Environment

• Configuration Source: Stable server configuration

• API Environment: Development/staging server endpoints

Production Deployment

• Purpose: Live app with production APIs and services

• Recommended: Release Flavor + Production Environment

• Configuration Source: Local assets with optional network updates

• API Environment: Production endpoints and variables

Best Practices

Local Development

dart

// Local development with local APIs
Flavor.debug(
  branchName: 'feature/my-feature',
  environment: Environment.local,
)

Development Testing

dart

// Development server testing
Flavor.debug(
  branchName: 'feature/my-feature',
  environment: Environment.development,
)

Pre-Production Testing

dart

// QA testing with development APIs
Flavor.staging(
  environment: Environment.development,
)

Production Release

dart

// Production deployment with production APIs
Flavor.release(
  initStrategy: NetworkFirstStrategy(timeoutInMs: 2000),
  appConfigPath: 'assets/app_config.json',
  functionsPath: 'assets/functions.json',
)
// Note: Release flavor automatically uses Environment.production

Conditional Flavors

import 'package:flutter/foundation.dart';
import 'package:digia_ui/digia_ui.dart';

Flavor getFlavor() {
  if (kDebugMode) {
    return Flavor.debug(environment: Environment.development);
  } else if (kReleaseMode) {
    return Flavor.release(
      initStrategy: NetworkFirstStrategy(timeoutInMs: 2000),
      appConfigPath: 'assets/app_config.json',
      functionsPath: 'assets/functions.json',
    );
  } else {
    // Profile mode
    return Flavor.staging(environment: Environment.production);
  }
}

// Use it in your app
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final digiaUI = await DigiaUI.initialize(
    DigiaUIOptions(
      accessKey: 'YOUR_ACCESS_KEY',
      flavor: getFlavor(),
    ),
  );
  
  runApp(MyApp(digiaUI: digiaUI));
}

This flavor system provides flexibility across all stages of app development while ensuring optimal performance and reliability for each environment.

Step-by-Step: Setting Up Flavors

Development Setup

Step 1: Create your main.dart with debug flavor

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

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  runApp(const MyApp());
}

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

  @override
  Widget build(BuildContext context) {
    return DigiaUIAppBuilder(
      options: DigiaUIOptions(
        accessKey: 'YOUR_ACCESS_KEY',
        flavor: Flavor.debug(
          environment: Environment.development,
        ),
      ),
      builder: (context, status) {
        if (status.isLoading) {
          return const MaterialApp(
            home: Scaffold(
              body: Center(child: CircularProgressIndicator()),
            ),
          );
        }

        if (status.hasError) {
          return MaterialApp(
            home: Scaffold(
              body: Center(
                child: Text('Error: ${status.error}'),
              ),
            ),
          );
        }

        return MaterialApp(
          title: 'My App',
          home: DUIFactory().createInitialPage(),
        );
      },
    );
  }
}

Step 2: Test with different branches (Teams plan and above)

// Test feature branch
Flavor.debug(
  branchName: 'feature/new-checkout',
  environment: Environment.development,
)

// Test from main branch
Flavor.debug(
  branchName: 'main',
  environment: Environment.development,
)

Staging Setup

Step 1: Create staging configuration

// lib/config/flavors.dart
import 'package:digia_ui/digia_ui.dart';

class AppFlavors {
  static Flavor staging() {
    return Flavor.staging(
      environment: Environment.production,
    );
  }
}

Step 2: Update main.dart

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final digiaUI = await DigiaUI.initialize(
    DigiaUIOptions(
      accessKey: 'YOUR_ACCESS_KEY',
      flavor: AppFlavors.staging(),
    ),
  );
  
  runApp(MyApp(digiaUI: digiaUI));
}

Production Setup

Step 1: Download assets from Digia Studio

1. Go to app.digia.tech

2. Open your project

3. Navigate to Release section

4. Click Download Assets

5. Save app_config.json and functions.json

Step 2: Add assets to project

your_project/
  ├── assets/
  │   ├── app_config.json
  │   └── functions.json
  ├── lib/
  └── pubspec.yaml

Update pubspec.yaml:

flutter:
  assets:
    - assets/

Step 3: Configure release flavor

// lib/config/flavors.dart
import 'package:digia_ui/digia_ui.dart';

class AppFlavors {
  static Flavor production() {
    return Flavor.release(
      initStrategy: NetworkFirstStrategy(timeoutInMs: 3000),
      appConfigPath: 'assets/app_config.json',
      functionsPath: 'assets/functions.json',
    );
  }

  static Flavor productionFastStartup() {
    return Flavor.release(
      initStrategy: CacheFirstStrategy(),
      appConfigPath: 'assets/app_config.json',
      functionsPath: 'assets/functions.json',
    );
  }

  static Flavor productionOffline() {
    return Flavor.release(
      initStrategy: LocalFirstStrategy(),
      appConfigPath: 'assets/app_config.json',
      functionsPath: 'assets/functions.json',
    );
  }
}

Step 4: Use in production

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final digiaUI = await DigiaUI.initialize(
    DigiaUIOptions(
      accessKey: 'YOUR_ACCESS_KEY',
      flavor: AppFlavors.production(),
    ),
  );
  
  runApp(MyApp(digiaUI: digiaUI));
}

Multi-Environment Setup (Advanced)

Create a flexible configuration that adapts to build mode:

// lib/config/app_config.dart
import 'package:flutter/foundation.dart';
import 'package:digia_ui/digia_ui.dart';

class AppConfig {
  // Access keys for different environments
  static const String devAccessKey = 'dev_access_key_here';
  static const String prodAccessKey = 'prod_access_key_here';

  // Get flavor based on build mode and environment variable
  static Flavor getFlavor() {
    const environment = String.fromEnvironment('ENV', defaultValue: 'dev');

    if (kDebugMode) {
      // Development mode - always use debug flavor
      return Flavor.debug(
        branchName: const String.fromEnvironment('BRANCH', defaultValue: 'main'),
        environment: Environment.development,
      );
    } else if (kProfileMode) {
      // Profile mode - use staging for testing
      return Flavor.staging(
        environment: Environment.production,
      );
    } else {
      // Release mode - use production configuration
      if (environment == 'staging') {
        return Flavor.staging(
          environment: Environment.production,
        );
      }
      
      return Flavor.release(
        initStrategy: NetworkFirstStrategy(timeoutInMs: 3000),
        appConfigPath: 'assets/app_config.json',
        functionsPath: 'assets/functions.json',
      );
    }
  }

  static String getAccessKey() {
    const environment = String.fromEnvironment('ENV', defaultValue: 'dev');
    return environment == 'prod' ? prodAccessKey : devAccessKey;
  }
}

// main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  
  final digiaUI = await DigiaUI.initialize(
    DigiaUIOptions(
      accessKey: AppConfig.getAccessKey(),
      flavor: AppConfig.getFlavor(),
    ),
  );
  
  runApp(MyApp(digiaUI: digiaUI));
}

Run with different configurations:

# Development with main branch
flutter run

# Development with feature branch
flutter run --dart-define=BRANCH=feature/new-ui

# Staging build
flutter build apk --release --dart-define=ENV=staging

# Production build
flutter build apk --release --dart-define=ENV=prod

Quick Reference

When to Use Each Flavor

Scenario	Recommended Flavor	Init Strategy
Local development	Flavor.debug(environment: Environment.local)	N/A (server)
Development server testing	Flavor.debug(environment: Environment.development)	N/A (server)
Feature branch testing	Flavor.debug(branchName: 'feature-x')	N/A (server)
QA/Staging environment	Flavor.staging(environment: Environment.production)	N/A (server)
A/B testing	Flavor.versioned(version: 42)	N/A (server)
Production (latest config)	Flavor.release(...)	NetworkFirstStrategy
Production (fast startup)	Flavor.release(...)	CacheFirstStrategy
Production (offline-first)	Flavor.release(...)	LocalFirstStrategy

Environment Variables in Different Flavors

All flavors (except release) support environment selection:

// Local APIs
Flavor.debug(environment: Environment.local)

// Dev server APIs
Flavor.debug(environment: Environment.development)

// Production APIs
Flavor.debug(environment: Environment.production)
Flavor.staging(environment: Environment.production)

// Custom environment
Flavor.debug(environment: Environment.custom('staging-eu'))

⚠️ Note: Flavor.release() always uses Environment.production and cannot be changed.