One post tagged with "BinaryMessenger"

Flutter’s platform channels are powerful - but when they break, they break hard. The most frequent symptom is a PlatformException at runtime, often caused by mis-registered channels, mismatched codecs, lifecycle missteps, or multi-engine pitfalls. This guide walks through a production-ready approach to designing, debugging, and shipping robust platform channel integrations using MethodCallHandler, BinaryMessenger, Pigeon, and configureFlutterEngine.

Prereqs

• Flutter 3.22+ and Dart 3.4+ (null safety)
• Android embedding v2 (Kotlin), iOS (Swift)
• Familiarity with MethodChannel, EventChannel, BasicMessageChannel

Contents

• Mental model: BinaryMessenger, channels, codecs
• The failure modes behind PlatformException
• Correct setup on Android (configureFlutterEngine) and iOS
• Dart API surface and error handling
• Strongly typed channels with the Pigeon package
• Multi-engine considerations, background isolates, lifecycle
• Testing and mocking channel calls
• Performance and production hardening
• Troubleshooting checklist

1) Mental model: BinaryMessenger, channels, codecs​

• BinaryMessenger is the transport that carries serialized messages between Dart and the platform.

  • Dart: ServicesBinding.defaultBinaryMessenger
  • Android: flutterEngine.dartExecutor.binaryMessenger
  • iOS: FlutterEngine.binaryMessenger or FlutterViewController.binaryMessenger

• Channels are logical names on top of the BinaryMessenger:

  • MethodChannel (RPC-style request/response)
  • EventChannel (streams)
  • BasicMessageChannel (fire-and-forget or duplex)

• StandardMessageCodec/StandardMethodCodec serialize a limited set of types (null, bool, int, double, String, Uint8List/Int32List/Int64List/Float64List, List, Map with supported types). Anything else causes serialization errors or PlatformException.

2) Why you hit PlatformException​

Common root causes:

• Channel name mismatch (Dart vs native).
• Method name mismatch → “not implemented”.
• Plugin or channel not registered (MissingPluginException).
• Lifecycle: using an engine that hasn’t been configured; forgot configureFlutterEngine; wrong messenger.
• Codec/type mismatch or large payload not handled.
• Reply not sent exactly once or sent on a background thread when UI work is required.
• Running in a background isolate without initializing a BinaryMessenger.

Tip: Always log the channel name, method, and arguments on both sides during development.

3) Correct setup on Android with configureFlutterEngine​

When manually wiring channels in an app (as opposed to writing a reusable plugin), use FlutterActivity.configureFlutterEngine to bind your MethodCallHandler to the engine’s BinaryMessenger.

Kotlin (android/app/src/main/kotlin/.../MainActivity.kt):

package com.example.app

import android.os.Build
import android.os.Bundle
import android.os.Handler
import android.os.Looper
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodCall
import io.flutter.plugin.common.MethodChannel

class MainActivity : FlutterActivity() {
    private val CHANNEL = "com.example.app/device"

    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)

        val channel = MethodChannel(flutterEngine.dartExecutor.binaryMessenger, CHANNEL)
        channel.setMethodCallHandler { call: MethodCall, result: MethodChannel.Result ->
            when (call.method) {
                "getSdkInt" -> {
                    // If UI work is needed, ensure to post to main thread
                    Handler(Looper.getMainLooper()).post {
                        result.success(Build.VERSION.SDK_INT)
                    }
                }
                else -> result.notImplemented()
            }
        }
    }
}

Key points:

• Use the engine’s BinaryMessenger: flutterEngine.dartExecutor.binaryMessenger.
• If you override configureFlutterEngine, plugin auto-registration still happens via GeneratedPluginRegistrant unless you remove it in settings. Leave it as-is unless you know why you’re changing it.
• Never keep a static global MethodChannel; bind to the provided BinaryMessenger to support multiple engines.

4) Correct setup on iOS (Swift)​

Swift (ios/Runner/AppDelegate.swift):

import UIKit
import Flutter

@UIApplicationMain
class AppDelegate: FlutterAppDelegate {
  private let channelName = "com.example.app/device"

  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {

    let controller = window?.rootViewController as! FlutterViewController
    let channel = FlutterMethodChannel(
      name: channelName,
      binaryMessenger: controller.binaryMessenger
    )

    channel.setMethodCallHandler { [weak self] (call: FlutterMethodCall, result: @escaping FlutterResult) in
      switch call.method {
      case "getSdkInt":
        // Example value; iOS doesn’t have SDK_INT like Android
        result(UIDevice.current.systemVersion)
      default:
        result(FlutterMethodNotImplemented)
      }
    }

    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

Key points:

• Use the view controller or engine’s binaryMessenger.
• Always return exactly one result call per method invocation.

5) Dart side: MethodChannel and error handling​

Dart (lib/device_service.dart):

import 'dart:async';
import 'package:flutter/services.dart';
import 'package:flutter/foundation.dart';

class DeviceService {
  static const _channel = MethodChannel('com.example.app/device');

