bridge_native #

A Flutter plugin that provides type-safe communication between Flutter and native platforms (Android/iOS) using Pigeon. This plugin contains autogenerated Pigeon code and Flutter-side utilities for seamless Flutter-to-native integration.

What is bridge_native? #

bridge_native is a foundation plugin that provides:

• Autogenerated Pigeon code for type-safe communication
• Request-Response models (Req/Res classes)
• Flutter utilities (sendToNative() function and Native widget)
• Platform interfaces that your main plugin implements

This plugin is typically used as a dependency by other plugins that need Flutter-to-native communication.

Features #

• Type-Safe Models: Autogenerated Req and Res classes using Pigeon
• ReqApi Interface: Type-safe API for native implementations
• Flutter Utilities:
  • sendToNative(): Send requests from Flutter to native
  • Native widget: Wrapper to receive native events
• Cross-Platform: Works with both Android (Java) and iOS (Objective-C)
• Zero Manual Serialization: Pigeon handles all serialization automatically

Installation #

Add this to your plugin's pubspec.yaml:

dependencies:
  bridge_native: ^1.0.0

Then run:

flutter pub get

Architecture #

┌─────────────────────────────────────┐
│         Your Flutter Plugin         │
│                                     │
│  Uses: sendToNative()               │
│        Native widget                │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│         bridge_native               │
│                                     │
│  Provides:                          │
│  • Req/Res models                   │
│  • ReqApi interface                 │
│  • Pigeon autogenerated code        │
└──────────────┬──────────────────────┘
               │
               ▼
┌─────────────────────────────────────┐
│      Your Native Implementation     │
│                                     │
│  Implements: ReqApi                 │
│  Sets up: EventChannel (optional)   │
└─────────────────────────────────────┘

Usage #

1. Flutter Side - Use Provided Utilities #

Send Request to Native

import 'package:bridge_native/bridge/native.dart';

// Send request to native and receive response
Future<void> getDeviceInfo() async {
  final response = await sendToNative(
    key: 'getDeviceInfo',
    data: {'includeModel': true},
  );

  print('Response: ${response.data}');
}

Listen to Native Events

import 'package:bridge_native/bridge/native.dart';
import 'package:flutter/material.dart';

class MyWidget extends StatelessWidget {
  @override
  Widget build(BuildContext context) {
    return Native(
      child: YourContent(),
      doNativeDataBack: (data) {
        // Handle data from native
        print('Native event: $data');

        if (data is Map) {
          final key = data['key']?.toString() ?? '';
          final payload = data['data'];
          // Process event...
        }
      },
    );
  }
}

2. Native Side - Implement ReqApi #

The autogenerated code provides interfaces/protocols that you must implement in your native plugin.

Android (Java)

package com.example.yourplugin;

import androidx.annotation.NonNull;
import io.flutter.embedding.engine.plugins.FlutterPlugin;
import io.flutter.plugin.common.EventChannel;
import vn.son.bridge.Pigeon;
import java.util.HashMap;
import java.util.Map;

public class YourPlugin implements FlutterPlugin {

    private EventChannel eventChannel;
    private EventChannel.EventSink eventSink;

    @Override
    public void onAttachedToEngine(@NonNull FlutterPluginBinding binding) {
        // 1. Setup Pigeon API
        Pigeon.ReqApi.setup(binding.getBinaryMessenger(), new AndroidAPI());

        // 2. Setup EventChannel for sending events to Flutter
        eventChannel = new EventChannel(binding.getBinaryMessenger(), "bridgeStream");
        eventChannel.setStreamHandler(new EventChannel.StreamHandler() {
            @Override
            public void onListen(Object arguments, EventChannel.EventSink events) {
                eventSink = events;
            }

            @Override
            public void onCancel(Object arguments) {
                eventSink = null;
            }
        });
    }

