Getting Started

This guide covers everything you need to integrate Digia UI SDK into your Flutter app.

Installation

Step 1: Add the SDK

Recommended: Use Flutter CLI

flutter pub add digia_ui

Alternative: Manual Installation

Add to pubspec.yaml:

dependencies:
  digia_ui: ^1.0.0

Then run:

flutter pub get

Step 2: Get Your Access Key

Log in to Digia Studio
Open your project
Go to Settings → App Settings
Copy your Access Key

Screenshot showing the App Settings page in Digia Studio with the Access Key field highlighted.

⚠️ Security: Never commit your access key to public repositories.

Basic Setup

Choose Your Initialization Pattern

The SDK offers two initialization approaches. Pick based on your needs:

Pattern

When to Use

Best For

DigiaUIAppBuilder

You want automatic loading/error state handling

✅ New apps, need splash screens

DigiaUIApp

You need the SDK ready before first render

Complex init flows, dependency injection

Option A: DigiaUIAppBuilder (Recommended)

Use this if:

Building a new app
Want to show loading indicators during initialization
Need error handling built-in

Example from ProductHub Demo:

// From ProductHub demo - lib/main.dart
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AppConfig.loadConfig();

  print('[ProductHub] Starting Digia UI Demo');
  print('[ProductHub] Environment: ${AppConfig.environment}');

  final analytics = DummyAnalyticsAdapter();
  final messageHandler = CustomMessageHandler(analytics: analytics);
  ApiService.initialize(analytics: analytics);

  // Choose integration method:
  // Method 1: Automatic initialization with DigiaUIAppBuilder
  // Method 2: Manual initialization with DigiaUIScope (used below)
  runApp(ManualInitExample(
    analytics: analytics,
    messageHandler: messageHandler,
  ));
}

DigiaUIAppBuilder Example:

// From ProductHub demo - lib/main.dart
class AutomaticInitExample extends StatelessWidget {
  final DummyAnalyticsAdapter analytics;
  final CustomMessageHandler messageHandler;

  const AutomaticInitExample({
    super.key,
    required this.analytics,
    required this.messageHandler,
  });

  @override
  Widget build(BuildContext context) {
    return DigiaUIAppBuilder(
      options: DigiaUIOptions(
        accessKey: AppConfig.getAccessKey(),
        flavor: DigiaConfig.getFlavor(),
      ),
      analytics: analytics,
      builder: (context, status) {
        if (status.isLoading) {
          return const MaterialApp(
            home: Scaffold(
              backgroundColor: Color(0xFF673AB7),
              body: Center(
                child: Column(
                  mainAxisAlignment: MainAxisAlignment.center,
                  children: [
                    CircularProgressIndicator(color: Colors.white),
                    SizedBox(height: 24),
                    Text(
                      'Loading...',
                      style: TextStyle(color: Colors.white, fontSize: 16),
                    ),
                  ],
                ),
              ),
            ),
          );
        }

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

        DUIFactory().setEnvironmentVariables({
          'accessToken': AppConfig.shopifyAccessToken,
          'storeName': AppConfig.shopifyStoreName,
        });
        registerDeliveryTypeStatusCustomWidgets();

        return MaterialApp(
          title: 'ProductHub - Digia UI Demo',
          theme: ThemeData(primarySwatch: Colors.deepPurple),
          home: MessageHandlerWrapper(
            messageHandler: messageHandler,
            child: const HomePage(),
          ),
        );
      },
    );
  }
}

Option B: DigiaUIApp (Pre-initialized)

Use this if:

You have complex initialization logic
Need SDK ready before any widgets render
Using dependency injection frameworks

Example from ProductHub Demo:

// From ProductHub demo - lib/main.dart
class ManualInitExample extends StatefulWidget {
  final DummyAnalyticsAdapter analytics;
  final CustomMessageHandler messageHandler;

  const ManualInitExample({
    super.key,
    required this.analytics,
    required this.messageHandler,
  });

  @override
  State<ManualInitExample> createState() => _ManualInitExampleState();
}

class _ManualInitExampleState extends State<ManualInitExample> {
  DigiaUI? _digiaUI;
  bool _isLoading = true;
  String? _error;

  @override
  void initState() {
    super.initState();
    _initializeDigiaUI();
  }

  Future<void> _initializeDigiaUI() async {
    try {
      final digiaUI = await DigiaConfig.initialize();
      setState(() {
        _digiaUI = digiaUI;
        _isLoading = false;
      });
    } catch (e) {
      setState(() {
        _error = e.toString();
        _isLoading = false;
      });
    }
  }

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

    if (_error != null) {
      return MaterialApp(
        home: Scaffold(
          body: Center(child: Text('Error: $_error')),
        ),
      );
    }

