Flutter Platform Integration

Flutter Platform Integration Skill

Purpose

Design and implement reliable, type-safe bridges between Flutter and native platforms — Android (Kotlin/Java) and iOS (Swift/ObjC) — using the appropriate channel or FFI mechanism for each use case.

Scope and authority

Lead authority for:

• MethodChannel and EventChannel design
• Dart FFI for native C/C++ libraries
• AndroidView / UiKitView (platform views)
• federated plugin architecture
• background execution (Android WorkManager, iOS BGTaskScheduler)
• native permission handling
• native SDK integration (Maps, Camera, Bluetooth, etc.)
• plugin packaging and publishing

Supporting interactions:

• flutter-monorepo for federated plugin package structure
• flutter-security for permissions and secure native storage
• flutter-build-release for native build configuration

When to use

• Accessing platform APIs not exposed by existing packages
• Integrating a native SDK (e.g., a vendor analytics SDK, hardware SDK)
• Implementing high-performance native code via FFI
• Embedding native views (Maps, WebView, camera preview)
• Building a plugin (internal or public)
• Background task scheduling (download, sync, notification delivery)
• Requesting and handling native permissions

Channel mechanism selection

MethodChannel — standard pattern

Dart side

// core/platform/camera_channel.dart
class CameraChannel {
  static const _channel = MethodChannel('com.example.app/camera');

  Future<String?> capturePhoto() async {
    try {
      final path = await _channel.invokeMethod<String>('capturePhoto');
      return path;
    } on PlatformException catch (e) {
      // Map platform errors to domain exceptions
      throw CameraException(
        code: e.code,
        message: e.message ?? 'Unknown camera error',
      );
    }
  }

  Future<void> requestCameraPermission() async {
    final granted = await _channel.invokeMethod<bool>('requestPermission');
    if (granted != true) throw const CameraPermissionDeniedException();
  }
}

Android side (Kotlin)

// android/app/src/main/kotlin/.../CameraPlugin.kt
class CameraPlugin : FlutterPlugin, MethodCallHandler {
    private lateinit var channel: MethodChannel
    private lateinit var activity: Activity

    override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
        channel = MethodChannel(
            binding.binaryMessenger,
            "com.example.app/camera"
        )
        channel.setMethodCallHandler(this)
    }

    override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {
        when (call.method) {
            "capturePhoto" -> capturePhoto(result)
            "requestPermission" -> requestPermission(result)
            else -> result.notImplemented()
        }
    }

    private fun capturePhoto(result: MethodChannel.Result) {
        try {
            // Native implementation
            val path = takePhoto()
            result.success(path)
        } catch (e: Exception) {
            result.error("CAMERA_ERROR", e.message, null)
        }
    }

    override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
        channel.setMethodCallHandler(null)
    }
}

iOS side (Swift)

// ios/Classes/CameraPlugin.swift
public class CameraPlugin: NSObject, FlutterPlugin {
    public static func register(with registrar: FlutterPluginRegistrar) {
        let channel = FlutterMethodChannel(
            name: "com.example.app/camera",
            binaryMessenger: registrar.messenger()
        )
        let instance = CameraPlugin()
        registrar.addMethodCallDelegate(instance, channel: channel)
    }

    public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
        switch call.method {
        case "capturePhoto":
            capturePhoto(result: result)
        case "requestPermission":
            requestPermission(result: result)
        default:
            result(FlutterMethodNotImplemented)
        }
    }

    private func capturePhoto(result: @escaping FlutterResult) {
        // Native implementation
        result("/path/to/photo.jpg")
    }
}

EventChannel — streaming data pattern

Dart side

// Connectivity stream example
class ConnectivityChannel {
  static const _channel = EventChannel('com.example.app/connectivity');

  Stream<bool> get
      _channel.receiveBroadcastStream().map(
        (event) => event as bool,
      );
}

// Usage with Riverpod:
@riverpod
Stream<bool> networkConnectivity(Ref ref) {
  return ConnectivityChannel().onConnectivityChanged;
}

Android side (Kotlin)

class ConnectivityStreamHandler(private val context: Context) : EventChannel.StreamHandler {
    private var networkCallback: ConnectivityManager.NetworkCallback? = null

    override fun onListen(arguments: Any?, events: EventChannel.EventSink) {
        val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE)
                as ConnectivityManager
        networkCallback = object : ConnectivityManager.NetworkCallback() {
            override fun onAvailable(network: Network) {
                events.success(true)
            }
            override fun onLost(network: Network) {
                events.success(false)
            }
        }
        cm.registerDefaultNetworkCallback(networkCallback!!)
    }

    override fun onCancel(arguments: Any?) {
        // Unregister callback to prevent leaks
        val cm = context.getSystemService(Context.CONNECTIVITY_SERVICE)
                as ConnectivityManager
        networkCallback?.let { cm.unregisterNetworkCallback(it) }
        networkCallback = null
    }
}

Dart FFI — native C/C++ integration

// lib/src/ffi/image_processor.dart
import 'dart:ffi';
import 'package:ffi/ffi.dart';

// Load native library
final _lib = DynamicLibrary.open('libimage_processor.so'); // Android
// DynamicLibrary.process() for iOS (static linking)

