flutter-core:flutter-platform-integration

What this skill does

# Flutter Platform Integration Skill

This skill provides comprehensive guidance on Flutter platform integration, covering platform channels, native code integration, plugin development, and platform views. Use this skill when working with platform-specific features, creating plugins, or integrating native Android/iOS code with Flutter applications.

## When to Use This Skill

Use this skill when:

1. **Platform Channel Communication**: Implementing MethodChannel, EventChannel, or BasicMessageChannel for Flutter-native communication
2. **Native Code Integration**: Calling Android (Kotlin/Java) or iOS (Swift/Objective-C) code from Dart
3. **Plugin Development**: Creating reusable Flutter plugins for pub.dev or internal use
4. **Platform Views**: Embedding native Android views or iOS UIKit views in Flutter apps
5. **Platform-Specific Features**: Accessing device capabilities not available through Dart alone
6. **FFI Integration**: Binding to native C/C++ libraries using dart:ffi
7. **Custom Native UI**: Integrating native UI components that aren't available in Flutter
8. **Hardware Access**: Working with cameras, sensors, battery status, or other device features

## Skill Overview

Flutter's platform integration system enables you to build cross-platform apps while accessing platform-specific functionality when needed. This skill covers the complete spectrum from simple method calls to complex native integrations.

### Core Concepts

**Platform Channels**: Asynchronous message-passing channels between Flutter (Dart) and native code:
- **MethodChannel**: One-way method invocations with return values (most common)
- **EventChannel**: Streaming data from native to Flutter (sensors, location updates)
- **BasicMessageChannel**: Bidirectional message passing

**Native Integration**: Three primary approaches:
- **Platform Channels**: String-based method calls with StandardMessageCodec
- **Pigeon**: Type-safe code generation for platform communication
- **FFI (Foreign Function Interface)**: Direct C/C++ library bindings

**Plugin Architecture**: Reusable packages combining Dart APIs with platform-specific implementations:
- **Dart Packages**: Pure Dart code (no native code)
- **Plugin Packages**: Dart + native code (Android, iOS, web, desktop)
- **Federated Plugins**: Modular architecture with platform-specific packages

### Architecture Pattern

The typical platform integration flow:

```
┌─────────────────────────────────────────────────────┐
│                    Flutter (Dart)                   │
│  ┌──────────────────────────────────────────────┐  │
│  │          Your Flutter Widget/App             │  │
│  └────────────────┬─────────────────────────────┘  │
│                   │                                 │
│  ┌────────────────▼─────────────────────────────┐  │
│  │    MethodChannel / EventChannel / FFI        │  │
│  └────────────────┬─────────────────────────────┘  │
└───────────────────┼─────────────────────────────────┘
                    │ Asynchronous Messages
┌───────────────────▼─────────────────────────────────┐
│             Platform-Specific Code                  │
│  ┌──────────────────┐      ┌──────────────────┐    │
│  │  Android         │      │  iOS             │    │
│  │  (Kotlin/Java)   │      │  (Swift/Obj-C)   │    │
│  └──────────────────┘      └──────────────────┘    │
│                                                     │
│  Platform APIs: Camera, Location, Battery, etc.    │
└─────────────────────────────────────────────────────┘
```

### Key Principles

**1. Asynchronous by Design**: All platform channel communications are asynchronous to maintain UI responsiveness. Never block the UI thread waiting for native responses.

**2. Type-Safe Communication**: Use StandardMessageCodec for automatic type conversion between Dart and native types, or leverage Pigeon for compile-time type safety.

**3. Main Thread Constraint**: Channel method handlers must execute on the platform's main thread (UI thread). Use dispatchers/handlers to switch threads when needed.

**4. Error Handling**: Always implement robust error handling on both sides:
- Dart: Catch `PlatformException` with try-catch blocks
- Native: Return error codes, messages, and details for debugging

**5. Cross-Platform Consistency**: Design APIs that work consistently across platforms while respecting platform-specific conventions and limitations.

## Reference Documentation

This skill includes comprehensive reference documentation:

- **[Platform Channels](references/platform-channels.md)**: MethodChannel, EventChannel, message codecs, threading, and Pigeon integration
- **[Android Integration](references/android-integration.md)**: Kotlin/Java integration, JNI, Gradle configuration, and Android-specific patterns
- **[iOS Integration](references/ios-integration.md)**: Swift/Objective-C integration, CocoaPods, Xcode configuration, and iOS-specific patterns
- **[Plugin Development](references/plugin-development.md)**: Creating plugins, federated architecture, publishing to pub.dev, and best practices
- **[Platform Views](references/platform-views.md)**: Embedding native Android views and iOS UIKit views in Flutter apps

## Practical Examples

This skill includes complete working examples:

- **[Custom Plugin Example](examples/custom-plugin.md)**: Battery level plugin demonstrating MethodChannel implementation for Android and iOS
- **[Native Features](examples/native-features.md)**: Camera integration showing EventChannel, permissions, and platform-specific UI

## Development Workflow

### 1. Design Phase
- Identify platform-specific requirements
- Choose integration approach (channels vs FFI vs existing plugins)
- Design cross-platform API surface
- Document platform limitations and differences

### 2. Implementation Phase
- Create plugin or add platform channels to existing app
- Implement Dart API layer
- Write platform-specific code (Android, iOS, etc.)
- Connect Dart and native via channels or FFI
- Handle errors and edge cases on both sides

### 3. Testing Phase
- Unit test Dart API layer
- Test native implementations separately
- Integration test cross-platform behavior
- Test error handling and edge cases
- Verify threading and performance

### 4. Documentation Phase
- Document public APIs with dartdoc comments
- Provide usage examples and code samples
- Document platform-specific requirements
- Create README with setup instructions
- Maintain CHANGELOG for versions

### 5. Publication Phase (for plugins)
- Validate with `flutter pub publish --dry-run`
- Ensure all metadata is complete (pubspec.yaml)
- Add Flutter Favorite criteria where applicable
- Publish to pub.dev
- Monitor issues and feedback

## Best Practices

### API Design
- **Simplicity First**: Expose simple, intuitive Dart APIs regardless of native complexity
- **Consistency**: Maintain consistent naming and patterns across platforms
- **Async/Await**: Use Future-based APIs for asynchronous operations
- **Null Safety**: Fully support Dart null safety with proper annotations
- **Documentation**: Provide comprehensive dartdoc comments with examples

### Platform Channels
- **Unique Names**: Use reverse domain notation for channel names (e.g., `com.example.app/battery`)
- **Type Safety**: Consider Pigeon for type-safe code generation
- **Error Handling**: Always catch `PlatformException` and provide helpful error messages
- **Threading**: Ensure handlers run on main thread; offload heavy work to background
- **Data Types**: Use StandardMessageCodec-supported types or custom codecs

### Native Code
- **Separation of Concerns**: Keep channel logic separate from business logic
- **Platform Conventions**: Follow platform-specific naming and architectural patterns
- **Resource Management**: Properly manage native resources (memory, file handles, etc.)
- **Permissions**: Handle runtime permissions gracefully with clear user messaging
- **Backward Compatibility**: Support reasonable range of OS versions

### Plugi