Flutter Pigeon

Demystifying Flutter Pigeon: A Deep Dive into Efficient Native Integration

by

Ever wanted to leverage the power of native features within your Flutter app? Look no further than Flutter Pigeon! This powerful code generator tool takes the complexity out of native integration, ensuring smooth and type-safe communication between your Flutter code and the underlying platform (Android or iOS). In this deep dive, we’ll unveil the secrets of Flutter Pigeon, guiding you through its functionalities and empowering you to build feature-rich Flutter apps with ease.

What is Flutter Pigeon?

Flutter Pigeon is a code generation tool designed to streamline communication between your Flutter app and the native platform (Android or iOS) it runs on. Essentially, it acts as a bridge, allowing your Flutter code to interact with features and functionalities that aren’t directly available in the Flutter framework itself.

Benefits of using Flutter Pigeon

Here are some key benefits of using Flutter Pigeon:

  • Type Safety: Pigeon enforces type safety, which helps prevent errors and makes your code more reliable. This is a major advantage compared to traditional methods like Method Channels, which can be prone to runtime issues due to mismatched data types.
  • Efficiency: Pigeon generates optimized code for both Flutter and the native platform, leading to faster communication and improved performance in your app.
  • Reduced Boilerplate: Pigeon eliminates the need for writing a lot of repetitive code for platform communication. It automates the process, saving you development time and effort.
  • Clarity: Pigeon uses a clear and concise syntax for defining communication interfaces, making your code easier to understand and maintain.

Overall, Flutter Pigeon simplifies and enhances the process of integrating native functionalities into your Flutter apps, allowing you to build more powerful and versatile experiences.

Setting Up Pigeon in Your Flutter Project

To start using Pigeon, add it as a dev dependency in your Flutter project’s pubspec.yaml file. Once you’ve done that, you can define your communication interface in a Dart file and then run Pigeon to generate the native code for Android and iOS and the Dart side boilerplate.

dev_dependencies:
 pigeon: ^latest_version

After adding the dependency, you can create a Dart file that defines the interface for communication. For example:

import 'package:pigeon/pigeon.dart';

class SearchRequest {
 String query;
}

class SearchResponse {
 List<String> results;
}

@HostApi()
abstract class SearchApi {
 SearchResponse search(SearchRequest request);
}

With the interface defined, you can run Pigeon using the command flutter pub run pigeon to generate the native code for the host platform and the corresponding Dart code. This code will be placed in the generated folder by default, and you can then use it within your Flutter app and native platform code to facilitate communication.

flutter pub run pigeon --input pigeons/search.dart

By setting up Pigeon in your Flutter project, you create a robust channel for native communication that is both type-safe and easy to maintain.

Pigeon’s Approach to Type-Safe Communication

Building Flutter apps often involves interacting with native code (Android or iOS). Here, ensuring type safety is crucial. Type safety means your code defines the expected data types for communication, preventing errors that might arise from mismatched data types between Dart and the native platform.

Flutter Pigeon addresses this challenge by generating type-safe interfaces. These interfaces act like contracts, defining the data types and functions that both the native code and your Flutter code must follow. This enforces consistency and reduces the risk of runtime errors, leading to a more robust and reliable application.

Defining Data and Methods in Dart

The first step to using Pigeon’s type safety is defining how your Flutter code will talk to the native platform. This involves creating a Dart file (usually outside the lib directory) that acts like a blueprint for communication.

Within this file:

  • Data Classes: Define data classes to represent the information you’ll be exchanging between your Flutter code and the native platform. These classes specify the structure and types of the data being passed.
  • Abstract Class: Create an abstract class that outlines the methods available for interacting with the native functionalities. This class acts as a contract, specifying the methods your Flutter code can call and the expected data types for both arguments and return values.

Let’s take a look at an example to illustrate this concept:

import 'package:pigeon/pigeon.dart';

// Define the data class.
class Message {
 String content;
}

// Define the host API with methods for native communication.
@HostApi()
abstract class MessageApi {
 void sendMessage(Message message);
}

In this example, Message is a data class that holds a single string, and MessageApi is an abstract class that defines a message sending method. Pigeon uses these classes to generate the corresponding native code.

Generating Type-Safe Interfaces for Native Platforms

Pigeon shines in its ability to create type-safe communication channels. After defining your data structures and methods in a Dart file, simply run Pigeon using the dedicated command. This generates corresponding native code (for Android and iOS) that mirrors your Dart definitions.

The magic lies in the type-safety. The generated code includes classes and method signatures that perfectly match your Dart code. This ensures data passed between Dart and native platforms is always of the expected type, preventing errors and making your app more reliable.

To generate the type-safe interfaces, you run Pigeon with the appropriate command:

flutter pub run pigeon --input pigeon/message.dart

This command will generate Dart code that includes the abstract class and data class you defined, as well as the native code for both Android and iOS. The generated code will be placed in a directory of your choosing, often within the android/app/src/main/java/ directory for Android and the ios/Runner/ directory for iOS.

