Update to Flutter Plugin V2 embedding; deprecate old methods for background execution

MuhammedAm1n · MuhammedAm1n · commit 545336c4c588 · 2025-05-06T11:48:48.000+03:00
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,3 +1,9 @@
+## 1.6.0 - 2025-05-06
+- Updated to use the modern FlutterPlugin.FlutterPluginBinding pattern
+- Deprecated Registrar, PluginRegistrantCallback, and ShimPluginRegistry usage
+- Added backward compatibility for older Flutter versions
+- Improved handling of plugin registration in background execution
+
 ## 1.5.0 - 2025-01-29
 - Updated gradle dependencies
   
diff --git a/README.md b/README.md
@@ -53,8 +53,6 @@ Or add the info to the Info.plist
 
 ### Update the AppDelegate
 
-Make sure you call the `setPluginRegistrantCallback` so other plugins can be accessed in the background.
-
 ```
 import UIKit
 import Flutter
@@ -65,6 +63,8 @@ import background_location_tracker
     override func application(_ application: UIApplication,didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
         GeneratedPluginRegistrant.register(with: self)
 
+        // Register plugins for background execution - this method is deprecated 
+        // but kept for backward compatibility
         BackgroundLocationTrackerPlugin.setPluginRegistrantCallback { registry in
             GeneratedPluginRegistrant.register(with: registry)
         }
@@ -124,7 +124,21 @@ Future stopLocationTracking() async {
 
 ```
 This is mostly caused by a misconfiguration of the plugin:
-Android Pre v2 embedding: make sure the plugin registrant callback is set
-Android v2 embedding: Log a new github issues. This
-iOS: make sure the plugin registrant callback is set
+- Android: This plugin now uses Flutter's Plugin V2 embedding pattern (FlutterPluginBinding) so you don't need to set a manual plugin registrant callback.
+- iOS: For compatibility with older Flutter versions, the setPluginRegistrantCallback is still available but will be removed in a future version.
+
+If you're using Flutter 1.12 or later, the plugin should work out of the box with the V2 embedding.
 ```
+
+## Migration Guide
+
+### Upgrading from older versions
+
+This plugin has been updated to use the modern Flutter Plugin V2 embedding pattern with FlutterPluginBinding. If you're using Flutter 1.12 or later, you don't need to make any changes to your app's code.
+
+For backward compatibility, the older methods are still available but marked as deprecated:
+
+- `BackgroundLocationTrackerPlugin.setPluginRegistrantCallback` on Android
+- `BackgroundLocationTrackerPlugin.setPluginRegistrantCallback` on iOS
+
+These methods will be removed in a future version of the plugin.
diff --git a/android/src/main/kotlin/com/icapps/background_location_tracker/BackgroundLocationTrackerPlugin.kt b/android/src/main/kotlin/com/icapps/background_location_tracker/BackgroundLocationTrackerPlugin.kt
@@ -19,17 +19,29 @@ import io.flutter.plugin.common.MethodCall
 import io.flutter.plugin.common.MethodChannel
 import io.flutter.plugin.common.MethodChannel.MethodCallHandler
 import io.flutter.plugin.common.MethodChannel.Result
-import io.flutter.plugin.common.PluginRegistry
+import io.flutter.embedding.engine.plugins.FlutterPlugin.FlutterPluginBinding
+import io.flutter.embedding.engine.FlutterEngine
 
 class BackgroundLocationTrackerPlugin : FlutterPlugin, MethodCallHandler, ActivityAware {
     private var lifecycle: Lifecycle? = null
     private var methodCallHelper: MethodCallHelper? = null
-
-    override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
-        registerBackgroundLocationManager(binding.binaryMessenger, binding.applicationContext)
+    private var channel: MethodChannel? = null
+    private var applicationContext: Context? = null
+
+    override fun onAttachedToEngine(binding: FlutterPluginBinding) {
+        applicationContext = binding.applicationContext
+        channel = MethodChannel(binding.binaryMessenger, FOREGROUND_CHANNEL_NAME)
+        channel?.setMethodCallHandler(this)
+        
+        if (methodCallHelper == null) {
+            methodCallHelper = MethodCallHelper.getInstance(binding.applicationContext)
+        }
     }
 
-    override fun onDetachedFromEngine(binding: FlutterPlugin.FlutterPluginBinding) {
+    override fun onDetachedFromEngine(binding: FlutterPluginBinding) {
+        channel?.setMethodCallHandler(null)
+        channel = null
+        applicationContext = null
     }
 
     override fun onMethodCall(call: MethodCall, result: Result) {
@@ -38,10 +50,7 @@ class BackgroundLocationTrackerPlugin : FlutterPlugin, MethodCallHandler, Activi
 
     override fun onAttachedToActivity(binding: ActivityPluginBinding) {
         lifecycle = FlutterLifecycleAdapter.getActivityLifecycle(binding)
-        if (methodCallHelper == null) {
-            ActivityCounter.attach(binding.activity)
-            methodCallHelper = MethodCallHelper.getInstance(binding.activity.applicationContext)
-        }
+        ActivityCounter.attach(binding.activity)
         methodCallHelper?.let {
             lifecycle?.removeObserver(it)
             lifecycle?.addObserver(it)
@@ -50,67 +59,42 @@ class BackgroundLocationTrackerPlugin : FlutterPlugin, MethodCallHandler, Activi
 
     override fun onDetachedFromActivity() {}
 
-    override fun onReattachedToActivityForConfigChanges(binding: ActivityPluginBinding) {}
+    override fun onReattachedToActivityForConfigChanges(binding: ActivityPluginBinding) {
+        onAttachedToActivity(binding)
+    }
 
-    override fun onDetachedFromActivityForConfigChanges() {}
+    override fun onDetachedFromActivityForConfigChanges() {
+        onDetachedFromActivity()
+    }
 
     companion object {
         private const val TAG = "FBLTPlugin"
         private const val FOREGROUND_CHANNEL_NAME = "com.icapps.background_location_tracker/foreground_channel"
 
-        var pluginRegistryCallback: PluginRegistry.PluginRegistrantCallback? = null
+        // New static properties for background execution
+        private var flutterEngine: FlutterEngine? = null
 
-        @JvmStatic
-        private fun registerBackgroundLocationManager(messenger: BinaryMessenger, ctx: Context) {
-            val channel = MethodChannel(messenger, FOREGROUND_CHANNEL_NAME)
-            channel.setMethodCallHandler(BackgroundLocationTrackerPlugin().apply {
-                if (methodCallHelper == null) {
-                    methodCallHelper = MethodCallHelper.getInstance(ctx)
-                }
-                methodCallHelper?.let {
-                    lifecycle?.removeObserver(it)
-                    lifecycle?.addObserver(it)
-                }
-            })
-        }
+        // For compatibility with older plugins
+        @Deprecated("Use FlutterEngine's plugin registry instead")
+        private var pluginRegistrantCallback: ((FlutterEngine) -> Unit)? = null
 
         @JvmStatic
-        fun registerWith(registrar: PluginRegistry.Registrar) {
-            val activity = registrar.activity()
-            if (activity == null) {
-                Logger.debug(TAG, "Activity should not be null while registering this plugin")
-                return
-            }
-
-            val lifecycle: Lifecycle = if (activity is LifecycleOwner) {
-                (activity as LifecycleOwner).lifecycle
-            } else {
-                Logger.debug(TAG, "Your activity has not implemented a lifecycle owner. We will create one for you.")
-                @Suppress("DEPRECATION")
-                ProxyLifecycleProvider(activity).lifecycle
-            }
-
-            ActivityCounter.attach(activity)
-            val channel = MethodChannel(registrar.messenger(), FOREGROUND_CHANNEL_NAME)
-            channel.setMethodCallHandler(BackgroundLocationTrackerPlugin().apply {
-                if (methodCallHelper == null) {
-                    methodCallHelper = MethodCallHelper.getInstance(registrar.activeContext())
-                }
-                methodCallHelper?.let {
-                    lifecycle.removeObserver(it)
-                    lifecycle.addObserver(it)
-                }
-            })
+        @Deprecated("Use the Android embedding v2 instead")
+        fun setPluginRegistrantCallback(callback: ((FlutterEngine) -> Unit)) {
+            pluginRegistrantCallback = callback
         }
 
-        @Deprecated(message = "Use the Android v2 embedding method.")
+        // Method to get or create the Flutter engine for background execution
         @JvmStatic
-        fun setPluginRegistrantCallback(pluginRegistryCallback: PluginRegistry.PluginRegistrantCallback) {
-            BackgroundLocationTrackerPlugin.pluginRegistryCallback = pluginRegistryCallback
+        fun getFlutterEngine(context: Context): FlutterEngine {
+            return flutterEngine ?: FlutterEngine(context).also {
+                flutterEngine = it
+                pluginRegistrantCallback?.invoke(it)
+            }
         }
     }
 
-    @Deprecated(message = "Use the Android v2 embedding method.")
+    @Deprecated("Use the Android embedding v2 instead")
     private class ProxyLifecycleProvider internal constructor(activity: Activity) : Application.ActivityLifecycleCallbacks, LifecycleOwner {
         override val lifecycle = LifecycleRegistry(this)
         private val registrarActivityHashCode: Int = activity.hashCode()
diff --git a/android/src/main/kotlin/com/icapps/background_location_tracker/flutter/FlutterBackgroundManager.kt b/android/src/main/kotlin/com/icapps/background_location_tracker/flutter/FlutterBackgroundManager.kt
@@ -11,7 +11,6 @@ import com.icapps.background_location_tracker.utils.SharedPrefsUtil
 import io.flutter.embedding.engine.FlutterEngine
 import io.flutter.embedding.engine.dart.DartExecutor
 import io.flutter.embedding.engine.loader.FlutterLoader
-import io.flutter.embedding.engine.plugins.shim.ShimPluginRegistry
 import io.flutter.plugin.common.MethodCall
 import io.flutter.plugin.common.MethodChannel
 import io.flutter.view.FlutterCallbackInformation
@@ -24,10 +23,7 @@ internal object FlutterBackgroundManager {
     private fun getInitializedFlutterEngine(ctx: Context): FlutterEngine {
         Logger.debug("BackgroundManager", "Creating new engine")
 
-        val engine = FlutterEngine(ctx)
-        //Backwards compatibility with v1. We register all the user's plugins.
-        BackgroundLocationTrackerPlugin.pluginRegistryCallback?.registerWith(ShimPluginRegistry(engine))
-        return engine
+        return BackgroundLocationTrackerPlugin.getFlutterEngine(ctx)
     }
 
     fun sendLocation(ctx: Context, location: Location) {
diff --git a/example/android/app/src/main/AndroidManifest.xml b/example/android/app/src/main/AndroidManifest.xml
@@ -1,7 +1,7 @@
 <manifest xmlns:android="http://schemas.android.com/apk/res/android">
     <application
         android:label="example"
-        android:name="${applicationName}"
+        android:name=".Application"
         android:icon="@mipmap/ic_launcher">
         <activity
             android:name=".MainActivity"
diff --git a/example/android/app/src/main/kotlin/com/example/example/Application.kt b/example/android/app/src/main/kotlin/com/example/example/Application.kt
@@ -0,0 +1,24 @@
+package com.example.example
+
+import io.flutter.app.FlutterApplication
+import com.icapps.background_location_tracker.BackgroundLocationTrackerPlugin
+import io.flutter.plugin.common.PluginRegistry
+import io.flutter.plugins.GeneratedPluginRegistrant
+
+// This Application class shows both approaches:
+// 1. The deprecated approach using PluginRegistrantCallback (for backward compatibility)
+// 2. Comments showing that this is not needed with the modern FlutterPluginBinding approach
+class Application : FlutterApplication() {
+    override fun onCreate() {
+        super.onCreate()
+
+        // Note: This is the deprecated approach and is only kept for backward compatibility
+        // With modern Flutter plugins using the v2 embedding (FlutterPluginBinding),
+        // this callback registration is not necessary
+        BackgroundLocationTrackerPlugin.setPluginRegistrantCallback { engine ->
+            // In a modern plugin using FlutterPluginBinding, plugins are automatically
+            // registered through the FlutterEngine's plugin registry
+            GeneratedPluginRegistrant.registerWith(engine)
+        }
+    }
+} 
diff --git a/example/ios/Runner/AppDelegate.swift b/example/ios/Runner/AppDelegate.swift
@@ -9,9 +9,13 @@ import background_location_tracker
     didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
   ) -> Bool {
     GeneratedPluginRegistrant.register(with: self)
+    
+    // Register plugins for background execution - this call is kept for backward compatibility
+    // With modern Flutter versions (1.12+), this is not required as the plugin uses FlutterPluginBinding
     BackgroundLocationTrackerPlugin.setPluginRegistrantCallback { registry in
         GeneratedPluginRegistrant.register(with: registry)
     }
+    
     return super.application(application, didFinishLaunchingWithOptions: launchOptions)
   }
 }
diff --git a/ios/Classes/BackgroundLocationTrackerPlugin.m b/ios/Classes/BackgroundLocationTrackerPlugin.m
@@ -14,6 +14,8 @@ + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar {
   [SwiftBackgroundLocationTrackerPlugin registerWithRegistrar:registrar];
 }
 
+// This method is deprecated and will be removed in a future version
+// Use the iOS embedding v2 method instead
 + (void)setPluginRegistrantCallback:(FlutterPluginRegistrantCallback)callback {
     [SwiftBackgroundLocationTrackerPlugin setPluginRegistrantCallback:callback];
 }
diff --git a/ios/Classes/ForegroundChannel.swift b/ios/Classes/ForegroundChannel.swift
@@ -25,8 +25,15 @@ public class ForegroundChannel : NSObject {
     
     private let userDefaults = UserDefaults.standard
     
+    // This method is kept for backwards compatibility but marked as deprecated
+    @available(*, deprecated, message: "Use createMethodChannel(binaryMessenger:) instead")
     public static func getMethodChannel(with registrar: FlutterPluginRegistrar) -> FlutterMethodChannel {
-        return FlutterMethodChannel(name: FOREGROUND_CHANNEL_NAME, binaryMessenger: registrar.messenger())
+        return createMethodChannel(binaryMessenger: registrar.messenger())
+    }
+    
+    // New method that works with FlutterBinaryMessenger directly
+    public static func createMethodChannel(binaryMessenger: FlutterBinaryMessenger) -> FlutterMethodChannel {
+        return FlutterMethodChannel(name: FOREGROUND_CHANNEL_NAME, binaryMessenger: binaryMessenger)
     }
     
     public func handle(_ call: FlutterMethodCall, result: @escaping FlutterResult) {
diff --git a/ios/Classes/SwiftBackgroundLocationTrackerPlugin.swift b/ios/Classes/SwiftBackgroundLocationTrackerPlugin.swift
@@ -17,7 +17,8 @@ public class SwiftBackgroundLocationTrackerPlugin: FlutterPluginAppLifeCycleDele
     private static var initializedBackgroundCallbacksStarted = false
     private static var locationData: [String: Any]? = nil
     
-    private static var flutterPluginRegistrantCallback: FlutterPluginRegistrantCallback?
+    // This will store the plugin that registered engines
+    private static var pluginRegistrants: [(FlutterEngine) -> Void] = []
     
     private let locationManager = LocationManager.shared()
     
@@ -27,12 +28,13 @@ extension SwiftBackgroundLocationTrackerPlugin: FlutterPlugin {
     
     @objc
     public static func setPluginRegistrantCallback(_ callback: @escaping FlutterPluginRegistrantCallback) {
-        flutterPluginRegistrantCallback = callback
+        // Store the callback in our new pluginRegistrants array
+        pluginRegistrants.append(callback)
     }
     
     public static func register(with registrar: FlutterPluginRegistrar) {
         foregroundChannel = ForegroundChannel()
-        let methodChannel = ForegroundChannel.getMethodChannel(with: registrar)
+        let methodChannel = ForegroundChannel.createMethodChannel(binaryMessenger: registrar.messenger())
         let instance = SwiftBackgroundLocationTrackerPlugin()
         registrar.addMethodCallDelegate(instance, channel: methodChannel)
         registrar.addApplicationDelegate(instance)
@@ -61,7 +63,10 @@ extension SwiftBackgroundLocationTrackerPlugin: FlutterPlugin {
             
             CustomLogger.log(message: "FlutterEngine.run returned `\(success)`")
             if success {
-                SwiftBackgroundLocationTrackerPlugin.flutterPluginRegistrantCallback?(flutterEngine)
+                // Run all the registered plugin registrants
+                for registrant in pluginRegistrants {
+                    registrant(flutterEngine)
+                }
                 self.flutterEngine = flutterEngine
             } else {
                 CustomLogger.log(message: "FlutterEngine.run returned `false` we will cleanup the flutterEngine")

Original file line number	Diff line number	Diff line change
`@@ -9,9 +9,13 @@ import background_location_tracker`
`9`	`9`	`didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?`
`10`	`10`	`) -> Bool {`
`11`	`11`	`GeneratedPluginRegistrant.register(with: self)`
	`12`	`+`
	`13`	`+ // Register plugins for background execution - this call is kept for backward compatibility`
	`14`	`+ // With modern Flutter versions (1.12+), this is not required as the plugin uses FlutterPluginBinding`
`12`	`15`	`BackgroundLocationTrackerPlugin.setPluginRegistrantCallback { registry in`
`13`	`16`	`GeneratedPluginRegistrant.register(with: registry)`
`14`	`17`	`}`
	`18`	`+`
`15`	`19`	`return super.application(application, didFinishLaunchingWithOptions: launchOptions)`
`16`	`20`	`}`
`17`	`21`	`}`
Original file line number	Diff line number	Diff line change
`@@ -14,6 +14,8 @@ + (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar>*)registrar {`
`14`	`14`	`[SwiftBackgroundLocationTrackerPlugin registerWithRegistrar:registrar];`
`15`	`15`	`}`
`16`	`16`
	`17`	`+// This method is deprecated and will be removed in a future version`
	`18`	`+// Use the iOS embedding v2 method instead`
`17`	`19`	`+ (void)setPluginRegistrantCallback:(FlutterPluginRegistrantCallback)callback {`
`18`	`20`	`[SwiftBackgroundLocationTrackerPlugin setPluginRegistrantCallback:callback];`
`19`	`21`	`}`