feat(analytics): event bridge common package

packages/mixpanel_flutter/android/build.gradle

@@ -2,6 +2,7 @@ group 'com.mixpanel.mixpanel_flutter'
 version '1.0'
 
 buildscript {
+    ext.kotlin_version = '1.9.0'
     repositories {
         google()
         mavenCentral()
@@ -10,6 +11,7 @@ buildscript {
     dependencies {
         // Use a compatible version of Gradle Plugin
         classpath 'com.android.tools.build:gradle:8.1.0' // Updated to 8.1.0
+        classpath "org.jetbrains.kotlin:kotlin-gradle-plugin:$kotlin_version"
     }
 }
 
@@ -21,6 +23,7 @@ rootProject.allprojects {
 }
 
 apply plugin: 'com.android.library'
+apply plugin: 'kotlin-android'
 
 android {
     // Safely handle 'namespace' property for new Android Gradle plugin versions
@@ -40,12 +43,35 @@ android {
         targetCompatibility JavaVersion.VERSION_17
     }
 
+    kotlinOptions {
+        jvmTarget = '17'
+        // mixpanel-android-common:1.0.1 is published with Kotlin 2.0
+        // metadata. Flutter's gradle integration picks a KGP version we
+        // can't reliably control from this module's buildscript, so a
+        // Kotlin 1.9.x compiler often ends up compiling this plugin and
+        // chokes on the newer metadata. The bytecode itself is
+        // forward-compatible (the consumed APIs are just a Flow and a
+        // data class), so suppressing the metadata version check is the
+        // canonical workaround.
+        freeCompilerArgs += ['-Xskip-metadata-version-check']
+    }
+
+    sourceSets {
+        main.kotlin.srcDirs += 'src/main/kotlin'
+    }
+
     lintOptions {
         disable 'InvalidPackage'
     }
 }
 
 dependencies {
-    // Use the Mixpanel Android SDK
     implementation "com.mixpanel.android:mixpanel-android:8.7.0"
+    // mixpanel-android:8.7.0 only declares mixpanel-android-common as a
+    // runtime dependency, so MixpanelEventBridge is not on the compile
+    // classpath unless we add it explicitly here. EventBridgeSubscriber.kt
+    // imports it directly.
+    implementation "com.mixpanel.android:mixpanel-android-common:1.0.1"
+    implementation "org.jetbrains.kotlin:kotlin-stdlib:$kotlin_version"
+    implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.1"
 }

packages/mixpanel_flutter/android/src/main/java/com/mixpanel/mixpanel_flutter/MixpanelFlutterPlugin.java

@@ -201,12 +201,30 @@ public void onMethodCall(@NonNull MethodCall call, @NonNull Result result) {
             case "getAllVariants":
                 handleGetAllVariants(call, result);
                 break;
+            case "startEventBridge":
+                handleStartEventBridge(result);
+                break;
+            case "stopEventBridge":
+                handleStopEventBridge(result);
+                break;
             default:
                 result.notImplemented();
                 break;
         }
     }
 
+    private void handleStartEventBridge(Result result) {
+        if (channel != null) {
+            EventBridgeSubscriber.start(channel);
+        }
+        result.success(null);
+    }
+
+    private void handleStopEventBridge(Result result) {
+        EventBridgeSubscriber.stop();
+        result.success(null);
+    }
+
     private void initializeMethodChannel() {
         if (channel == null && flutterPluginBinding != null) {
             channel = new MethodChannel(flutterPluginBinding.getBinaryMessenger(), "mixpanel_flutter",
@@ -785,6 +803,7 @@ private long readPersistenceTtlMillis(Map<String, Object> policyMap) {
 
     @Override
     public void onDetachedFromEngine(@NonNull FlutterPluginBinding binding) {
+        EventBridgeSubscriber.stop();
         if (channel != null) {
             channel.setMethodCallHandler(null);
             channel = null;

packages/mixpanel_flutter/android/src/main/kotlin/com/mixpanel/mixpanel_flutter/EventBridgeSubscriber.kt

@@ -0,0 +1,62 @@
+package com.mixpanel.mixpanel_flutter
+
+import android.util.Log
+import com.mixpanel.android.eventbridge.MixpanelEventBridge
+import io.flutter.plugin.common.MethodChannel
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Dispatchers
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.SupervisorJob
+import kotlinx.coroutines.flow.collect
+import kotlinx.coroutines.launch
+import kotlinx.coroutines.plus
+import org.json.JSONException
+import org.json.JSONObject
+
+/**
+ * Subscribes to the native Mixpanel SDK's [MixpanelEventBridge] (a Kotlin
+ * `SharedFlow`) and forwards each event to the Dart side via the existing
+ * Flutter MethodChannel.
+ *
+ * The Java plugin calls [start] from `onAttachedToEngine` and [stop] from
+ * `onDetachedFromEngine`. This object is a singleton because the native
+ * SharedFlow itself is a singleton — we never want more than one active
+ * subscription per process.
+ */
+object EventBridgeSubscriber {
+
+    private val scope = CoroutineScope(SupervisorJob() + Dispatchers.Main)
+    private var job: Job? = null
+
+    @JvmStatic
+    fun start(channel: MethodChannel) {
+        if (job != null) return
+        job = scope.launch {
+            MixpanelEventBridge.events().collect { event ->
+                val properties = event.properties?.let { safelyConvert(it) }
+                channel.invokeMethod(
+                    "onMixpanelEvent",
+                    mapOf(
+                        "eventName" to event.eventName,
+                        "properties" to properties,
+                    )
+                )
+            }
+        }
+    }
+
+    @JvmStatic
+    fun stop() {
+        job?.cancel()
+        job = null
+    }
+
+    private fun safelyConvert(json: JSONObject): Map<String, Any?>? = try {
+        MixpanelFlutterHelper.toMap(json)
+    } catch (e: JSONException) {
+        // A malformed properties payload should not abort the whole
+        // subscription — drop this event's properties and keep collecting.
+        Log.w("EventBridgeSubscriber", "Failed to convert event properties", e)
+        null
+    }
+}

packages/mixpanel_flutter/example/pubspec.lock

@@ -143,6 +143,13 @@ packages:
       relative: true
     source: path
     version: "2.8.0"
+  mixpanel_flutter_common:
+    dependency: transitive
+    description:
+      path: "../../mixpanel_flutter_common"
+      relative: true
+    source: path
+    version: "0.1.0"
   path:
     dependency: transitive
     description:

packages/mixpanel_flutter/ios/mixpanel_flutter.podspec

@@ -16,6 +16,9 @@ Pod::Spec.new do |s|
   s.source_files = 'Classes/**/*'
   s.dependency 'Flutter'
   s.dependency 'Mixpanel-swift', '6.4.0'
+  # Explicit dependency (also pulled in transitively by Mixpanel-swift 6.4+)
+  # so `import MixpanelSwiftCommon` in our plugin resolves reliably.
+  s.dependency 'MixpanelSwiftCommon', '~> 1.0.0'
   s.platform = :ios, '13.0'
 
   # Flutter.framework does not contain a i386 slice.

packages/mixpanel_flutter/lib/mixpanel_flutter.dart

@@ -6,6 +6,7 @@ import 'package:flutter/foundation.dart' show kIsWeb;
 import 'package:flutter/services.dart';
 import 'package:mixpanel_flutter/codec/mixpanel_message_codec.dart';
 import 'package:mixpanel_flutter/src/version.dart';
+import 'package:mixpanel_flutter_common/mixpanel_flutter_common.dart';
 
 /// Identifies where a served [MixpanelFlagVariant] came from. Non-null on
 /// every variant the SDK returns:
@@ -344,6 +345,39 @@ class Mixpanel {
     'mp_lib': 'flutter',
   };
 
+  // Wires the reverse path from the native MixpanelEventBridge into the
+  // Dart-side [MixpanelEventBridge] the first time `Mixpanel` is touched.
+  // The MethodCallHandler is installed eagerly so a native event can never
+  // race ahead of the handler, but the native subscription itself is only
+  // started when a Dart listener attaches — see [setLifecycleCallbacks].
+  // Web is skipped — the JS SDK has no EventBridge.
+  // ignore: unused_field
+  static final bool _eventBridgeWired = _wireEventBridge();
+
+  static bool _wireEventBridge() {
+    if (kIsWeb) return false;
+    _channel.setMethodCallHandler((MethodCall call) async {
+      if (call.method == 'onMixpanelEvent') {
+        final args = (call.arguments as Map?)?.cast<String, Object?>();
+        final eventName = args?['eventName'] as String?;
+        final properties =
+            (args?['properties'] as Map?)?.cast<String, Object?>();
+        if (eventName != null) {
+          MixpanelEventBridge.notifyListeners(
+            eventName: eventName,
+            properties: properties,
+          );
+        }
+      }
+      return null;
+    });
+    MixpanelEventBridge.setLifecycleCallbacks(
+      onActivate: () => _channel.invokeMethod<void>('startEventBridge'),
+      onDeactivate: () => _channel.invokeMethod<void>('stopEventBridge'),
+    );
+    return true;
+  }
+
   final String _token;
   final People _people;
   final FeatureFlags _featureFlags;
@@ -371,6 +405,9 @@ class Mixpanel {
       Map<String, dynamic>? superProperties,
       Map<String, dynamic>? config,
       FeatureFlagsConfig? featureFlags}) async {
+    // Force lazy initialization of the reverse-direction MethodCallHandler
+    // so any native events tracked after this point reach Dart subscribers.
+    _eventBridgeWired;
     var allProperties = <String, dynamic>{'token': token};
     allProperties['optOutTrackingDefault'] = optOutTrackingDefault;
     allProperties['trackAutomaticEvents'] = trackAutomaticEvents;

packages/mixpanel_flutter/macos/mixpanel_flutter.podspec

@@ -16,6 +16,9 @@ Pod::Spec.new do |s|
   s.source_files = 'Classes/**/*'
   s.dependency 'FlutterMacOS'
   s.dependency 'Mixpanel-swift', '6.4.0'
+  # Explicit dependency (also pulled in transitively by Mixpanel-swift 6.4+)
+  # so `import MixpanelSwiftCommon` in our plugin resolves reliably.
+  s.dependency 'MixpanelSwiftCommon', '~> 1.0.0'
   s.platform = :osx, '10.15'
 
   s.pod_target_xcconfig = { 'DEFINES_MODULE' => 'YES' }

packages/mixpanel_flutter/pubspec.lock

@@ -128,6 +128,13 @@ packages:
       url: "https://pub.dev"
     source: hosted
     version: "1.17.0"
+  mixpanel_flutter_common:
+    dependency: "direct main"
+    description:
+      path: "../mixpanel_flutter_common"
+      relative: true
+    source: path
+    version: "0.1.0"
   path:
     dependency: transitive
     description:

packages/mixpanel_flutter/pubspec.yaml

@@ -15,6 +15,8 @@ dependencies:
     sdk: flutter
   flutter_web_plugins:
     sdk: flutter
+  mixpanel_flutter_common:
+    path: ../mixpanel_flutter_common
 
 dev_dependencies:
   flutter_test:

packages/mixpanel_flutter/swift/Classes/SwiftMixpanelFlutterPlugin.swift

@@ -4,18 +4,29 @@ import Flutter
 import FlutterMacOS
 #endif
 import Mixpanel
+import MixpanelSwiftCommon
 
 #if os(macOS)
 public typealias MixpanelFlutterPlugin = SwiftMixpanelFlutterPlugin
 #endif
 
 public class SwiftMixpanelFlutterPlugin: NSObject, FlutterPlugin {
-    
+
     private var instance: MixpanelInstance?
     var token: String?
     var mixpanelProperties: [String: String]?
     let defaultFlushInterval = 60.0
-
+
+    // Held so `startEventBridge` (invoked lazily from Dart) can fan native
+    // events back through the same channel that delivers regular method
+    // calls. Released on `deinit` along with the task.
+    private var channel: FlutterMethodChannel?
+
+    // The long-lived AsyncStream consumer that forwards native
+    // MixpanelEventBridge events to Dart. Created on first
+    // `startEventBridge` and cancelled by `stopEventBridge` / `deinit`.
+    private var eventBridgeTask: Task<Void, Never>?
+
     public static func register(with registrar: FlutterPluginRegistrar) {
         let readWriter = MixpanelReaderWriter()
         let codec = FlutterStandardMethodCodec(readerWriter: readWriter)
@@ -25,7 +36,43 @@ public class SwiftMixpanelFlutterPlugin: NSObject, FlutterPlugin {
         let channel = FlutterMethodChannel(name: "mixpanel_flutter", binaryMessenger: registrar.messenger, codec: codec)
         #endif
         let instance = SwiftMixpanelFlutterPlugin()
+        instance.channel = channel
         registrar.addMethodCallDelegate(instance, channel: channel)
+
+        // The native EventBridge subscription is started lazily from Dart
+        // via `startEventBridge` when the first listener attaches to
+        // `MixpanelEventBridge.events`. Apps that never consume events
+        // never pay the cost of the AsyncStream consumer task.
+    }
+
+    deinit {
+        eventBridgeTask?.cancel()
+    }
+
+    private func handleStartEventBridge(_ result: @escaping FlutterResult) {
+        guard eventBridgeTask == nil, let channel = channel else {
+            result(nil)
+            return
+        }
+        if #available(iOS 13.0, macOS 10.15, *) {
+            eventBridgeTask = Task {
+                for await event in MixpanelEventBridge.shared.eventStream() {
+                    await MainActor.run {
+                        channel.invokeMethod("onMixpanelEvent", arguments: [
+                            "eventName": event.eventName,
+                            "properties": event.properties,
+                        ])
+                    }
+                }
+            }
+        }
+        result(nil)
+    }
+
+    private func handleStopEventBridge(_ result: @escaping FlutterResult) {
+        eventBridgeTask?.cancel()
+        eventBridgeTask = nil
+        result(nil)
     }
 
     public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
@@ -174,6 +221,12 @@ public class SwiftMixpanelFlutterPlugin: NSObject, FlutterPlugin {
         case "getAllVariants":
             handleGetAllVariants(call, result: result)
             break
+        case "startEventBridge":
+            handleStartEventBridge(result)
+            break
+        case "stopEventBridge":
+            handleStopEventBridge(result)
+            break
         default:
             result(FlutterMethodNotImplemented)
         }