// Bind native function
typedef _ProcessImageNative = Pointer<Uint8> Function(
  Pointer<Uint8> data,
  Int32 width,
  Int32 height,
);
typedef _ProcessImageDart = Pointer<Uint8> Function(
  Pointer<Uint8> data,
  int width,
  int height,
);

final _processImage = _lib
    .lookupFunction<_ProcessImageNative, _ProcessImageDart>('process_image');

// Dart wrapper
Future<Uint8List> processImageFfi(Uint8List imageData, int width, int height) {
  return Isolate.run(() {
    final pointer = calloc<Uint8>(imageData.length);
    try {
      pointer.asTypedList(imageData.length).setAll(0, imageData);
      final result = _processImage(pointer, width, height);
      return result.asTypedList(width * height * 4);
    } finally {
      calloc.free(pointer);
    }
  });
}

Platform views (AndroidView / UiKitView)

// Embedding a native map view
class NativeMapView extends StatelessWidget {
  const NativeMapView({super.key, required this.initialLatLng});
  final LatLng initialLatLng;

  @override
  Widget build(BuildContext context) {
    // Always wrap in RepaintBoundary — platform views are expensive
    return RepaintBoundary(
      child: Platform.isAndroid
          ? AndroidView(
              viewType: 'com.example/native_map',
              creationParams: {
                'lat': initialLatLng.latitude,
                'lng': initialLatLng.longitude,
              },
              creationParamsCodec: const StandardMessageCodec(),
              layoutDirection: TextDirection.ltr,
            )
          : UiKitView(
              viewType: 'com.example/native_map',
              creationParams: {
                'lat': initialLatLng.latitude,
                'lng': initialLatLng.longitude,
              },
              creationParamsCodec: const StandardMessageCodec(),
            ),
    );
  }
}

Permission handling

// Use permission_handler package — DO NOT write raw permission channels
import 'package:permission_handler/permission_handler.dart';

class PermissionService {
  Future<PermissionResult> requestCamera() async {
    final status = await Permission.camera.request();
    return switch (status) {
      PermissionStatus.granted => PermissionResult.granted,
      PermissionStatus.denied => PermissionResult.denied,
      PermissionStatus.permanentlyDenied => PermissionResult.permanentlyDenied,
      _ => PermissionResult.denied,
    };
  }

  Future<void> openSettings() => openAppSettings();
}

Background execution

Android (WorkManager via workmanager package)

// Register background task
await Workmanager().initialize(callbackDispatcher, isInDebugMode: kDebugMode);
await Workmanager().registerPeriodicTask(
  'sync-task',
  'backgroundSync',
  frequency: const Duration(hours: 1),
  constraints: Constraints(networkType: NetworkType.connected),
);

@pragma('vm:entry-point')
void callbackDispatcher() {
  Workmanager().executeTask((task, inputData) async {
    // Background work — no BuildContext, no UI
    await SyncService().syncPendingQueue();
    return Future.value(true);
  });
}

iOS (BGTaskScheduler)

Requires flutter_background_fetch or background_fetch package. Register in AppDelegate + Info.plist with BGTaskSchedulerPermittedIdentifiers.

Federated plugin checklist

When creating a plugin for reuse (internal or public):

□ Create package structure: interface + app-facing + android + ios
□ Platform interface extends PlatformInterface (prevents direct instantiation)
□ App-facing package only imports platform interface (not implementations)
□ Each platform implementation registers itself via registerWith()
□ Dart API is pure Dart (no platform imports)
□ Comprehensive dartdoc on all public API
□ Example app demonstrates all features
□ Tests for Dart logic (mock platform implementations)
□ README includes platform setup instructions

Channel naming convention

com.{company}.{app_or_plugin}/{feature}

Examples:
com.example.app/camera
com.example.app/connectivity
com.example.myPlugin/bluetooth

Always use reverse domain notation. Never use generic names like flutter/channel.

Anti-pattern detection

• MethodChannel name collisions (generic strings) → use reverse domain
• Native code called on main thread for long operations → use background thread/coroutine
• EventChannel without onCancel cleanup → memory/battery leak
• Platform view without RepaintBoundary → performance degradation
• Permission check without rationale flow (permanently denied case not handled)
• FFI pointer not freed → memory leak
• Background task accessing BuildContext → crashes in background
• @pragma('vm:entry-point') missing on background entry point → tree-shaken in release

Uncertainty protocol

• High (≥ 0.80): platform requirements and native SDK docs available
• Medium (0.60–0.79): native API unclear or SDK undocumented
• Low (< 0.60): no native experience or unknown hardware constraints

Cross-skill handoff payload

Use the standard payload from ../../AGENTS.md. Set requesting_skill to flutter-platform-integration.

Output contract

Follow global section order from ../../AGENTS.md. Also include:

• Channel mechanism selection rationale
• Dart + Android (Kotlin) + iOS (Swift) implementation
• Error mapping from platform exceptions to domain exceptions
• Memory/resource cleanup strategy
• Test strategy for platform code

Related resources

• references/method-channel-guide.md
• references/event-channel-guide.md
• references/ffi-guide.md
• references/platform-views-guide.md
• references/background-execution.md
• templates/method-channel.dart
• templates/method-channel-android.kt
• templates/method-channel-ios.swift
• templates/event-channel.dart
• templates/ffi-binding.dart