Executando Dart em segundo plano com plugins do Flutter e geofencing
Aprenda como plugins do Flutter podem executar código Dart em segundo plano no Android.
04/11/2022: Este artigo foi atualizado para substituir links quebrados devido a mudanças de nome ou local de docs e plugins.
09/10/2020: Este artigo foi atualizado para refletir a migração para a API de embedding v2 do Android. As instruções de migração para aplicativos criados antes da 1.12 podem ser encontradas aqui, e aqui para plugins.
Seja para tratar notificações push, atualizações de localização ou eventos de sensores, muitos recursos úteis exigem que um aplicativo consiga tratar eventos sem interação do usuário, mesmo quando não está rodando em primeiro plano. Até agora, aplicativos escritos com Flutter só conseguiam tratar eventos em segundo plano usando código de plataforma, e os plugins não tinham como permitir que quem os usa fornecesse um callback para tratar eventos em segundo plano em Dart. Basicamente, se um usuário do Flutter quisesse tratar eventos em segundo plano em um aplicativo, era preciso criar uma implementação específica para cada uma das plataformas-alvo.
Felizmente, essa situação não existe mais, graças à chegada do suporte do Flutter à execução de código Dart em segundo plano. Tendo projetado grande parte do fluxo de execução em segundo plano do Flutter, estou animado para compartilhar minhas experiências desenvolvendo plugins que aproveitam essa funcionalidade, como o android_alarm_manager e um handler de eventos de localização do iOS, para ajudar você a começar a criar seus próprios plugins.
Ao longo do restante deste artigo, vou explorar (em detalhes) o processo de construir um plugin Flutter que trata eventos de geofencing em segundo plano no Android e no iOS. Por fim, só por diversão, vou mostrar como usei este plugin de geofencing para criar um aplicativo simples que pode ser usado para abrir automaticamente o portão da minha garagem quando eu me aproximar de casa.
Geofencing: definindo a API do Dart
Antes de escrever qualquer código específico de plataforma, primeiro preciso definir a API do Dart para o plugin de geofencing. Como Android e iOS têm cada um suas próprias APIs para registrar e tratar eventos de geofencing, quero que a interface do Dart forneça uma abstração de geofencing razoável que seja compatível com as duas plataformas. Sem entrar em muitos detalhes sobre as APIs do Android e do iOS, a seguir está, de forma aproximada, a interface do Dart que vou usar no meu plugin:
/// A circular region which represents a geofence.
abstract class GeofenceRegion {
/// The ID associated with the geofence.
///
/// This ID identifies the geofence and is required to delete a
/// specific geofence.
final String id;
/// The location (center point) of the geofence.
final Location location;
/// The radius around `location` that is part of the geofence.
final double radius;
/// Listen to these geofence events.
final List<GeofenceEvent> triggers;
/// Android-specific settings for a geofence.
final AndroidGeofencingSettings androidSettings;
GeofenceRegion(
this.id, double latitude, double longitude, this.radius, this.triggers,
{AndroidGeofencingSettings androidSettings});
}
abstract class GeofencingPlugin {
/// Initialize the plugin and request relevant permissions from the user.
static Future<bool> initialize() async;
/// Register for geofence events for a [GeofenceRegion].
///
/// `region` is the geofence region to register with the system.
/// `callback` is the method to be called when a geofence event associated
/// with `region` occurs.
static Future<bool> registerGeofence(
GeofenceRegion region,
void Function(List<String> id, Location location, GeofenceEvent event) callback);
/// Stop receiving geofence events for a given [GeofenceRegion].
static Future<bool> removeGeofence(GeofenceRegion region);
/// Stop receiving geofence events for an identifier associated with a
/// geofence region.
static Future<bool> removeGeofenceById(String id) async;
}
Esta interface oferece a seguinte funcionalidade aos usuários do plugin:
-
A capacidade de criar instâncias de
GeofenceRegion, que contêm as coordenadas e o raio de uma geofence, um ID único e uma lista de eventos de geofencing a escutar. Como o Android oferece um conjunto de opções mais rico para definir geofences do que o iOS, as opções específicas do Android ficam disponíveis pela propriedade opcionalandroidSettings. -
GeofencingPlugin.registerGeofencepermite registrar uma instância deGeofenceRegioncom um callback que é invocado quando um evento de geofence para essa região é recebido. -
GeofencingPlugin.removeGeofenceeGeofencingPlugin.removeGeofenceByIdcancelam o registro de umGeofenceRegionpara que ele pare de disparar eventos adicionais.
No geral, esta interface é bastante simples e (em grande parte) independente de plataforma, o que torna o plugin fácil de usar tanto no Android quanto no iOS.
Execução de Dart em segundo plano
Esta seção explica como configurar seu isolate para execução em segundo plano. Você vai aprender como referenciar callbacks e como usar o callback dispatcher.
Referenciando callbacks
Agora que a interface do Dart está definida, comece a adicionar a infraestrutura para se comunicar com as partes específicas de plataforma do plugin. Por exemplo, o código a seguir inicializa o plugin de geofencing e registra as geofences:
abstract class GeofencingPlugin {
static const MethodChannel _channel =
const MethodChannel('plugins.flutter.io/geofencing_plugin');
static Future<bool> initialize() async {
final callback = PluginUtilities.getCallbackHandle(callbackDispatcher);
await _channel.invokeMethod('GeofencingPlugin.initializeService',
<dynamic>[callback.toRawHandle()]);
}
static Future<bool> registerGeofence(
GeofenceRegion region,
void Function(List<String> id, Location location, GeofenceEvent event)
callback) {
if (Platform.isIOS &&
region.triggers.contains(GeofenceEvent.dwell) &&
(region.triggers.length == 1)) {
throw UnsupportedError("iOS does not support 'GeofenceEvent.dwell'");
}
final args = <dynamic>[
PluginUtilities.getCallbackHandle(callback).toRawHandle()
];
args.addAll(region._toArgs());
_channel.invokeMethod('GeofencingPlugin.registerGeofence', args);
}
/*
* … `removeGeofence` methods here …
*/
}
Se você já desenvolveu plugins Flutter e conhece MethodChannel, isso deve parecer esperado, em grande parte. (Se você é novo no desenvolvimento de plugins, confira
o artigo sobre platform channels para uma introdução). No entanto, as duas chamadas a
PluginUtilities.getCallbackHandle podem chamar atenção.
Para invocar um callback do Dart como resultado de um evento em segundo plano, você precisa obter um handle que é passado entre o Dart e o código de plataforma, e que também permite buscar o callback entre threads de plataforma e isolates do Dart.
Nota à parte: Obter um CallbackHandle para um método de PluginUtilities.getCallbackHandle
tem como efeito colateral popular um cache de callbacks dentro da engine do Flutter, como visto no diagrama acima. Esse cache mapeia as informações necessárias para recuperar callbacks em handles inteiros brutos, que são simplesmente hashes calculados com base nas propriedades do callback. Esse cache persiste entre execuções, mas esteja atento: as buscas de callback podem falhar se o callback for renomeado ou movido e PluginUtilities.getCallbackHandle
não for chamado para o callback atualizado.
No código acima, duas instâncias de CallbackHandle são obtidas: uma para o callback, que está associado a um
GeofenceRegion, e outra para um método com o nome callbackDispatcher. O método
callbackDispatcher, o entrypoint do isolate em segundo plano, é responsável por pré-processar os dados brutos dos eventos de geofence, buscar callbacks por meio de
PluginUtilities.getCallbackFromHandle e invocá-los para as geofences registradas.
O callback dispatcher
Como mencionado no final da seção anterior, vou usar um padrão que chamo de callback dispatcher para criar o entrypoint do isolate em segundo plano do plugin de geofencing. Esse padrão permite executar a inicialização necessária para estabelecer canais de comunicação com o código de plataforma, além de permitir a criação de interfaces não triviais para métodos de callback. Para este plugin de geofencing, a implementação do callback dispatcher é a seguinte:
void callbackDispatcher() {
// 1. Initialize MethodChannel used to communicate with the platform portion of the plugin.
const MethodChannel _backgroundChannel =
MethodChannel('plugins.flutter.io/geofencing_plugin_background');
// 2. Setup internal state needed for MethodChannels.
WidgetsFlutterBinding.ensureInitialized();
// 3. Listen for background events from the platform portion of the plugin.
_backgroundChannel.setMethodCallHandler((MethodCall call) async {
final args = call.arguments;
// 3.1. Retrieve callback instance for handle.
final Function callback = PluginUtilities.getCallbackFromHandle(
CallbackHandle.fromRawHandle(args[0]));
assert(callback != null);
// 3.2. Preprocess arguments.
final triggeringGeofences = args[1].cast<String>();
final locationList = args[2].cast<double>();
final triggeringLocation = locationFromList(locationList);
final GeofenceEvent event = intToGeofenceEvent(args[3]);
// 3.3. Invoke callback.
callback(triggeringGeofences, triggeringLocation, event);
});
// 4. Alert plugin that the callback handler is ready for events.
_backgroundChannel.invokeMethod('GeofencingService.initialized');
}
Como você pode ver, na invocação de callbackDispatcher (no momento da criação do isolate em segundo plano do plugin de geofencing), apenas quatro operações são executadas. Primeiro, um
MethodChannel é criado para escutar eventos do plugin. Em seguida, WidgetsFlutterBinding.ensureInitialized()
é chamado para inicializar o estado necessário para se comunicar com a engine do Flutter. Nesse ponto, o MethodCall
handler é configurado para processar os eventos do plugin, e por fim a parte de plataforma do plugin é avisada de que o isolate em segundo plano está inicializado e pronto para começar a tratar eventos.
Quando o plugin começa a enviar eventos ao callback dispatcher, o callback fornecido pelo usuário do plugin pode ser invocado. Primeiro,
PluginUtilities.getCallbackFromHandle é chamado para recuperar uma instância do callback associado ao evento de geofencing disparado, usando o handle bruto do callback. Em seguida, os argumentos brutos de
MethodCall são refinados em:
-
Uma instância de
List<String>com os IDs das geofences que foram disparadas Uma instância de
Locationdescrevendo a localização atual do dispositivo-
Uma instância do enum
GeofenceEvent, que representa se o dispositivo entrou, saiu ou permaneceu dentro das geofences disparadas.
Em seguida, forneça essas informações como argumentos para nosso callback.
Nota importante: Você deve ter notado que nenhum estado é mantido dentro do handler de callback. Isso acontece porque não há garantia de que o isolate em segundo plano continue vivo enquanto o próprio aplicativo está em segundo plano. Tanto Android quanto iOS têm políticas de ciclo de vida que podem fazer com que serviços ou execuções em segundo plano sejam encerrados, o que significa que o isolate em segundo plano pode ser destruído e depois recriado na próxima vez que o aplicativo for reativado. Como resultado, a melhor prática é evitar armazenar estado volátil tanto no handler de callback quanto nos callbacks fornecidos pelo usuário.
Neste ponto, já temos todo o código Dart necessário para o plugin! Agora, passemos para a parte específica de plataforma do plugin de geofencing.
Execução em segundo plano: Android (Kotlin)
Para a implementação do plugin no Android, preciso implementar as seguintes classes:
-
A classe
GeofencingPlugin, que é registrada na engine do Flutter para receber e tratar chamadas de método feitas pelo código Dart -
Um
GeofencingBroadcastReceiver, que é invocado pelo sistema em um evento de geofence -
O
GeofencingService, que cria o isolate em segundo plano, inicializa o callback dispatcher descrito anteriormente e processa os eventos de geofence antes de invocar o callback dispatcher.
Esse trio formado por 1) plugin, 2) broadcast receiver e 3) service é um padrão comum em plugins para Android, então vale a pena se familiarizar com ele. Embora eu tenha decidido usar Kotlin para este plugin, tudo aqui também pode ser implementado com Java.
GeofencingPlugin
Como mencionado antes, a principal função do GeofencingPlugin é processar pedidos do código Dart e então registrar ou remover geofences com base no conteúdo desse pedido. Uma instância dessa classe é criada automaticamente e adicionada ao registro de plugins na inicialização do aplicativo.
Essa classe implementa duas interfaces que são necessárias para a funcionalidade básica do plugin:
-
FlutterPlugin: declaraonAttachedToEngineeonDetachedFromEngine, usados para notificar o plugin sobre seu status de conexão com uma instância da engine do Flutter. -
MethodCallHandler: declaraonMethodCall, o método usado para processar mensagens enviadas ao plugin por umMethodChannel.
A maioria dos plugins precisa implementar tanto FlutterPlugin quanto MethodCallHandler, mas alguns plugins também podem precisar de informações sobre o
Activity atual ou sobre outro componente do aplicativo.
Para acessar componentes do aplicativo atualmente anexados à instância do plugin, um plugin deve implementar uma ou mais das interfaces de awareness para
Activity,
BroadcastReceiver,
ContentProvider ou
Service. Essas interfaces declaram callbacks que podem ser invocados pela engine do Flutter para notificar o plugin quando um componente é anexado ou desanexado. Por exemplo, um plugin que precisa de acesso a uma
Activity implementaria a interface ActivityAware e seria notificado quando o plugin ganha ou perde acesso a uma
Activity devido à minimização do aplicativo.
Criando geofences
Para tratar pedidos, crie uma instância de MethodChannel no mesmo channel de antes e, em seguida, registre a
GeofencingPlugin com esse novo channel na implementação de onAttachedToEngine:
override fun onAttachedToEngine(binding: FlutterPlugin.FlutterPluginBinding) {
mContext = binding.getApplicationContext()
mGeofencingClient = LocationServices.getGeofencingClient(mContext!!)
val channel = MethodChannel(binding.getBinaryMessenger(), "plugins.flutter.io/geofencing_plugin")
channel.setMethodCallHandler(this)
}
Para gerenciar esses pedidos, onMethodCall precisa ser implementado:
override fun onMethodCall(call: MethodCall, result: Result) {
val args = call.arguments<ArrayList<*>>()
when(call.method) {
"GeofencingPlugin.initializeService" -> {
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
mActivity?.requestPermissions(REQUIRED_PERMISSIONS, 12312)
}
// Simply stores the callback handle for the callback dispatcher
initializeService(mContext!!, args)
result.success(true)
}
"GeofencingPlugin.registerGeofence" -> registerGeofence(mContext!!,
mGeofencingClient!!,
args,
result,
true)
"GeofencingPlugin.removeGeofence" -> removeGeofence(mContext!!,
mGeofencingClient!!,
args,
result)
else -> result.notImplemented()
}
}
Por fim, vou adicionar a capacidade de registrar geofences (remover geofences é relativamente trivial, então vou focar em adicioná-las neste artigo):
@JvmStatic
private fun getGeofencingRequest(geofence: Geofence, initialTrigger: Int): GeofencingRequest {
return GeofencingRequest.Builder().apply {
setInitialTrigger(initialTrigger)
addGeofence(geofence)
}.build()
}
@JvmStatic
private fun getGeofencePendingIndent(context: Context, callbackHandle: Long): PendingIntent {
val intent = Intent(context, GeofencingBroadcastReceiver::class.java)
.putExtra(CALLBACK_HANDLE_KEY, callbackHandle)
return PendingIntent.getBroadcast(context, 0, intent, PendingIntent.FLAG_UPDATE_CURRENT)
}
// TODO(bkonyi): Reregister geofences after reboot
// https://developer.android.com/training/location/geofencing
@JvmStatic
private fun registerGeofence(context: Context,
geofencingClient: GeofencingClient,
args: ArrayList<*>?,
result: Result?) {
val callbackHandle = args!![0] as Long
val id = args[1] as String
val lat = args[2] as Double
val long = args[3] as Double
val radius = (args[4] as Number).toFloat()
val fenceTriggers = args[5] as Int
val initialTriggers = args[6] as Int
val expirationDuration = (args[7] as Int).toLong()
val loiteringDelay = args[8] as Int
val notificationResponsiveness = args[9] as Int
val geofence = Geofence.Builder()
.setRequestId(id)
.setCircularRegion(lat, long, radius)
.setTransitionTypes(fenceTriggers)
.setLoiteringDelay(loiteringDelay)
.setNotificationResponsiveness(notificationResponsiveness)
.setExpirationDuration(expirationDuration)
.build()
// Ensure permissions are set properly.
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M &&
(context.checkSelfPermission(Manifest.permission.ACCESS_FINE_LOCATION)
== PackageManager.PERMISSION_DENIED)) {
val msg = "'registerGeofence' requires the ACCESS_FINE_LOCATION permission."
Log.w(TAG, msg)
result?.error(msg, null, null)
}
geofencingClient.addGeofences(getGeofencingRequest(geofence, initialTriggers),
getGeofencePendingIndent(context, callbackHandle))?.run {
addOnSuccessListener {
Log.i(TAG, "Successfully added geofence")
result?.success(true)
}
addOnFailureListener {
Log.e(TAG, "Failed to add geofence: $it")
result?.error(it.toString(), null, null)
}
}
}
Tem bastante coisa acontecendo aqui, então vamos detalhar:
-
Extrair os argumentos relevantes do
ArrayListenviado peloMethodChannel -
Criar uma instância de
Geofenceque descreve a localização e o tamanho da geofence, bem como seus vários parâmetros de disparo -
Antes de registrar a instância de
Geofence, fazer outra verificação para garantir que o aplicativo ainda tenha as permissões corretas do dispositivo para geofencing -
Por fim, um
GeofencingRequeste umPendingIntentsão criados e usados para registrar a geofence. OPendingIntenté usado para invocar oGeofencingBroadcastReceiverquando a geofence é disparada; ele contém o handle de callback associado a essa geofence.
Pronto! Neste ponto, o plugin consegue criar e registrar uma geofence. No entanto, o plugin ainda não está pronto para tratar eventos reais de geofence. Para isso, o plugin precisa poder ser acordado pelo sistema quando houver um evento de geofence a tratar.
Agendando o serviço de geofencing
Agora que o plugin pode registrar eventos de geofence, ele também precisa saber tratar os próprios eventos. Quando um geofence registrado pelo plugin é acionado, o Android inicia o app Flutter em segundo plano, cria uma instância de
GeofencingBroadcastReceiver, e invoca o método onReceive sobrescrito:
class GeofencingBroadcastReceiver: BroadcastReceiver() {
companion object {
private const val TAG = "GeofencingBroadcastReceiver"
}
override fun onReceive(context: Context, intent: Intent) {
FlutterMain.startInitialization(context)
FlutterMain.ensureInitializationComplete(context, null)
GeofencingService.enqueueWork(context, intent)
}
}
A implementação de onReceive é simples: ela garante que o framework Flutter esteja inicializado e então adiciona o
Intent do evento de geofencing à fila de trabalho de GeofencingService. Como
GeofencingService é uma implementação de JobIntentService, GeofencingService.enqueueWork
é apenas um wrapper em torno do método enqueueWork de JobIntentService, que cuida de agendar o trabalho para o serviço.
Tratando eventos de geofence
Em algum momento depois que um evento de geofence é adicionado à fila de trabalho, o Android acorda o app para invocar o método onHandleWork de GeofencingService. No entanto, antes que onHandleWork
possa ser chamado, uma instância de GeofencingService precisa ser criada e inicializada invocando
startGeofencingService a partir do método onCreate de GeofencingService.
private fun startGeofencingService(context: Context) {
// Synchronize on sServiceStarted to avoid multiple concurrent
// initializations.
synchronized(sServiceStarted) {
mContext = context
// If we don't have an existing background FlutterNativeView,
// we need to create one and have it initialize our callback
// dispatcher.
if (sBackgroundFlutterEngine == null) {
// Grab the callback handle for the callback dispatcher from
// storage.
val callbackHandle = context.getSharedPreferences(
GeofencingPlugin.SHARED_PREFERENCES_KEY,
Context.MODE_PRIVATE)
.getLong(GeofencingPlugin.CALLBACK_DISPATCHER_HANDLE_KEY, 0)
if (callbackHandle == 0L) {
Log.e(TAG, "Fatal: no callback registered")
return
}
// Retrieve the actual callback information needed to invoke it.
val callbackInfo = FlutterCallbackInformation.lookupCallbackInformation(callbackHandle)
if (callbackInfo == null) {
Log.e(TAG, "Fatal: failed to find callback")
return
}
// Create a FlutterEngine which will process the geofencing events.
sBackgroundFlutterEngine = FlutterEngine(context)
val args = DartCallback(
context.getAssets(),
FlutterMain.findAppBundlePath(context)!!,
callbackInfo
)
// Start running callback dispatcher code in our background FlutterEngine instance.
sBackgroundFlutterEngine!!.getDartExecutor().executeDartCallback(args)
}
}
// Create the MethodChannel used to communicate between the callback
// dispatcher and this GeofencingService instance.
mBackgroundChannel = MethodChannel(sBackgroundFlutterEngine!!.getDartExecutor().getBinaryMessenger(),
"plugins.flutter.io/geofencing_plugin_background")
mBackgroundChannel.setMethodCallHandler(this)
}
startGeofencingService é responsável por garantir que o plugin tenha uma instância FlutterEngine associada. Cada instância de FlutterEngine fornece acesso a um DartExecutor
que pode ser usado para executar código Dart em um novo isolate. Neste caso, a instância de FlutterEngine
tem a importante tarefa de inicializar o despachante de callbacks e executar os callbacks registrados no plugin.
Depois que startGeofencingService termina de executar, onHandleWork é chamado pelo sistema com o
Intent que foi enfileirado antes:
override fun onHandleWork(intent: Intent) {
// Retrieve the callback handle associated with the triggered geofence.
val callbackHandle = intent.
getLongExtra(GeofencingPlugin.CALLBACK_HANDLE_KEY, 0)
// Parse the GeofencingEvent from the Intent.
val geofencingEvent = GeofencingEvent.fromIntent(intent)
if (geofencingEvent.hasError()) {
Log.e(TAG, "Geofencing error: ${geofencingEvent.errorCode}")
return
}
// Get the geofence transition type (e.g., enter, dwell, exit).
val geofenceTransition = geofencingEvent.geofenceTransition
// Get the geofences that were triggered. A single event can trigger
// multiple geofences.
val triggeringGeofences = geofencingEvent.triggeringGeofences.map {
it.requestId
}
val location = geofencingEvent.triggeringLocation
val locationList = listOf(location.latitude,
location.longitude)
val geofenceUpdateList = listOf(callbackHandle,
triggeringGeofences,
locationList,
geofenceTransition)
synchronized(sServiceStarted) {
if (!sServiceStarted.get()) {
// Queue up geofencing events while background isolate is starting
queue.add(geofenceUpdateList)
} else {
// Callback method name is intentionally left blank.
mBackgroundChannel.invokeMethod("", geofenceUpdateList)
}
}
}
A maior parte do código acima monta a lista de argumentos enviada ao despachante de callbacks. No entanto, antes de passar os argumentos processados do evento de geofence para o despachante, o plugin precisa garantir que o despachante de callbacks já esteja escutando seu
MethodChannel. Para isso, o GeofencingService escuta uma mensagem do despachante de callbacks, que é enviada depois que o handler
MethodCall do despachante é definido:
override fun onMethodCall(call: MethodCall, result: Result) {
if (call.method == "GeofencingService.initialized") {
synchronized(sServiceStarted) {
// Dispatch any geofencing events that were handled before the
// callback dispatcher was ready.
while (!queue.isEmpty()) {
mBackgroundChannel.invokeMethod("", queue.remove())
}
sServiceStarted.set(true)
result.success(null)
}
} else {
result.notImplemented()
}
}
Neste ponto, o GeofencingService está totalmente inicializado, e quaisquer eventos de geofencing que ficaram na fila são enviados ao despachante de callbacks.
Execução em segundo plano: iOS (Objective-C)
Agora que a implementação do plugin de geofencing para Android está concluída, a mesma funcionalidade de geofencing precisa ser implementada para iOS.
Inicializando o plugin
Uma das primeiras tarefas executadas pela engine do Flutter na inicialização é registrar e inicializar todos os plugins usados pelo app. No iOS, isso envolve invocar o método estático
registerWithRegistrar definido para cada plugin. Para o plugin de geofencing, a inicialização envolve criar uma instância de
GeofencingPlugin e registrá-la como delegate do aplicativo, como mostrado no trecho de código abaixo. Isso permite que a engine do Flutter delegue o tratamento de certos eventos ao plugin.
+ (void)registerWithRegistrar:(NSObject<FlutterPluginRegistrar> *)registrar {
@synchronized(self) {
if (instance == nil) {
NSLog(@"Registering with registrar");
instance = [[GeofencingPlugin alloc] init:registrar];
[registrar addApplicationDelegate:instance];
}
}
}
Um estado adicional do plugin é definido quando a instância GeofencingPlugin é criada durante o registro do plugin:
- (instancetype)init:(NSObject<FlutterPluginRegistrar> *)registrar {
self = [super init];
NSAssert(self, @"super init cannot be nil");
// 1. Retrieve NSUserDefaults which will be used to store callback handles
// between launches.
_persistentState = [NSUserDefaults standardUserDefaults];
// 2. Initialize the location manager, and register as its delegate.
_locationManager = [[CLLocationManager alloc] init];
[_locationManager setDelegate:self];
[_locationManager requestAlwaysAuthorization];
_locationManager.allowsBackgroundLocationUpdates = YES;
// 3. Initialize the Dart runner which will be used to run the callback
// dispatcher.
_headlessRunner = [[FlutterEngine alloc]
initWithName:@"GeofencingIsolate"
project:nil
allowHeadlessExecution:YES];
_registrar = registrar;
// 4. Create the method channel used by the Dart interface to invoke
// methods and register to listen for method calls.
_mainChannel = [FlutterMethodChannel
methodChannelWithName:@"plugins.flutter.io/geofencing_plugin"
binaryMessenger:[registrar messenger]];
[registrar addMethodCallDelegate:self channel:_mainChannel];
// 5. Create a second method channel to be used to communicate with the
// callback dispatcher. This channel will be registered to listen for
// method calls once the callback dispatcher is started.
_callbackChannel =
[FlutterMethodChannel methodChannelWithName:@"plugins.flutter.io/geofencing_plugin_background"
binaryMessenger:_headlessRunner];
return self;
}
Iniciando o despachante de callbacks
Quando a inicialização do estado interno termina, o despachante de callbacks precisa ser iniciado invocando
startGeofencingService. Isso é feito quando o usuário chama GeofencingManager.initialize()
no app ou quando o app é iniciado para tratar um evento de geofence (mais sobre isso adiante).
- (void)startGeofencingService:(int64_t)handle {
NSLog(@"Initializing GeofencingService");
[self setCallbackDispatcherHandle:handle];
FlutterCallbackInformation *info = [FlutterCallbackCache lookupCallbackInformation:handle];
NSAssert(info != nil, @"failed to find callback");
NSString *entrypoint = info.callbackName;
NSString *uri = info.callbackLibraryPath;
[_headlessRunner runWithEntrypointAndLibraryUri:entrypoint libraryUri:uri];
NSAssert(registerPlugins != nil, @"failed to set registerPlugins");
// Once our headless runner has been started, we need to register the application's plugins
// with the runner in order for them to work on the background isolate. `registerPlugins` is
// a callback set from AppDelegate.m in the main application. This callback should register
// all relevant plugins (excluding those which require UI).
registerPlugins(_headlessRunner);
[_registrar addMethodCallDelegate:self channel:_callbackChannel];
}
Nota: o FlutterMethodChannel do despachante de callbacks só é registrado
depois que o runner headless é iniciado. Se houver uma tentativa de registrar o canal de método do despachante de callbacks antes disso, o app provavelmente vai travar.
Tratando chamadas de método
Assim como onMethodCall precisou ser implementado no Android para permitir que o plugin tratasse as requisições vindas da interface Dart e do despachante de callbacks, handleMethodCall precisa ser implementado:
- (void)handleMethodCall:(FlutterMethodCall *)call result:(FlutterResult)result {
NSArray *arguments = call.arguments;
if ([@"GeofencingPlugin.initializeService" isEqualToString:call.method]) {
NSAssert(arguments.count == 1,
@"Invalid argument count for 'GeofencingPlugin.initializeService'");
[self startGeofencingService:[arguments[0] longValue]];
result(@(YES));
} else if ([@"GeofencingService.initialized" isEqualToString:call.method]) {
// Ignored on iOS.
result(nil);
} else if ([@"GeofencingPlugin.registerGeofence" isEqualToString:call.method]) {
[self registerGeofence:arguments];
result(@(YES));
} else if ([@"GeofencingPlugin.removeGeofence" isEqualToString:call.method]) {
result(@([self removeGeofence:arguments]));
} else {
result(FlutterMethodNotImplemented);
}
}
Registrando geofences
Com a inicialização concluída, o plugin está pronto para registrar eventos de geofence. Quando quem usa o plugin solicita que um geofence seja configurado, registerGeofence é chamado:
- (void)registerGeofence:(NSArray *)arguments {
NSLog(@"RegisterGeofence: %@", arguments);
int64_t callbackHandle = [arguments[0] longLongValue];
NSString *identifier = arguments[1];
double latitude = [arguments[2] doubleValue];
double longitude = [arguments[3] doubleValue];
double radius = [arguments[4] doubleValue];
CLCircularRegion *region =
[[CLCircularRegion alloc] initWithCenter:CLLocationCoordinate2DMake(latitude, longitude)
radius:radius
identifier:identifier];
region.notifyOnEntry = YES;
region.notifyOnExit = YES;
[self setCallbackHandleForRegionId:callbackHandle regionId:identifier];
[self->_locationManager startMonitoringForRegion:region];
}
Esse método cria a região do geofence e usa o método
startMonitoringForRegion de CLLocationManager para registrar o geofence. Para manter o controle de qual callback está associado ao geofence recém-registrado, o handle do callback é mapeado para o identificador da região fornecido pelo usuário, que é salvo em disco usando
NSUserDefaults. Isso permite que o plugin busque o handle do callback quando um evento de geofence for recebido, mesmo que o app tenha sido fechado desde que o geofence foi registrado.
Tratando eventos de geofence
Quando o sistema determina que um geofence foi entrado ou saído, o CLLocationManager
invoca um dos métodos didEnterRegion ou didExitRegion. Nesse momento, o handle do callback do geofence acionado é recuperado do armazenamento e o despachante de callbacks é invocado:
- (void)sendLocationEvent:(CLRegion *)region eventType:(int)event {
NSAssert([region isKindOfClass:[CLCircularRegion class]], @"region must be CLCircularRegion");
CLLocationCoordinate2D center = region.center;
int64_t handle = [self getCallbackHandleForRegionId:region.identifier];
[_callbackChannel
invokeMethod:@""
arguments:@[
@(handle),
@[ region.identifier ],
@[ @(center.latitude), @(center.longitude) ],
@(event)
]
];
}
- (void)locationManager:(CLLocationManager *)manager didEnterRegion:(CLRegion *)region {
[self sendLocationEvent:region eventType:kEnterEvent];
}
- (void)locationManager:(CLLocationManager *)manager didExitRegion:(CLRegion *)region {
[self sendLocationEvent:region eventType:kExitEvent];
}
Eventos de geofence em estado suspenso
Se você já desenvolveu apps para Android e iOS, provavelmente sabe que o iOS é bem mais restritivo que o Android quando se trata de executar código em segundo plano. Em vez de iniciar serviços potencialmente longos para tratar eventos em segundo plano, o iOS permite que os apps registrem interesse em tipos específicos de evento que, quando recebidos, acordam o app e invocam os delegates relevantes. Como o protocolo
FlutterPlugin
permite que plugins sejam registrados como delegates, fica relativamente simples tratar qualquer evento de segundo plano fornecido pelo sistema.
No caso do geofencing, o plugin precisa implementar didFinishLaunchingWithOptions, que é invocado quando o app acabou de ser iniciado e está pronto para rodar. O parâmetro dicionário desse método vai conter
UIApplicationLaunchOptionsLocationKey se o app foi iniciado por causa de um evento de geofence.
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Check to see if we're being launched due to a location event.
if (launchOptions[UIApplicationLaunchOptionsLocationKey] != nil) {
// Restart the headless service.
[self startGeofencingService:[self getCallbackDispatcherHandle]];
}
// Note: if we return NO, this vetos the launch of the application.
return YES;
}
Se o app for iniciado como resultado de um geofence acionado, o despachante de callbacks do plugin ainda precisará ser inicializado chamando
startGeofencingService com o handle em cache do despachante de callbacks. Depois que esse método retorna, o location manager invoca o handler apropriado descrito na seção anterior para o evento de geofence.
Exemplo de uso: abrindo o portão da garagem com geofencing
Agora que o plugin de geofencing está totalmente implementado para Android e iOS, finalmente posso colocá-lo em bom uso: abrir automaticamente o portão da minha garagem enquanto pedalo em direção à minha casa!