For Android, Pigeon generates Kotlin or Java code that you can include in your Android app. Here’s an example of what the generated Kotlin code might look like:

// Generated Kotlin code for Android.
class MessageApi {
   fun sendMessage(message: Message) {
       // Implementation for sending a message.
   }
}

For iOS, Pigeon generates Swift or Objective-C code that you can include in your iOS Runner project. Here’s an example of what the generated Swift code might look like:

// Generated Swift code for iOS.
@objc class MessageApi: NSObject {
   @objc func sendMessage(_ message: Message) {
       // Implementation for sending a message.
   }
}

By generating these type-safe interfaces, Pigeon ensures that the communication between your Flutter app and the native platform is reliable and free from common type-related errors.

Writing the Host API with Pigeon

When integrating native features, seamless communication between your Flutter code and the underlying platform is essential. In Flutter Pigeon, the Host API acts as the bridge for this interaction. It’s a crucial element that defines the methods (functions) your Flutter app can call on the native side (Android or iOS).

Pigeon simplifies the process of creating this Host API. Using a dedicated syntax within a Dart file, you can define the methods available for Flutter to utilize. This makes it clear and efficient to specify how your Flutter code will interact with native functionalities.

Creating Abstract Classes for Native Code Interaction

To leverage native features in your Flutter app, Flutter Pigeon simplifies communication by generating type-safe code. Start by defining abstract classes in a Dart file. Annotate these classes with @HostApi() to signal interaction with the native platform (Android or iOS). Within these classes, define methods representing the functionalities you want to access from the native code. Pigeon will then generate the code for both the native platform and your Flutter app, ensuring smooth and error-free communication.

Here’s an example of an abstract class that you might create for native code interaction:

import 'package:pigeon/pigeon.dart';

class User {
 String id;
 String name;
}

@HostApi()
abstract class UserApi {
 User getUser(String userId);
}

In this Dart file, User is a data class that holds user information, and UserApi is an abstract class with a method to retrieve a user by their ID. Pigeon will use this abstract class to generate the native code the host platform will implement.

Integrating Generated Code into Native Platforms

After Pigeon generates the code, it’s time to bridge the gap! This crucial integration step involves incorporating the generated code into your native Android or iOS project. This enables your Flutter app to talk directly to native features. The integration process ensures that the abstract classes and methods you defined in your Dart file are translated correctly into functional native code.

Incorporating Generated Swift and Objective C Code

Integrating Pigeon with iOS involves incorporating the generated Swift or Objective-C code into your Xcode project. This code translates your abstract classes and methods into functional native counterparts.

Here’s the process:

  1. Locate the generated files: Pigeon places these files in a designated or default directory within your project.
  2. Add files to Xcode: Open your Xcode project and add the generated files to the appropriate target, typically ios/Runner.
  3. Implement native functionality: Fill in the generated interfaces with actual native code. For example, if a user API class was generated, you’d write Swift code to interact with iOS APIs for fetching user data.
  4. Register with Flutter engine: Ensure the generated classes are visible to Flutter by registering them in the AppDelegate or a similar entry point.

Here’s a simplified example of how you might register a generated Swift class with the Flutter engine:

import Flutter
import UIKit

@UIApplicationMain
@objc class AppDelegate: FlutterAppDelegate {
 override func application(
   _ application: UIApplication,
   didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
 ) -> Bool {
   GeneratedPluginRegistrant.register(with: self)
   let controller: FlutterViewController = window?.rootViewController as! FlutterViewController
   UserApiSetup(controller.binaryMessenger)

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

Adding Generated Kotlin and Java Code to Android App

Similar to iOS, integrating Pigeon with Android involves incorporating the generated code into your Android Studio project. This code translates your abstract classes and methods into functionalities specific to the Android platform.

Here’s the process:

  1. Locate the generated files: Pigeon places these files in a designated or default directory within your project.
  2. Add files to Android Studio: Open your Android Studio project and add the generated Kotlin or Java files to the appropriate source directory, typically android/app/src/main/java or android/app/src/main/kotlin.
  3. Implement native functionality: Fill in the generated interfaces with actual Android code. For example, if a user API class was generated, you’d write Kotlin code to interact with Android APIs for fetching user data.
  4. Register with Flutter engine: Ensure the generated classes are visible to Flutter by registering them in the MainActivity or a similar entry point in your Android project.

Here’s a simplified example of how you might register a generated Kotlin class with the Flutter engine:

import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity: FlutterActivity() {
   override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
       super.configureFlutterEngine(flutterEngine)
       MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "user_api_channel").setMethodCallHandler {
           // Note: this method is invoked on the main thread.
           call, result ->
           // Handle method calls from the Dart side.
       }
   }
}

Handling Method Channels with Pigeon

