Advanced Integration

This guide covers advanced SDK features for customization and extension.

Custom Widgets

Register your own Flutter widgets to use in Digia Studio.

When to Use

• ✅ Native Operations: When you need to perform native Flutter/platform operations (camera, GPS, device sensors)

• ✅ Third-party Libraries: When using Flutter packages not available in Digia UI

• ✅ Complex UI Logic: When you need custom animations, gestures, or state management

• ✅ Missing Components: When Digia UI doesn't have the specific widget you need

• ✅ Performance: When native widgets perform better for specific use cases

When NOT to Use

• ❌ Basic UI: For simple buttons, text, images - use Digia UI directly

• ❌ Standard Components: For common widgets already in Digia UI

• ❌ Simple Layouts: For basic containers, columns, rows - use Digia UI

Implementation

Step 1: Define Props Class

// From ProductHub demo - lib/widgets/delivery_type_status.dart
class DeliveryTypeWidgetProps {
  final String title;
  final Color color;

  DeliveryTypeWidgetProps({
    required this.title,
    required this.color,
  });

  static DeliveryTypeWidgetProps fromJson(Map<String, dynamic> json) {
    return DeliveryTypeWidgetProps(
      title: json['title'] as String,
      color: Color(int.parse(json['color'].replaceFirst('#', '0xff'))),
    );
  }
}

Note: This example shows a basic custom widget. In practice, prefer Digia UI components for simple styling needs. Only use custom widgets when Digia UI cannot provide the required functionality or performance.

Step 2: Create Widget Class

// From ProductHub demo - lib/widgets/delivery_type_status.dart
class DeliveryTypeStatus
    extends VirtualLeafStatelessWidget<DeliveryTypeWidgetProps> {
  DeliveryTypeStatus(
      {required super.props,
      required super.commonProps,
      required super.parent,
      required super.refName});

  @override
  Widget render(RenderPayload payload) {
    return DeliveryTypeStatusCustomWidget(
      title: props.title,
      color: props.color,
    );
  }
}

class DeliveryTypeStatusCustomWidget extends StatefulWidget {
  final String title;
  final Color color;

  const DeliveryTypeStatusCustomWidget({
    super.key,
    required this.title,
    required this.color,
  });

  @override
  State<DeliveryTypeStatusCustomWidget> createState() =>
      _DeliveryTypeStatusCustomWidgetState();
}

class _DeliveryTypeStatusCustomWidgetState
    extends State<DeliveryTypeStatusCustomWidget> {
  @override
  Widget build(BuildContext context) {
    return Text(
      widget.title,
      style: TextStyle(color: widget.color),
    );
  }
}

Step 3: Register Widget

// From ProductHub demo - lib/widgets/delivery_type_status.dart
void registerDeliveryTypeStatusCustomWidgets() {
  DUIFactory().registerWidget<DeliveryTypeWidgetProps>(
    'custom/deliverytype-1BsfGx', // ID in Digia Studio
    DeliveryTypeWidgetProps.fromJson,
    (props, childGroups) => DeliveryTypeStatus(
      props: props,
      commonProps: null,
      parent: null,
      refName: 'custom_deliveryType',
    ),
  );
}

💡 See custom-widgets.md for complete guide.

Environment Variables

Pass runtime configuration to Digia UI pages.

When to Use

• Different API endpoints per environment

• Feature flags

• App version info

• Theme configuration

Usage

DigiaUIApp(
  digiaUI: digiaUI,
  environmentVariables: {
    'apiBaseUrl': 'https://api.example.com',
    'appVersion': '1.2.3',
    'featureFlags': {
      'enableCheckoutV2': true,
      'enableSocialLogin': false,
    },
    'theme': {
      'primaryColor': '#FF5722',
      'accentColor': '#2196F3',
    },
  },
  builder: (context) => MaterialApp(
    home: DUIFactory().createInitialPage(),
  ),
)

or you can also set it by these two functions:

// Set a single environment variable
DUIFactory().setEnvironmentVariable('apiBaseUrl', 'https://api.example.com');

// Set multiple environment variables at once
DUIFactory().setEnvironmentVariables({
  'appVersion': '1.2.3',
  'featureFlags': {
    'enableCheckoutV2': true,
    'enableSocialLogin': false,
  },
  'theme': {
    'primaryColor': '#FF5722',
    'accentColor': '#2196F3',
  },
});