Nos últimos meses, venho brincando com um Raspberry Pi e o pacote rpi_gpio do Dart para voltar a trabalhar com circuitos. Eu vinha pensando em criar um app Flutter que abrisse o portão da garagem há um bom tempo, então fez sentido que meu primeiro projeto de hardware usasse Dart e Flutter. Ao longo de alguns fins de semana, escrevi um serviço para controlar o portão da garagem, fiz uma pequena cirurgia para ligar um relé ao botão do abridor, instalei um sensor de proximidade para consultar o estado da porta e, por fim, escrevi um app simples em Flutter que funciona como controle remoto.
Depois de usar minha solução por algumas semanas, comecei a ficar incomodado. Embora fosse ótimo poder abrir a garagem com um app no celular, eu ainda precisava tirar o celular do bolso, abrir o app e então acionar a porta manualmente. Isso é especialmente chato para mim, já que leitores de impressão digital aparentemente não gostam de funcionar com suor, o que dificulta desbloquear o celular (não tenho carro e vou de bicicleta 15 km em cada trajeto, então as dificuldades com o leitor de impressão digital acontecem todo dia).
Por sorte, o Flutter agora tem um plugin de geofencing que consegue executar tarefas mesmo quando o app não está aberto, inclusive abrir o portão da minha garagem!
Configurando as permissões corretas
A primeira coisa que vou fazer é garantir que meu app tenha as permissões certas para usar o plugin de geofencing.
Permissões: Android
Para que o plugin de geofencing funcione em segundo plano, GeofencingBroadcastReceiver
e GeofencingService precisam ser registrados no AndroidManifest.xml:
<receiver android:name="io.flutter.plugins.geofencing.GeofencingBroadcastReceiver"
android:enabled="true" android:exported="true"/>
<service android:name="io.flutter.plugins.geofencing.GeofencingService"
android:permission="android.permission.BIND_JOB_SERVICE" android:exported="true"/>
O geofencing no Android também exige que as permissões ACCESS_FINE_LOCATION e ACCESS_BACKGROUND_LOCATION
(Android 10+) sejam solicitadas no AndroidManifest.xml:
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_BACKGROUND_LOCATION"/>
Permissões: iOS
Solicitar as permissões relevantes no iOS exige algumas modificações simples em Info.plist
no diretório ios do app. Primeiro, adicione as seguintes linhas para solicitar atualizações de localização em segundo plano:
<dict>
<!-- ... -->
<key>UIRequiredDeviceCapabilities</key>
<array>
<string>location-services</string>
<string>gps</string>
<string>armv7</string>
</array>
<key>UIBackgroundModes</key>
<array>
<string>location</string>
</array>
<!-- ... -->
</dict>
Depois, defina as mensagens de descrição de NSLocation:
<dict>
<!-- ... -->
<key>NSLocationAlwaysAndWhenInUseUsageDescription</key>
<string>YOUR DESCRIPTION HERE</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>YOUR DESCRIPTION HERE</string>
<!-- ... -->
</dict>
Essas descrições são mostradas ao usuário quando o app solicita acesso à localização dele. Se elas não forem fornecidas, o registro do geofence falha silenciosamente!
#include "AppDelegate.h"
#include "GeneratedPluginRegistrant.h"
// Add the import for the GeofencingPlugin.
#import <geofencing/GeofencingPlugin.h>
void registerPlugins(NSObject<FlutterPluginRegistry>* registry) {
[GeneratedPluginRegistrant registerWithRegistry:registry];
}
@implementation AppDelegate
- (BOOL)application:(UIApplication *)application
didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {
// Register the plugins with the AppDelegate
registerPlugins(self);
// Set registerPlugins as a callback within GeofencingPlugin. This allows
// for the Geofencing plugin to register the plugins with the background
// FlutterEngine instance created to handle events. If this step is skipped,
// other plugins will not work in the geofencing callbacks!
[GeofencingPlugin setPluginRegistrantCallback:registerPlugins];
// Override point for customization after application launch.
return [super application:application didFinishLaunchingWithOptions:launchOptions];
}
@end
Por fim, de forma semelhante ao que foi feito no Android, defina uma referência ao registrant de plugins do app dentro de
GeofencingPlugin no AppDelegate do app. Isso é necessário para registrar os plugins do app no isolate em segundo plano do plugin de geofencing, o que torna possível usar outros plugins no contexto desse isolate.
Juntando tudo
Agora que as permissões necessárias para o geofencing estão configuradas corretamente, resta apenas conectar o plugin ao app de controle remoto do portão da garagem.
Antes de tudo, o plugin precisa ser inicializado. Isso é feito em um método chamado initialize, que é invocado quando o app inicia:
Future<void> initialize() async {
// Perform other initialization
// …
// Initialize the geofencing plugin.
await GeofencingManager.initialize();
}
Em seguida, deve haver alguma forma de alternar se o portão da garagem deve abrir quando o geofence for entrado. Isso pode ser feito com um simples Switch exibido na parte inferior do app:
Widget _proximityTriggerToggle() => Container(
padding: const EdgeInsets.fromLTRB(26.0, 2.5, 26.0, 2.5),
child: Row(
mainAxisAlignment: MainAxisAlignment.spaceBetween,
children: <Widget>[
const Text('Proximity Trigger',
style: TextStyle(fontWeight: FontWeight.bold, fontSize: 16.0)),
Switch(
value: _proximityTriggerEnabled,
onChanged: (bool state) async {
setState(() {
_proximityTriggerEnabled = state;
});
if (state) {
await GeofencingManager.registerGeofence(
GeofenceTrigger.homeRegion,
GeofenceTrigger.homeGeofenceCallback);
} else {
await GeofencingManager.removeGeofence(
GeofenceTrigger.homeRegion);
}
},
),
],
)
);
Dependendo do estado desse Switch, o app registra um geofence com o callback usado para abrir o portão da garagem ou remove o geofence.
Por fim, a região do geofence ao redor da minha casa e seu callback correspondente são definidos em GeofenceTrigger:
abstract class GeofenceTrigger {
static final _androidSettings = AndroidGeofencingSettings(
initialTrigger: [GeofenceEvent.exit],
notificationResponsiveness: 0,
loiteringDelay: 0);
static bool _isInitialized = false;
static final homeRegion = GeofenceRegion(
'home', HOME_LAT, HOME_LONG, 300.0, <GeofenceEvent>[GeofenceEvent.enter],
androidSettings: _androidSettings);
static Future<void> homeGeofenceCallback(
List<String> id, Location location, GeofenceEvent event) async {
// Check to see if this is the first time the callback is being called.
if (!_isInitialized) {
// Re-initialize state required to communicate with the garage door
// server.
await initialize();
_isInitialized = true;
}
if (event == GeofenceEvent.enter) {
await GarageDoorRemote.openDoor();
}
}
}
Para os meus testes iniciais, criei um GeofenceRegion com raio de 300 m ao redor da minha casa, que será acionado em algum momento depois que eu entrar na área. Quando o geofence for entrado, o homeGeofenceCallback é invocado, verificações são feitas para garantir que o app consegue se comunicar com o servidor do portão, e então uma requisição para abrir a porta é enviada. Depois que confirmei que a lógica dentro do callback realmente fez o portão abrir, usando um app de terceiros para simular minha localização e meus movimentos, chegou a hora de fazer testes no mundo real, na minha bicicleta!
Depois de algumas idas e vindas pela rua, ficou evidente que, embora os geofences sejam acionados quase imediatamente ao usar uma localização simulada, o Android não garante quando um evento de geofence será entregue. Infelizmente, isso significa que pode levar minutos até que meu controle remoto do portão seja notificado de que entrei na região do geofence ao redor da minha casa. Com um raio tão pequeno quanto 300 m, muitas vezes eu ficava esperando um ou dois minutos para a porta abrir sozinha.
A solução temporária foi aumentar o raio da região do geofence para 1 km, o que parece funcionar bem o suficiente por enquanto. Obviamente, essa abordagem tem alguns problemas, mas pretendo refinar a lógica de acionamento por proximidade para usar um geofence maior que inicie atualizações de localização com mais frequência. Essas atualizações serão então usadas para determinar manualmente se estou dentro de um certo raio da minha casa, momento em que a requisição para abrir a porta será enviada.
Conclusão
Se você chegou até aqui, agora já deve ter todo o conhecimento necessário para criar um plugin Flutter que executa código Dart em segundo plano! Claro, neste artigo eu só arranhei a superfície do desenvolvimento de plugins para Flutter, mas recomendo muito a documentação sobre desenvolvimento de pacotes e plugins, bem como o passo a passo sobre como escrever código específico de plataforma com platform channels. Se quiser um olhar mais profundo sobre como o plugin de geofencing é implementado, o código-fonte completo está no repositório FlutterGeofencing no GitHub. Também linkei toda a documentação adicional, plugins de exemplo e projetos mencionados ao longo do artigo na seção Recursos abaixo.
Me diverti muito implementando o suporte a execução em segundo plano para Flutter, e ainda mais criando o plugin de geofencing para este artigo. (Foi uma ótima desculpa para trabalhar em um projeto pessoal como parte do meu trabalho!) Se você se sentir inclinado, siga-me no GitHub para acompanhar meu trabalho com Flutter e com a máquina virtual Dart, além dos meus outros projetos pessoais.
Obrigado pela leitura e feliz Fluttering!
Recursos
Documentação do Dart:
-
PluginUtilities: contém métodos para lidar com CallbackHandles
-
IsolateNameServer: estabelece comunicação entre isolates em primeiro e segundo plano usando SendPorts nomeados
Documentação do Android:
-
FlutterCallbackInformation: consulta as informações de callback necessárias para iniciar um isolate em segundo plano usando handles de callback
Documentação do iOS:
-
FlutterEngine: permite criar um isolate em segundo plano
-
FlutterCallbackCache: consulta as informações de callback necessárias para iniciar um isolate em segundo plano usando handles de callback
Plugins de exemplo:
-
FlutterGeofencing: o plugin de geofencing criado para este artigo
-
android_alarm_manager: um plugin de AlarmManager para Flutter
-
background_location: plugin para escutar mudanças significativas de localização no Android e no iOS
Projetos referenciados:
-
rpi_gpio: pacote para acessar os pinos GPIO do Raspberry Pi.
-
FlutterGarageDoorOpener: controle remoto de portão de garagem feito com Flutter
-
GarageDoorController: a biblioteca e o serviço de controle do portão da garagem