Before Flutter Pigeon, developers relied on method channels for native communication. These channels allow sending messages between Dart and native code, but require manual setup. Pigeon simplifies this process by automating the method channel implementation. This eliminates the complexity and potential errors associated with manual channel creation, making native integration smoother and more reliable.

The Method Channel Implementation Process

Pigeon cuts through the busywork of native communication in Flutter. Traditionally, method channels required writing repetitive code on both Dart and native sides. Pigeon generates most of this code for you!

When you define your communication interface in Dart using Pigeon, it creates the corresponding method channel code. This code automatically handles method names, data serialization (converting data to a format for transfer), and deserialization (converting it back) – all using a simple JSON-like format for efficient data exchange between Dart and the native platform.

Here’s an example of how Pigeon generates the method channel code for a simple Dart class:

import 'package:pigeon/pigeon.dart';

class User {
 String id;
 String name;
}

@HostApi()
abstract class UserApi {
 User getUser(String userId);
}

Running Pigeon with the above Dart file would generate the necessary method channel code for both the Dart side and the native side. On the Dart side, it might look something like this:

// Generated Dart code for method channel implementation.
class UserApi {
 Future<User> getUser(String userId) async {
   final Map<String, dynamic> args = <String, dynamic>{
     'userId': userId,
   };
   final Map<dynamic, dynamic> result = await _channel.invokeMethod('getUser', args);
   return User.fromJson(result);
 }
}

Streamlining Communication Between Dart and Native Code

Pigeon takes the hassle out of message passing between Dart and native code. Its generated code handles the complex tasks of serializing and deserializing data, freeing you to focus on the core functionality of your native methods.

Imagine working with a clear instruction manual! On the native side (like iOS with Swift), Pigeon provides precise guidance on receiving calls from Dart and crafting appropriate responses. Here’s an example to illustrate this concept:

// Generated Swift code to handle method channel communication.
public class UserApi: NSObject, FlutterPlugin {
   public static func register(with registrar: FlutterPluginRegistrar) {
       let channel = FlutterMethodChannel(name: "user_api", binaryMessenger: registrar.messenger()) let instance = UserApi() registrar.addMethodCallDelegate(instance, channel: channel)
   }

   public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
       switch call.method {
           case "getUser": if let args = call.arguments as? [String: Any], let userId = args["userId"] as? String {
               // Call the native function to get user data
               let user = getUser(userId: userId) result(user.toDictionary())
           }
           else {
               result(FlutterError(code: "INVALID_ARGUMENTS", message: "Invalid arguments received for method (call.method)", details: nil))
           }
           default: result(FlutterMethodNotImplemented)
       }
   }

   private func getUser(userId: String) -> User {
       // Implement your native logic to retrieve a user by ID
       // For example, querying a database or contacting a server
       return User(id: userId, name: "John Doe")
   }

}

}

The generated code above shows how Pigeon creates a clear path for method calls from the Dart side to be received and processed on the native side. The handle function is where you would implement the native logic to perform the requested operation, in this case, fetching a user’s information.

Similarly, for Android, the generated Kotlin code would provide a structure for handling method calls:

// Generated Kotlin code to handle method channel communication.
class UserApi: MethodChannel.MethodCallHandler {
 companion object {
   @JvmStatic
   fun registerWith(registrar: Registrar) {
     val channel = MethodChannel(registrar.messenger(), "user_api")
     channel.setMethodCallHandler(UserApi())
   }
 }

 override fun onMethodCall(call: MethodCall, result: MethodChannel.Result) {
   when (call.method) {
     "getUser" -> {
       val userId = call.argument<String>("userId")
       if (userId != null) {
         // Call the native function to get user data
         val user = getUser(userId)
         result.success(user.toMap())
       } else {
         result.error("INVALID_ARGUMENTS", "Invalid arguments received for method ${call.method}", null)
       }
     }
     else -> result.notImplemented()
   }
 }

 private fun getUser(userId: String): User {
   // Implement your native logic to retrieve a user by ID
   // For example, querying a database or contacting a server
   return User(userId, "Jane Smith")
 }
}

The Kotlin example above demonstrates how Pigeon generates a method call handler that listens for method calls from the Dart side. The onMethodCall function checks the method name and arguments, and if they match the expected values, it proceeds to call the native implementation.

Conclusion

Flutter Pigeon tackles the challenge of integrating native features into your Flutter apps. It achieves this by providing a streamlined and type-safe approach. Pigeon automates the generation of repetitive code for method channels, a common communication method between Flutter and native platforms. This saves you time and reduces the potential for errors.

No matter the complexity of your data types, Pigeon can handle the communication setup, freeing you to focus on building your app’s core functionalities. For a more efficient, reliable, and enjoyable development experience, leverage the power of Flutter Pigeon to unlock the native capabilities within your Flutter apps.

Wanna Level up Your Flutter game? Then check out our ebook The Complete Guide to Flutter Developement where we teach you how to build production grade cross platform apps from scratch.Do check it out to completely Master Flutter framework from basic to advanced level.

Leave a comment