    return DigiaUIScope(
      digiaUI: _digiaUI!,
      analytics: widget.analytics,
      builder: (context) {
        DUIFactory().setEnvironmentVariables({
          'accessToken': AppConfig.shopifyAccessToken,
          'storeName': AppConfig.shopifyStoreName,
        });
        registerDeliveryTypeStatusCustomWidgets();

        return MaterialApp(
          title: 'ProductHub - Digia UI Demo',
          theme: ThemeData(primarySwatch: Colors.deepPurple),
          home: MessageHandlerWrapper(
            messageHandler: widget.messageHandler,
            child: const HomePage(),
          ),
        );
      },
    );
  }
}

Understanding Flavors

Flavors control how your app loads UI configuration. Choose based on your environment:

Development

// From ProductHub demo - lib/config/digia_config.dart
flavor: Flavor.debug(
  branchName: AppConfig.branch,
  environment: AppConfig.environment,
)

Use for:

Active development
Real-time config updates from Digia Studio
Testing changes immediately without rebuilding

Staging/QA

// Alternative staging configuration
flavor: Flavor.staging(
  environment: AppConfig.environment,
)

Use for:

Pre-release testing
QA environments
Stable config that can still be updated remotely

Production

// For production with local assets
flavor: Flavor.release(
  initStrategy: NetworkFirstStrategy(timeoutInMs: 3000),
  appConfigPath: 'assets/app_config.json',
  functionsPath: 'assets/functions.json',
)

Use for:

Production releases
Maximum performance and reliability
Offline-first capability

💡 See understanding-flavors.md for detailed flavor documentation and init strategies.

Working with Pages and Components

Name Conversion

Digia Studio names are converted to snake_case in code:

Studio Name

Code Reference (slugs)

Product Details

product_details_xCV12O

Shopping Cart

shopping_cart_sV467N

Creating Pages

// Get initial page
Widget home = DUIFactory().createInitialPage();

// Create specific page with arguments
Widget page = DUIFactory().createPage('product_details_acd78n', {
  'productId': '123',
  'source': 'search',
});

// Navigate to a page
Navigator.push(
  context,
  DUIFactory().createPageRoute('checkout_qv4FNB', {'cartId': cartId}),
);

Creating Components

// Embed a component in native Flutter
Widget card = DUIFactory().createComponent('product_card_wsU879', {
  'id': product.id,
  'title': product.title,
  'price': product.price,
  'onTap': () => openProduct(product.id),
});

Integration Patterns

Pattern 1: Full App Mode

When to use: Building entire app in Digia Studio

MaterialApp(
  home: DUIFactory().createInitialPage(),
  onGenerateRoute: (settings) {
    return DUIFactory().createPageRoute(
      settings.name!,
      settings.arguments as Map<String, dynamic>?,
    );
  },
)

Best for: Apps where 90%+ of UI is built in Digia Studio

Pattern 2: Hybrid Mode

When to use: Mix native Flutter and Digia UI screens

// Native Flutter screen with Digia UI components
class ProductList extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: Text('Products')),
      body: ListView(
        children: [
          // Use Digia UI for complex product cards
          DUIFactory().createComponent('product_card_wsU879', {
            'product': product,
          }),
        ],
      ),
    );
  }
}

Best for: Apps needing some native screens with Digia UI components

Pattern 3: Component Embedding

When to use: Use Digia UI components in native screens

Example from ProductHub Demo:

// From ProductHub demo - lib/screens/cart_screen.dart
class CartScreen extends StatelessWidget {
  final List<dynamic> cartItems;
  final String? totalAmount;
  final String? checkoutUrl;
  final VoidCallback onCheckout;

  const CartScreen({
    super.key,
    required this.cartItems,
    this.totalAmount,
    this.checkoutUrl,
    required this.onCheckout,
  });

  @override
  Widget build(BuildContext context) {
    return Column(
      children: [
        // Native header - use Flutter for simple UI
        Container(
          padding: const EdgeInsets.all(16),
          color: Colors.white,
          child: Row(
            children: [
              IconButton(
                icon: const Icon(Icons.arrow_back),
                onPressed: () => Navigator.pop(context),
              ),
              const Text(
                'Shopping Cart',
                style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
              ),
            ],
          ),
        ),

        // Digia UI cart items - use Digia for complex lists
        Expanded(
          child: DUIFactory().createComponent('cart_items_list_xDSV94', {
            'items': cartItems,
          }),
        ),

        // Native checkout section - use Flutter for custom layouts
        Container(
          padding: const EdgeInsets.all(16),
          child: Column(
            children: [
              Row(
                mainAxisAlignment: MainAxisAlignment.spaceBetween,
                children: [
                  const Text('Total:', style: TextStyle(fontSize: 18)),
                  Text('\$${totalAmount ?? '0.00'}'),
                ],
              ),
              // Digia UI checkout button - use Digia for consistent design
              DUIFactory().createComponent('checkout_button_578cVG', {
                'text': 'Proceed to Checkout',
              }),
            ],
          ),
        ),
      ],
    );
  }
}

Best for: Apps with complex native logic but wanting Digia UI consistency

Pattern 4: Custom Widgets (Advanced)

When to use: Need completely custom Flutter widgets in Digia Studio