  Future<int> getSdkInt() async {
    try {
      final value = await _channel.invokeMethod<int>('getSdkInt');
      if (value == null) {
        throw const PlatformException(
          code: 'NULL_VALUE',
          message: 'Native returned null for getSdkInt',
        );
      }
      return value;
    } on PlatformException catch (e, st) {
      if (kDebugMode) {
        // Prefer structured logging
        debugPrint('PlatformException: ${e.code} ${e.message}\n$st');
      }
      rethrow;
    }
  }
}

Best practices:

• Wrap calls in try/catch for PlatformException.
• Validate nulls when using nullable generics in invokeMethod().
• Use structured error codes on native side to make debugging actionable.

If native needs to call Dart:

// Somewhere during app init
DeviceService._channel.setMethodCallHandler((MethodCall call) async {
  switch (call.method) {
    case 'onSomethingHappened':
      // handle event from native
      return;
    default:
      throw PlatformException(code: 'UNIMPLEMENTED', message: call.method);
  }
});

6) Strongly-typed, safer channels with the Pigeon package​

Pigeon generates Dart, Kotlin, and Swift code for type-safe platform channels, reducing runtime mismatches that cause PlatformException.

pubspec.yaml:

dev_dependencies:
  pigeon: ^14.0.0

Define your API (pigeons/device_api.dart):

import 'package:pigeon/pigeon.dart';

class DeviceInfo {
  late int sdkInt;
  late String manufacturer;
}

@HostApi()
abstract class DeviceApi {
  DeviceInfo getDeviceInfo();
}

Generate code:

flutter pub run pigeon \
  --input pigeons/device_api.dart \
  --dart_out lib/pigeon/device_api.g.dart \
  --kotlin_out android/app/src/main/kotlin/com/example/app/DeviceApi.g.kt \
  --kotlin_package com.example.app \
  --swift_out ios/Runner/DeviceApi.g.swift

Implement on Android (DeviceApi.g.kt usage):

class DeviceApiImpl : DeviceApi {
    override fun getDeviceInfo(): DeviceInfo {
        val info = DeviceInfo()
        info.sdkInt = android.os.Build.VERSION.SDK_INT
        info.manufacturer = android.os.Build.MANUFACTURER ?: "unknown"
        return info
    }
}

// In MainActivity.configureFlutterEngine:
DeviceApi.setUp(flutterEngine.dartExecutor.binaryMessenger, DeviceApiImpl())

Implement on iOS (DeviceApi.g.swift usage):

class DeviceApiImpl: DeviceApi {
  func getDeviceInfo() throws -> DeviceInfo {
    return DeviceInfo(sdkInt: Int32(ProcessInfo.processInfo.operatingSystemVersion.majorVersion),
                      manufacturer: "Apple")
  }
}

// In AppDelegate after engine/viewController is available:
DeviceApiSetup.setUp(binaryMessenger: controller.binaryMessenger, api: DeviceApiImpl())

Use from Dart:

import 'pigeon/device_api.g.dart';

final _api = DeviceApi();

Future<DeviceInfo> loadInfo() => _api.getDeviceInfo();

With Pigeon:

• Codec is generated and consistent across platforms.
• Errors thrown natively become FlutterError → PlatformException with structured details.
• Safer refactors and fewer magic strings.

7) Multi-engine, lifecycle, and Activity/UIViewController constraints​

• Multiple FlutterEngines: Always bind channels to the engine’s BinaryMessenger you intend to use. Don’t keep static/global channels.
• FlutterActivity vs CachedEngine: If using a cached engine, channels must be set up when the engine is created, not per-activity instance.
• Plugins needing an Activity context: Implement ActivityAware in Android plugins or use FlutterPluginBinding.applicationContext for non-UI work.
• onDetachedFromEngine: Unregister handlers and clear references to avoid leaks.

Android plugin skeleton (for reference):

class ExamplePlugin : FlutterPlugin, ActivityAware {
  private var channel: MethodChannel? = null

  override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
    channel = MethodChannel(binding.binaryMessenger, "com.example.app/device")
    channel?.setMethodCallHandler { call, result -> /* ... */ }
  }

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

  // ActivityAware for UI-related APIs...
}

8) Background isolates and headless execution​

If you call platform channels from a background isolate, initialize a BinaryMessenger for that isolate.

Dart (e.g., in a background isolate entrypoint):

import 'package:flutter/services.dart';

void backgroundEntryPoint() {
  BackgroundIsolateBinaryMessenger.ensureInitialized(ServicesBinding.instance.defaultBinaryMessenger);
  // Now MethodChannel calls from this isolate will work.
}

Some plugins provide helpers for background entrypoints (e.g., Firebase Messaging). Ensure you follow their initialization docs.

9) Testing and mocking channels​

Unit test in Dart without native code by mocking the MethodChannel via BinaryMessenger.

Dart (test/device_service_test.dart):

