​

Flutter Troubleshooting Guide

This guide addresses common issues you might encounter when integrating Capsule with your Flutter application. It provides solutions and best practices to ensure a smooth integration.

​

General Troubleshooting Steps

Before diving into specific issues, try these general troubleshooting steps:

1. Clean the project and get dependencies:

   flutter clean
   flutter pub get
   

2. Update Flutter and dependencies:

   flutter upgrade
   flutter pub upgrade
   

3. Ensure Capsule package is up to date: Check your pubspec.yaml file and update the Capsule package version if necessary.

4. Rebuild the project:

   flutter run
   

​

Common Issues and Solutions

​

1. Package Not Found or Version Conflicts

Problem: Dart can’t find the Capsule package or there are version conflicts with other dependencies.

Solution: Ensure your pubspec.yaml file is correctly configured:

dependencies:
  flutter:
    sdk: flutter
  capsule: ^latest_version

dependency_overrides:
  # Add any necessary overrides here

After updating pubspec.yaml, run:

flutter pub get

​

2. Platform-Specific Setup Issues

Problem: Capsule features not working on specific platforms (iOS/Android).

Solution: Ensure platform-specific configurations are correct:

For iOS (ios/Runner/Info.plist):

<key>CFBundleURLTypes</key>
<array>
  <dict>
    <key>CFBundleURLSchemes</key>
    <array>
      <string>capsule</string>
    </array>
  </dict>
</array>

For Android (android/app/build.gradle):

android {
    defaultConfig {
        ...
        minSdkVersion 21
    }
}

​

3. Initialization Errors

Problem: Capsule fails to initialize or throws errors on startup.

Solution: Ensure proper initialization in your main.dart:

import 'package:capsule/capsule.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();

  final capsule = Capsule(
    environment: Environment.beta,
    apiKey: 'YOUR_API_KEY',
  );
  await capsule.init();

  runApp(MyApp(capsule: capsule));
}

​

4. Asynchronous Operation Errors

Problem: Errors when performing asynchronous operations with Capsule.

Solution: Ensure proper async/await usage and error handling:

try {
  final wallet = await capsule.createWallet(skipDistribute: false);
  // Handle successful wallet creation
} catch (e) {
  print('Error creating wallet: $e');
  // Handle error appropriately
}

​

5. UI Thread Blocking

Problem: Capsule operations blocking the UI thread.

Solution: Use compute function for heavy computations:

import 'package:flutter/foundation.dart';

Future<Wallet> createWalletAsync(Capsule capsule) async {
  return compute(_createWallet, capsule);
}

Wallet _createWallet(Capsule capsule) {
  return capsule.createWallet(skipDistribute: false);
}

// Usage
final wallet = await createWalletAsync(capsule);

​

6. Platform Channel Errors

Problem: Errors related to platform channel communication.

Solution: Ensure the latest version of Capsule Flutter plugin is used and platform-specific code is correctly implemented. If issues persist, check the plugin’s GitHub repository for any known issues or updates.

​

Best Practices

1. State Management: Use a state management solution like Provider or Riverpod to manage Capsule’s state across your app.

2. Error Handling: Implement robust error handling and user feedback mechanisms for Capsule operations.

3. Secure Storage: Use Flutter’s secure storage solutions for storing sensitive data related to Capsule.

4. Offline Support: Implement proper offline handling and synchronization strategies for Capsule operations.

5. Testing: Write unit and integration tests for your Capsule integration to catch issues early.

6. Performance Monitoring: Use Flutter’s DevTools to monitor the performance impact of Capsule integration.

7. Keep Updated: Regularly check for updates to the Capsule Flutter plugin and update your integration accordingly.

​

Debugging Tips

1. Enable Verbose Logging: Enable verbose logging for Capsule operations to get more detailed information:

   Capsule(
     environment: Environment.beta,
     apiKey: 'YOUR_API_KEY',
     logLevel: CapsuleLogLevel.verbose,
   );
   

2. Use Flutter DevTools: Utilize Flutter DevTools for performance profiling and debugging.

3. Platform-Specific Debugging: For platform-specific issues, use Xcode for iOS and Android Studio for Android debugging.

By following these troubleshooting steps and best practices, you should be able to resolve most common issues when integrating Capsule with your Flutter application.

​

Integration Support

If you’re experiencing issues that aren’t resolved by our troubleshooting resources, please contact our team for assistance. To help us resolve your issue quickly, please include the following information in your request:

1. 1

   A detailed description of the problem you’re encountering.

2. 2

   Any relevant error messages or logs.

3. 3

   Steps to reproduce the issue.

4. 4

   Details about your system or environment (e.g., device, operating system, software version).

Providing this information will enable our team to address your concerns more efficiently.