// Only use custom widgets when:
// 1. Digia UI doesn't have the component you need
// 2. You need native platform features (camera, GPS, etc.)
// 3. Third-party Flutter packages are required
// 4. Performance-critical custom animations/logic

class CameraWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: () => openCamera(), // Native camera API
      child: Text('Take Photo'),
    );
  }
}

// Register only when necessary
DUIFactory().registerWidget<CameraProps>(
  'native/camera',
  CameraProps.fromJson,
  (props, _) => CameraWidget(),
);

Best for: Specialized components requiring native capabilities

State Management

Global State

Share data between native Flutter and Digia UI:

// Set state from Flutter
DUIAppState().update('cartCount', 5);
DUIAppState().update('user', {'name': 'John', 'email': '[email protected]'});

// Read state in Flutter
final count = DUIAppState().getValue('cartCount') ?? 0;

// Listen to changes
DUIAppState().listen('cartCount', (value) {
  print('Cart count changed: $value');
});

In Digia Studio, access state with expressions:

${cartCount}
${user.name}

Production Deployment

Step 1: Download Assets

Go to app.digia.tech
Navigate to Release section
Download app_config.json and functions.json

Step 2: Add to Project

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

Update pubspec.yaml:

flutter:
  assets:
    - assets/

Step 3: Use Release Flavor

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

Init Strategy Options

Strategy

When to Use

Behavior

NetworkFirstStrategy

Want latest updates

Tries network first, falls back to cache/assets

CacheFirstStrategy

Fast startup priority

Uses cache, updates in background

LocalFirstStrategy

Offline-first apps

Uses only local assets, no network

Step 4: Build

# Android
flutter build apk --release

# iOS
flutter build ios --release

Troubleshooting

SDK Initialization Fails

Error: DigiaUIManager is not initialized

Fix: Ensure you await initialization:

// ✅ Correct
final digiaUI = await DigiaUI.initialize(options);

// ❌ Wrong
DUIFactory().createPage(...);  // Called before init

Page Not Found

Error: Page/component name not found

Fix: Check name conversion:

Studio: "Product Details" → Code: product_details

State Not Updating

Fix: Use AppState or StreamController in Digia Studio or execute actions like setState or rebuildState in Digia Studio

Assets Not Loading (Release)

Fix: Verify pubspec.yaml includes assets:

flutter:
  assets:
    - assets/

Next Steps

📖 Understanding Flavors - Deep dive into flavors and environments
🚀 Advanced Integration - Custom widgets, analytics, environment variables
💾 State Management - Complete state management guide

Support

📧 Email: [email protected]
💬 Discord: https://discord.gg/cZt4ptVKDT
📚 Docs: https://docs.digia.tech
🔗 Example: Digia Flutter Starter
🔗 Integrated Example: Product Hub

PreviousFlutter Integration NextAdvanced Integration

Last updated 28 days ago

hashtagInstallation

hashtagStep 1: Add the SDK

hashtagStep 2: Get Your Access Key

hashtagBasic Setup

hashtagChoose Your Initialization Pattern

hashtagOption A: DigiaUIAppBuilder (Recommended)

hashtagOption B: DigiaUIApp (Pre-initialized)

hashtagUnderstanding Flavors

hashtagDevelopment

hashtagStaging/QA

hashtagProduction

hashtagWorking with Pages and Components

hashtagName Conversion

hashtagCreating Pages

hashtagCreating Components

hashtagIntegration Patterns

hashtagPattern 1: Full App Mode

hashtagPattern 2: Hybrid Mode

hashtagPattern 3: Component Embedding

hashtagPattern 4: Custom Widgets (Advanced)

hashtagState Management

hashtagGlobal State

hashtagProduction Deployment

hashtagStep 1: Download Assets

hashtagStep 2: Add to Project

hashtagStep 3: Use Release Flavor

hashtagInit Strategy Options

hashtagStep 4: Build

hashtagTroubleshooting

hashtagSDK Initialization Fails

hashtagPage Not Found

hashtagState Not Updating

hashtagAssets Not Loading (Release)

hashtagNext Steps

hashtagSupport

Installation

Step 1: Add the SDK

Step 2: Get Your Access Key

Basic Setup

Choose Your Initialization Pattern

Option A: DigiaUIAppBuilder (Recommended)

Option B: DigiaUIApp (Pre-initialized)

Understanding Flavors

Development

Staging/QA

Production

Working with Pages and Components

Name Conversion

Creating Pages

Creating Components

Integration Patterns

Pattern 1: Full App Mode

Pattern 2: Hybrid Mode

Pattern 3: Component Embedding

Pattern 4: Custom Widgets (Advanced)

State Management

Global State

Production Deployment

Step 1: Download Assets

Step 2: Add to Project

Step 3: Use Release Flavor

Init Strategy Options

Step 4: Build

Troubleshooting

SDK Initialization Fails

Page Not Found

State Not Updating

Assets Not Loading (Release)

Next Steps

Support