import 'package:flutter/services.dart';
import 'package:flutter_test/flutter_test.dart';
import 'package:your_app/device_service.dart';

void main() {
  const channel = MethodChannel('com.example.app/device');
  final messenger = TestDefaultBinaryMessengerBinding.instance.defaultBinaryMessenger;

  setUp(() {
    messenger.setMockMethodCallHandler(channel, (MethodCall call) async {
      switch (call.method) {
        case 'getSdkInt':
          return 34;
        default:
          throw PlatformException(code: 'UNIMPLEMENTED');
      }
    });
  });

  tearDown(() {
    messenger.setMockMethodCallHandler(channel, null);
  });

  test('getSdkInt returns 34', () async {
    final service = DeviceService();
    expect(await service.getSdkInt(), 34);
  });
}

With Pigeon, you can mock the generated Dart API directly and skip channels entirely in unit tests.

10) Performance and production hardening​

• Avoid chatty channels. Batch operations or cache results (e.g., device info) in Dart.
• Choose the right channel:
  • MethodChannel for request/response.
  • EventChannel for continuous streams (sensors).
  • BasicMessageChannel for custom message patterns or non-RPC semantics.
• Keep payloads small and codec-friendly. For large binary data, use files or platform-side caching with a lightweight handle across the channel.
• Threading:
  • Android: switch to main thread for UI APIs.
  • iOS: dispatch to main queue when touching UIKit.
• Timeouts and retries: Add app-level timeouts around invokeMethod and surface actionable errors to the UI/logging.
• Logging: Include channel name, method, code, and details on failures. Prefer structured logs.

11) Troubleshooting checklist​

• PlatformException(code: “UNAVAILABLE”, message: “…”) or unknown code

  • Verify native method returns result exactly once and handles error/success paths.
  • Wrap native exceptions and return FlutterError (iOS) or result.error (Android) with structured codes.

• MissingPluginException(No implementation found for method X on channel Y)

  • Channel not registered? Ensure configureFlutterEngine ran and you used the right BinaryMessenger.
  • Incorrect channel name? Keep a single source of truth (const).
  • Running on a background isolate? Initialize BackgroundIsolateBinaryMessenger.
  • Using a cached engine? Ensure registration occurred when the engine was created.

• Method not implemented

  • Typo in method name.
  • Wrong platform check (e.g., calling Android-only method on iOS).

• Type mismatch / codec errors

  • Send only StandardMessageCodec-supported types.
  • With Pigeon, regenerate after model changes on all platforms.

• Multi-engine bugs

  • No static channels. Tie handlers to a specific engine’s messenger.
  • Unregister in onDetachedFromEngine to avoid leaks/dispatched-to-stale-engine issues.

• iOS not receiving messages

  • Ensure you use controller.binaryMessenger from the active FlutterViewController (or engine.binaryMessenger).
  • Avoid setting handler before the view controller/engine is ready.

12) Example: End-to-end with Pigeon and Riverpod​

A quick pattern using Riverpod to expose device info:

Dart (lib/device_provider.dart):

import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'pigeon/device_api.g.dart';

final deviceInfoProvider = FutureProvider<DeviceInfo>((ref) async {
  final api = DeviceApi();
  return api.getDeviceInfo();
});

Widget:

import 'package:flutter/material.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
import 'device_provider.dart';

class DeviceInfoTile extends ConsumerWidget {
  const DeviceInfoTile({super.key});

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final asyncInfo = ref.watch(deviceInfoProvider);

    return asyncInfo.when(
      data: (info) => ListTile(
        title: Text('SDK: ${info.sdkInt}'),
        subtitle: Text('Manufacturer: ${info.manufacturer}'),
      ),
      loading: () => const CircularProgressIndicator(),
      error: (err, _) => ListTile(
        title: const Text('Failed to load device info'),
        subtitle: Text(err.toString()),
      ),
    );
  }
}

This approach:

• Strongly typed Pigeon API.
• Simple async data flow with Riverpod.
• Clear error surfacing if a PlatformException bubbles up.

Key takeaways​

• Primary cause of PlatformException is contract drift: mismatched channel names, method names, payload types, or lifecycle issues.
• Always bind handlers to the correct BinaryMessenger-per engine-and use configureFlutterEngine to register on Android.
• Use Pigeon for type-safe, code-generated channels that prevent many runtime mistakes.
• Handle errors deliberately: structure error codes and messages on native and catch PlatformException in Dart.
• Plan for multi-engine, background isolates, and app lifecycle. Unregister handlers on detach.
• Test with BinaryMessenger mocks and keep the channel surface small, fast, and stable.

Next steps

• Migrate ad-hoc MethodChannel code to Pigeon for critical integrations.
• Add structured logging around channel calls and centralize channel names.
• Audit multi-engine and background isolate code paths.
• Add unit tests using setMockMethodCallHandler and integration tests with Flutter Driver/Integration Test for end-to-end coverage.

With these patterns, you’ll eliminate most PlatformException pain points and run robust, production-grade Flutter platform integrations.