    @Override
    public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
        eventChannel.setStreamHandler(null);
    }

    // Implement ReqApi interface
    class AndroidAPI implements Pigeon.ReqApi {
        @NonNull
        @Override
        public Pigeon.Res request(@NonNull Pigeon.Req request) {
            // Handle request from Flutter
            String key = request.getKey();
            Map<Object, Object> data = request.getData();

            // Process based on key
            switch (key) {
                case "getDeviceInfo":
                    return handleDeviceInfo(data);
                case "openCamera":
                    return handleCamera(data);
                default:
                    return createResponse("unknown", null);
            }
        }

        private Pigeon.Res handleDeviceInfo(Map<Object, Object> data) {
            Map<String, Object> result = new HashMap<>();
            result.put("model", android.os.Build.MODEL);
            result.put("version", android.os.Build.VERSION.RELEASE);
            return createResponse("deviceInfo", result);
        }

        private Pigeon.Res createResponse(String key, Map<String, Object> data) {
            Pigeon.Res response = new Pigeon.Res();
            response.setKey(key);
            response.setData((Map) data);
            return response;
        }
    }

    // Send event to Flutter
    public void sendEventToFlutter(String key, Map<String, Object> data) {
        if (eventSink != null) {
            Map<String, Object> event = new HashMap<>();
            event.put("key", key);
            event.put("data", data);
            eventSink.success(event);
        }
    }
}

iOS (Swift)

import Flutter
import bridge_native

public class YourPlugin: NSObject, FlutterPlugin, ReqApi {

    private var eventChannel: FlutterEventChannel?
    private var eventSink: FlutterEventSink?

    public static func register(with registrar: FlutterPluginRegistrar) {
        let instance = YourPlugin()

        // 1. Setup EventChannel for sending events to Flutter
        let channel = FlutterEventChannel(
            name: "bridgeStream",
            binaryMessenger: registrar.messenger()
        )
        channel.setStreamHandler(instance)
        instance.eventChannel = channel

        // 2. Setup Pigeon API
        ReqApiSetup(registrar.messenger(), instance)
    }

    // Implement ReqApi protocol
    public func requestRequest(
        _ request: Req,
        error: AutoreleasingUnsafeMutablePointer<FlutterError?>
    ) -> Res? {
        let res = Res()

        switch request.key {
        case "getDeviceInfo":
            res.key = "deviceInfo"
            res.data = [
                "model": UIDevice.current.model,
                "version": UIDevice.current.systemVersion
            ]

        case "openCamera":
            // Handle camera
            res.key = "cameraOpened"
            res.data = ["success": true]

        default:
            res.key = "unknown"
            res.data = nil
        }

        return res
    }

    // Send event to Flutter
    func sendEventToFlutter(key: String, data: [String: Any]) {
        let event: [String: Any] = [
            "key": key,
            "data": data
        ]
        eventSink?(event)
    }
}

// MARK: - FlutterStreamHandler
extension YourPlugin: FlutterStreamHandler {
    public func onListen(
        withArguments arguments: Any?,
        eventSink events: @escaping FlutterEventSink
    ) -> FlutterError? {
        self.eventSink = events
        return nil
    }

    public func onCancel(withArguments arguments: Any?) -> FlutterError? {
        self.eventSink = nil
        return nil
    }
}

API Reference #

Flutter API #

sendToNative({key, data})

Sends a request to native code and awaits response.

Parameters:

• key (dynamic): Request identifier
• data (dynamic): Request payload (typically Map)

Returns:

• Future<Res>: Response from native

Example:

final res = await sendToNative(
  key: 'action',
  data: {'param': 'value'},
);

Native Widget

A widget wrapper that receives events from native code via EventChannel.

Properties:

• child (Widget, required): Your widget content
• doNativeDataBack (Function(dynamic), required): Callback for native events

Example:

Native(
  child: MyContent(),
  doNativeDataBack: (data) {
    // Handle event
  },
)

Native API #

Android - Pigeon.ReqApi Interface

public interface ReqApi {
    @NonNull
    Res request(@NonNull Req request);
}

Setup:

Pigeon.ReqApi.setup(binaryMessenger, new YourImplementation());