Access in Digia Studio:

${env.apiBaseUrl}
${env.featureFlags.enableCheckoutV2}
${env.theme.primaryColor}

Analytics Integration

Track user interactions from Digia UI pages.

When to Use

• Track page views and events

• Monitor user behavior

• Send analytics to Firebase, Mixpanel, etc.

Implementation

// From ProductHub demo - lib/dummy_adapters/analytics_adapter.dart
class DummyAnalyticsAdapter extends DUIAnalytics {
  /// Log an event to Firebase Analytics
  void logEvent(String name, Map<String, dynamic>? parameters) {
    print('[Analytics] Event: $name, Params: $parameters');
  }

  /// Set user properties
  void setUserProperties(Map<String, dynamic> properties) {
    print('[Analytics] User Properties: $properties');
  }

  /// Set user ID
  void setUserId(String? userId) {
    print('[Analytics] User ID: $userId');
  }

  /// Log screen view
  void logScreenView(String screenName) {
    print('[Analytics] Screen View: $screenName');
  }

  @override
  void onDataSourceError(
      String dataSourceType, String source, DataSourceErrorInfo errorInfo) {
    // TODO: implement onDataSourceError
  }

  @override
  void onDataSourceSuccess(
      String dataSourceType, String source, metaData, perfData) {
    // TODO: implement onDataSourceSuccess
  }

  @override
  void onEvent(List<AnalyticEvent> events) {
    // TODO: implement onEvent
  }
}

Usage in main.dart:

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

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

  runApp(ManualInitExample(
    analytics: analytics,
    messageHandler: messageHandler,
  ));
}

Now events from Digia Studio actions will be tracked automatically.

PostMessage Handling (Digia to Native)

Handle messages sent from Digia UI pages to native Flutter code using the callExternalMethod action.

When to Use

• Trigger native functionality from Digia UI (navigation, external URLs, logging)

• Send data from Digia forms to native processing

• Execute platform-specific operations

Implementation

Step 1: Use DigiaMessageHandlerMixin

If you want to handle messages from Digia UI, use the DigiaMessageHandlerMixin and register handlers with addMessageHandler():

class MyApp extends StatefulWidget {
  @override
  _MyAppState createState() => _MyAppState();
}

class _MyAppState extends State<MyApp> with DigiaMessageHandlerMixin {
  @override
  void initState() {
    super.initState();
    
    // Register message handlers
    addMessageHandler('start_payment', _handlePayment);
    addMessageHandler('share_product', _handleShare);
    addMessageHandler('open_url', _handleOpenUrl);
    addMessageHandler('open_cart', _handleNavigateToCart);
  }

  Future<void> _handlePayment(dynamic message) async {
    print('[Payment] Starting payment: $message');
    // Integrate with payment gateway (Gokwik, Stripe, etc.)
  }

  Future<void> _handleShare(dynamic message) async {
    final data = message is Map ? Map<String, dynamic>.from(message) : {};
    final url = data['url'] ?? '';
    final title = data['title'] ?? '';
    final text = data['text'] ?? '$title\n$url';

    print('[Share] Would share: $text');
    // Use share_plus package
  }

  Future<void> _handleOpenUrl(dynamic message) async {
    final url = message is String ? message : message['url'];
    print('[URL] Opening: $url');
    // Use url_launcher to open URLs
  }


  void _handleNavigateToCart(dynamic message) {
    Navigator.push(
      context,
      MaterialPageRoute(
        builder: (context) => const CartScreenByDigiaUI(),
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      home: Scaffold(
        appBar: AppBar(title: Text('My App')),
        body: Center(child: Text('App Content')),
      ),
    );
  }
}

Step 2: Register Handler in App

// In main.dart or app initialization
void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await AppConfig.loadConfig();

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

  runApp(ManualInitExample(
    analytics: analytics,
    // No need to pass messageHandler - it's handled by the mixin
  ));
}

Step 3: Use in Digia Studio

In Digia Studio, use the callExternalMethod action

Best Practices

Message Naming

• Use snake_case for channel names: start_payment, share_product

• Be descriptive but concise

• Group related messages: payment_*, user_*, navigation_*

Data Handling

• Always check payload type and structure

• Provide fallbacks for missing data

• Use safe type casting

Network Configuration

Customize network behavior.

When to Use

• Custom headers

• SSL certificate pinning

• Proxy configuration

• Timeout customization

Implementation

final networkConfig = NetworkConfiguration(
  connectTimeout: Duration(seconds: 30),
  receiveTimeout: Duration(seconds: 30),
  sendTimeout: Duration(seconds: 30),
);

DigiaUIOptions(
  accessKey: 'YOUR_ACCESS_KEY',
  flavor: Flavor.debug(),
  networkConfiguration: networkConfig,
)

Advanced State Management

Stream-Based Updates

When to use: Real-time UI updates from native code

class CartManager {
  static void addToCart(Product product) {
    // Update native state
    cart.add(product);
    
    // Sync with Digia UI
    DUIAppState().update('cartCount', cart.length);
    DUIAppState().update('cartTotal', cart.totalAmount);
    DUIAppState().update('cartItems', cart.items.map((e) => e.toJson()).toList());
  }
}

// Listen in Flutter
class MyWidget extends StatefulWidget {
  @override
  _MyWidgetState createState() => _MyWidgetState();
}

class _MyWidgetState extends State<MyWidget> {
  late StreamSubscription _subscription;

  @override
  void initState() {
    super.initState();
    
    _subscription = DUIAppState().listen('cartCount', (value) {
      setState(() {
        // Update UI
      });
    });
  }

  @override
  void dispose() {
    _subscription.cancel();
    super.dispose();
  }
  
  @override
  Widget build(BuildContext context) {
    final count = DUIAppState().getValue('cartCount') ?? 0;
    return Badge(label: Text('$count'), child: Icon(Icons.shopping_cart));
  }
}

StreamBuilder Pattern

When to use: Reactive UI components

StreamBuilder<dynamic>(
  stream: DUIAppState().getStream('cartCount'),
  initialData: 0,
  builder: (context, snapshot) {
    final count = snapshot.data as int? ?? 0;
    return Badge(
      label: Text('$count'),
      isLabelVisible: count > 0,
      child: IconButton(
        icon: Icon(Icons.shopping_cart),
        onPressed: () => openCart(),
      ),
    );
  },
)

Multi-Environment Setup

When to use: Different configs for dev, staging, production

// From ProductHub demo - lib/config/app_config.dart
class AppConfig {
  static String environment = 'development';
  static String branch = 'main';
  static InitStrategy initStrategy = InitStrategy.networkFirst;
  
  static String shopifyStoreName = 'your-store';
  static String shopifyAccessToken = 'your-token';
  
  static Future<void> loadConfig() async {
    // Load from environment variables or config files
    // For demo purposes, using hardcoded values
  }
  
  static String getAccessKey() {
    // Return appropriate access key based on environment
    return 'your_digia_access_key';
  }
}

// From ProductHub demo - lib/config/digia_config.dart
class DigiaConfig {
  static Flavor getFlavor() {
    return Flavor.debug(
      branchName: AppConfig.branch,
      environment: AppConfig.environment,
    );
  }

  static Future<DigiaUI> initialize() async {
    final flavor = getFlavor();

    return await DigiaUI.initialize(
      DigiaUIOptions(
        accessKey: AppConfig.getAccessKey(),
        flavor: flavor,
      ),
    );
  }
}

// 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();
  ApiService.initialize(analytics: analytics);

  runApp(ManualInitExample(
    analytics: analytics,
    // Message handlers are registered in the widget using DigiaMessageHandlerMixin
  ));
}

Run different environments:

# Development (default)
flutter run

# Production build
flutter build apk --release

Best Practices

Security

• ✅ Store access keys securely (never in code for production)

• ✅ Use environment variables for sensitive data

• ✅ Validate data from Digia UI pages

Performance

• ✅ Use CacheFirstStrategy for faster app startup

• ✅ Minimize global state size

• ✅ Cancel stream subscriptions in dispose()

State Management

• ✅ Use meaningful state keys (user.profile not data1)

• ✅ Structure complex data with nested objects

• ✅ Provide fallbacks for null values

Testing

• ✅ Test with different flavors (debug, staging, release)

• ✅ Test offline scenarios with LocalFirstStrategy

• ✅ Mock DUIAppState for unit tests

Next Steps

• 📖 Understanding Flavors - Complete flavor reference

• 🎨 Custom Widgets - Detailed widget registration

• 💾 State Management - Full state guide

• Finding Page/Component Slugs - How to locate and copy page slugs for navigation