iOS - ReqApi Protocol

@protocol ReqApi
- (nullable Res *)requestRequest:(Req *)request
                           error:(FlutterError **)error;
@end

Setup:

ReqApiSetup(binaryMessenger, yourImplementation);

Data Models #

Req - Request Model

Res - Response Model

Complete Example #

See the example directory for a complete working example of using bridge_native.

Key implementation points:

• Flutter: Uses sendToNative() and Native widget
• Android: Implements Pigeon.ReqApi in EkycPlugin.kt
• iOS: Implements ReqApi protocol in EkycPlugin.swift
• Both platforms setup EventChannel named "bridgeStream"

Important Notes #

EventChannel Setup #

bridge_native does NOT setup EventChannel for you. You must:

1. Create EventChannel in your plugin's native code
2. Use the name "bridgeStream" (required by Native widget)
3. Send events as Map with key and data fields

Pigeon Versions #

This plugin uses Pigeon 10.1.4 for code generation. The generated code is compatible with:

• Android: Java/Kotlin
• iOS: Objective-C/Swift

Communication Pattern #

Request → Response (Synchronous-like):

• Use sendToNative() from Flutter
• Native implements ReqApi and returns Res

Event Streaming (Asynchronous):

• Native sends to EventChannel
• Flutter listens via Native widget

Troubleshooting #

"No implementation found for method request" #

Cause: ReqApi not properly setup in native code.

Solution:

• Android: Call Pigeon.ReqApi.setup(messenger, yourImpl) in onAttachedToEngine
• iOS: Call ReqApiSetup(messenger, yourImpl) in register(with:)

Events not received in Flutter #

Cause: EventChannel not setup or wrong channel name.

Solution:

• Verify channel name is exactly "bridgeStream"
• Ensure Native widget is mounted in widget tree
• Check that native is calling eventSink?.success(data)

Type casting errors #

Solution: Always type-check dynamic data:

if (data is Map) {
  final key = data['key']?.toString() ?? '';
  // Safe to use
}

How bridge_native Works #

What It Provides #

1. Autogenerated Pigeon Code:

   • Req and Res classes (Android + iOS)
   • ReqApi interface/protocol
   • Codec for serialization

2. Flutter Utilities:

   • sendToNative() function (wraps Pigeon API)
   • Native widget (wraps EventChannel listener)
   • Convenience functions for common patterns

What You Must Implement #

1. In Your Native Plugin:

   • Implement ReqApi interface/protocol
   • Setup EventChannel if you need native → Flutter events
   • Handle requests in request() method

2. In Your Flutter Plugin:

   • Use sendToNative() to send requests
   • Use Native widget to receive events
   • Process responses and events

Development #

Regenerating Pigeon Code #

If you need to modify the API:

1. Edit pigeons/br_api.dart
2. Run Pigeon code generation:

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

Testing #

Test your implementation:

test('sendToNative returns response', () async {
  final res = await sendToNative(key: 'test', data: {});
  expect(res, isNotNull);
  expect(res.key, isNotNull);
});

Best Practices #

1. Define Key Constants:

   class BridgeKeys {
     static const getDeviceInfo = 'getDeviceInfo';
     static const openCamera = 'openCamera';
   }
   

2. Type-Safe Data Handling:

   if (data is Map<String, dynamic>) {
     final value = data['key'] as String?;
   }
   

3. Error Handling:

   try {
     final res = await sendToNative(key: 'action', data: {});
   } catch (e) {
     print('Bridge error: $e');
   }
   

4. Document Your Protocol:

   • List all supported keys
   • Define data structures
   • Document response formats

Additional Resources #

• Pigeon Documentation
• Flutter Platform Channels
• Real-world example plugin using bridge_native

License #

This project is licensed under the MIT License. See the LICENSE file for details.

Contributing #

Contributions are welcome! Please submit issues or pull requests.

Repository: https://github.com/sonuos1501/bridge_native Maintainer: SON (Lucas)