Platform Channels no Flutter

"Interface bonita. Mas como o Flutter lida com APIs específicas de plataforma?"

O Flutter convida você a escrever seu app mobile na linguagem Dart e a compilar para Android e iOS. Mas o Dart não compila para o bytecode Dalvik do Android, nem você tem bindings Dart/Objective-C no iOS. Isso significa que seu código Dart é escrito sem acesso direto às APIs específicas de plataforma do iOS Cocoa Touch e do Android SDK.

Isso não é um grande problema enquanto você estiver apenas escrevendo Dart para pintar pixels na tela. O framework Flutter e sua engine gráfica subjacente são bem capazes disso por conta própria. Também não é problema se tudo que você faz além de pintar pixels é I/O de arquivos ou rede e a lógica de negócio associada. A linguagem Dart, o runtime e as bibliotecas cuidam disso.

Mas apps não triviais exigem integração mais profunda com a plataforma hospedeira:

  • notificações, ciclo de vida do app, deep links, …

  • sensores, câmera, bateria, geolocalização, som, conectividade, …

  • compartilhamento de informações com outros apps, abertura de outros apps, …

  • preferências persistidas, pastas especiais, informações do dispositivo, …

A lista é longa e ampla, e parece crescer a cada nova versão da plataforma.

Todas essas APIs de plataforma poderiam ser embutidas no próprio framework Flutter. Mas isso faria o Flutter ficar muito maior e ter muito mais motivos para mudar. Na prática, isso provavelmente levaria o Flutter a ficar atrás da versão mais recente da plataforma. Ou deixaria os autores de apps com empacotamentos de APIs de plataforma “menor denominador comum” insatisfatórios. Ou confundiria os recém-chegados com abstrações complicadas para esconder as diferenças entre plataformas. Ou fragmentação de versões. Ou bugs.

Pensando bem, provavelmente todas as opções acima.

A equipe do Flutter escolheu uma abordagem diferente. Ela não faz muita coisa, mas é simples, versátil e totalmente nas suas mãos.

Em primeiro lugar, o Flutter é hospedado por um app Android ou iOS ao redor. As partes Flutter do app ficam envolvidas em componentes padrão específicos de cada plataforma, como View no Android e UIViewController no iOS. Então, embora o Flutter convide você a escrever seu app em Dart, você pode fazer tanto ou tão pouco em Java/Kotlin ou Objective-C/Swift no app hospedeiro quanto quiser, trabalhando diretamente sobre as APIs específicas de cada plataforma.

Em segundo lugar, canais de plataforma oferecem um mecanismo simples de comunicação entre seu código Dart e o código específico da plataforma do seu app hospedeiro. Isso significa que você pode expor um serviço de plataforma no código do app hospedeiro e fazer com que ele seja invocado pelo lado Dart. Ou vice-versa.

E em terceiro lugar, plugins tornam possível criar uma API Dart apoiada por uma implementação Android escrita em Java ou Kotlin e uma implementação iOS escrita em Objective-C ou Swift, e empacotar isso como um trio Flutter/Android/iOS unido por canais de plataforma. Isso significa que você pode reutilizar, compartilhar e distribuir sua visão sobre como o Flutter deve usar uma API de plataforma específica.

Este artigo é uma introdução aprofundada aos canais de plataforma. Começando pelos fundamentos de mensagens do Flutter, vou apresentar os conceitos de canais de mensagem, método e evento, e discutir algumas considerações de design de API. Não haverá listagens de API, mas sim pequenos exemplos de código para copiar e reutilizar. Uma breve lista de diretrizes de uso é fornecida, com base na minha experiência contribuindo para o repositório flutter/plugins no GitHub como membro da equipe do Flutter. O artigo termina com uma lista de recursos adicionais, incluindo links para as referências de API DartDoc/JavaDoc/ObjcDoc.

API de canais de plataforma

Para a maioria dos casos de uso, você provavelmente usaria canais de método para a comunicação com a plataforma. Mas, como muitas de suas propriedades derivam dos canais de mensagem mais simples canais de mensagem e das bases de mensagens binárias, vou começar por aí.

Fundamentos: mensagens binárias assíncronas

No nível mais básico, o Flutter se comunica com o código da plataforma usando troca de mensagens assíncrona com mensagens binárias, ou seja, o payload da mensagem é um buffer de bytes. Para distinguir mensagens usadas com finalidades diferentes, cada mensagem é enviada em um “canal” lógico, que é apenas uma string com o nome. Os exemplos abaixo usam o nome de canal foo.

dart
// Send a binary message from Dart to the platform.
​
final WriteBuffer buffer = WriteBuffer()
  ..putFloat64(3.1415)
  ..putInt32(12345678);
final ByteData message = buffer.done();
await BinaryMessages.send('foo', message);
print('Message sent, reply ignored');

No Android, essa mensagem pode ser recebida, como um java.nio.ByteBuffer, com o seguinte código Kotlin:

kotlin
// Receive binary messages from Dart on Android.
// This code can be added to a FlutterActivity subclass, typically
// in onCreate.
​
flutterView.setMessageHandler("foo") { message, reply ->
  message.order(ByteOrder.nativeOrder())
  val x = message.double
  val n = message.int
  Log.i("MSG", "Received: $x and $n")
  reply.reply(null)
}

A API ByteBuffer oferece suporte à leitura de valores primitivos avançando automaticamente a posição de leitura atual. A história no iOS é parecida; sugestões para melhorar meu Swift, que ainda é fraco, são muito bem-vindas:

swift
// Receive binary messages from Dart on iOS.
// This code can be added to a FlutterAppDelegate subclass,
// typically in application:didFinishLaunchingWithOptions:.
​
let flutterView =
  window?.rootViewController as! FlutterViewController;
flutterView.setMessageHandlerOnChannel("foo") {
  (message: Data!, reply: FlutterBinaryReply) -> Void in
  let x : Float64 = message.subdata(in: 0..<8)
    .withUnsafeBytes { $0.pointee }
  let n : Int32 = message.subdata(in: 8..<12)
    .withUnsafeBytes { $0.pointee }
  os_log("Received %f and %d", x, n)
  reply(nil)
}

A comunicação é bidirecional, então você também pode enviar mensagens na direção oposta, de Java/Kotlin ou Objective-C/Swift para o Dart. Invertendo a direção da configuração acima, fica assim:

Envie uma mensagem binária a partir do Android:

kotlin
val message = ByteBuffer.allocateDirect(12)
message.putDouble(3.1415)
message.putInt(123456789)
flutterView.send("foo", message) { _ ->
  Log.i("MSG", "Message sent, reply ignored")
}

Envie uma mensagem binária a partir do iOS:

swift
var message = Data(capacity: 12)
var x: Float64 = 3.1415
var n: Int32 = 12345678
message.append(UnsafeBufferPointer(start: &x, count: 1))
message.append(UnsafeBufferPointer(start: &n, count: 1))
flutterView.send(onChannel: "foo", message: message) {(_) -> Void in
  os_log("Message sent, reply ignored")
}

Receba mensagens binárias da plataforma no Dart:

dart
BinaryMessages.setMessageHandler('foo', (ByteData message) async {
  final ReadBuffer readBuffer = ReadBuffer(message);
  final double x = readBuffer.getFloat64();
  final int n = readBuffer.getInt32();
  print('Received $x and $n');
  return null;
});

Letra miúda. Respostas obrigatórias. Cada envio de mensagem envolve uma resposta assíncrona do receptor. Nos exemplos acima, não há valor interessante para comunicar de volta, mas a resposta nula é necessária para que o future do Dart seja concluído e para que os dois callbacks da plataforma sejam executados.

Threads. Mensagens e respostas são recebidas, e precisam ser enviadas, na thread principal de UI da plataforma. No Dart há apenas uma thread por isolate, ou seja, por view do Flutter, então não há confusão sobre qual thread usar aqui.

Exceções. Qualquer exceção não capturada lançada em um handler de mensagem do Dart ou do Android é capturada pelo framework, registrada no log, e uma resposta nula é enviada de volta ao remetente. Exceções não capturadas lançadas em handlers de resposta são registradas no log.

Tempo de vida do handler. Handlers de mensagem registrados são mantidos vivos junto com a view do Flutter (ou seja, o isolate do Dart, a instância FlutterView do Android e o FlutterViewController do iOS). Você pode encurtar a vida de um handler desregistrando-o: basta definir um handler nulo (ou diferente) usando o mesmo nome de canal.

Unicidade do handler. Os handlers ficam em um mapa hash indexado pelo nome do canal, então pode haver no máximo um handler por canal. Uma mensagem enviada em um canal para o qual nenhum handler de mensagem está registrado do lado receptor recebe uma resposta automática nula.

Comunicação síncrona. A comunicação com a plataforma está disponível apenas no modo assíncrono. Isso evita fazer chamadas bloqueantes entre threads e os problemas em nível de sistema que isso pode acarretar (desempenho ruim, risco de deadlocks). Até a data desta escrita, não está totalmente claro se a comunicação síncrona é realmente necessária no Flutter e, se for, em que forma.

Trabalhando no nível de mensagens binárias, você precisa se preocupar com detalhes delicados como endianness e como representar mensagens de nível mais alto, como strings ou maps, usando bytes. Você também precisa especificar o nome de canal correto sempre que quiser enviar uma mensagem ou registrar um handler. Para facilitar isso, temos os canais de plataforma:

Um canal de plataforma é um objeto que reúne um nome de canal e um codec para serializar/desserializar mensagens para a forma binária e de volta.

Canais de mensagens: nome + codec

Suponha que você queira enviar e receber mensagens de texto em vez de buffers de bytes. Isso pode ser feito usando um canal de mensagens, um tipo simples de canal de plataforma, construído com um codec de string. O código abaixo mostra como usar canais de mensagens nos dois sentidos entre Dart, Android e iOS.

No lado do Dart:

dart
const channel = BasicMessageChannel<String>('foo', StringCodec());
​
// Send message to platform and receive reply.
final String reply = await channel.send('Hello, world');
print(reply);
​
// Receive messages from platform and send replies.
channel.setMessageHandler((String message) async {
  print('Received: $message');
  return 'Hi from Dart';
});

No lado do Android:

kotlin
val channel = BasicMessageChannel<String>(
  flutterView, "foo", StringCodec.INSTANCE)
​
// Send message to Dart and receive reply.
channel.send("Hello, world") { reply ->
  Log.i("MSG", reply)
}
​
// Receive messages from Dart and send replies.
channel.setMessageHandler { message, reply ->
  Log.i("MSG", "Received: $message")
  reply.reply("Hi from Android")
}

No lado do iOS:

swift
let channel = FlutterBasicMessageChannel(
    name: "foo",
    binaryMessenger: controller,
    codec: FlutterStringCodec.sharedInstance())
​
// Send message to Dart and receive reply.
channel.sendMessage("Hello, world") {(reply: Any?) -> Void in
  os_log("%@", type: .info, reply as! String)
}
​
// Receive messages from Dart and send replies.
channel.setMessageHandler {
  (message: Any?, reply: FlutterReply) -> Void in
  os_log("Received: %@", type: .info, message as! String)
  reply("Hi from iOS")
}

O nome do canal é especificado somente na construção do canal. Depois disso, as chamadas para enviar uma mensagem ou definir um handler de mensagem podem ser feitas sem repetir o nome do canal. Mais importante ainda, deixamos para a classe do codec de string lidar com a forma de interpretar buffers de bytes como strings e vice-versa.

Essas são vantagens nobres, sem dúvida, mas você provavelmente concordaria que BasicMessageChannel não faz muita coisa. O que é intencional. O código Dart acima é equivalente ao seguinte uso das bases de mensagens binárias:

dart
const codec = StringCodec();
​
// Send message to platform and receive reply.
final String reply = codec.decodeMessage(
  await BinaryMessages.send(
    'foo',
    codec.encodeMessage('Hello, world'),
  ),
);
print(reply);
​
// Receive messages from platform and send replies.
BinaryMessages.setMessageHandler('foo', (ByteData message) async {
  print('Received: ${codec.decodeMessage(message)}');
  return codec.encodeMessage('Hi from Dart');
});

Essa observação se aplica às implementações de Android e iOS dos canais de mensagens também. Não há mágica envolvida:

  • Canais de mensagens delegam toda a comunicação para a camada de mensagens binárias.

  • Canais de mensagens não mantêm o controle dos handlers registrados por conta própria.

  • Canais de mensagens são leves e sem estado.

  • Duas instâncias de canal de mensagens criadas com o mesmo nome de canal e codec são equivalentes (e interferem na comunicação uma da outra).

Por razões históricas diversas, o framework Flutter define quatro codecs de mensagem diferentes:

  • StringCodec Codifica strings usando UTF-8. Como acabamos de ver, canais de mensagens com esse codec têm o tipo BasicMessageChannel<String> no Dart.

  • BinaryCodec Implementa o mapeamento identidade sobre buffers de bytes; esse codec permite aproveitar a conveniência dos objetos de canal nos casos em que você não precisa de codificação/decodificação. Canais de mensagens Dart com esse codec têm o tipo BasicMessageChannel<ByteData>.

  • JSONMessageCodec Trabalha com valores “parecidos com JSON” (strings, números, booleanos, null, listas desses valores e maps com chaves string desses valores). Listas e maps são heterogêneos e podem ser aninhados. Durante a codificação, os valores são convertidos em strings JSON e depois em bytes usando UTF-8. Canais de mensagens Dart têm o tipo BasicMessageChannel<dynamic> com esse codec.

  • StandardMessageCodec Trabalha com valores um pouco mais generalizados do que o codec JSON, suportando também buffers de dados homogêneos (UInt8List, Int32List, Int64List, Float64List) e maps com chaves que não são strings. O tratamento de números difere do JSON: ints do Dart chegam à plataforma como inteiros com sinal de 32 ou 64 bits, dependendo da magnitude — nunca como números de ponto flutuante. Os valores são codificados em um formato binário personalizado, razoavelmente compacto e extensível. O codec padrão foi projetado para ser a escolha padrão para comunicação de canais no Flutter. Assim como no JSON, canais de mensagens Dart construídos com o codec padrão têm o tipo BasicMessageChannel<dynamic>.

Como você deve ter imaginado, canais de mensagens funcionam com qualquer implementação de codec de mensagem que satisfaça um contrato simples. Isso permite que você plugue seu próprio codec, se precisar. Você terá que implementar codificação e decodificação compatíveis em Dart, Java/Kotlin e Objective-C/Swift.

Letra miúda. Evolução do codec. Cada codec de mensagem está disponível em Dart, como parte do framework Flutter, bem como nas duas plataformas, como parte das bibliotecas expostas pelo Flutter ao seu código Java/Kotlin ou Objective-C/Swift. O Flutter usa os codecs somente para comunicação intra-app, não como formato de persistência. Isso significa que a forma binária das mensagens pode mudar de uma versão do Flutter para a próxima, sem aviso. Claro, as implementações de codec em Dart, Android e iOS evoluem juntas, para garantir que o que é codificado pelo remetente possa ser decodificado com sucesso pelo receptor, nos dois sentidos.

Mensagens nulas. Qualquer codec de mensagem deve suportar e preservar mensagens nulas, já que essa é a resposta padrão a uma mensagem enviada em um canal para o qual nenhum handler de mensagem foi registrado do lado receptor.

Tipagem estática de mensagens no Dart. Um canal de mensagens configurado com o codec de mensagem padrão dá o tipo dynamic às mensagens e respostas. Você frequentemente deixaria explícitas suas expectativas de tipo atribuindo a uma variável tipada:

dart
final String reply1 = await channel.send(msg1);
final int reply2 = await channel.send(msg2);

Mas há uma ressalva ao lidar com respostas que envolvem parâmetros de tipo genéricos:

dart
final List<String> reply3 = await channel.send(msg3);      // Fails.
final List<dynamic> reply3 = await channel.send(msg3);     // Works.

A primeira linha falha em tempo de execução, a menos que a resposta seja null. O codec de mensagens padrão foi escrito para listas e mapas heterogêneos. No lado Dart, esses valores têm tipos de tempo de execução List<dynamic> e Map<dynamic, dynamic>, e o Dart 2 impede que esses valores sejam atribuídos a variáveis com argumentos de tipo mais específicos. Essa situação é parecida com a desserialização de JSON no Dart, que produz List<dynamic> e Map<String, dynamic> — assim como o codec de mensagens JSON.

Futures podem causar problemas parecidos:

dart
Future<String> greet() => channel.send('hello, world');    // Fails.
Future<String> greet() async {                             // Works.
  final String reply = await channel.send('hello, world');
  return reply;
}

O primeiro método falha em tempo de execução, mesmo que a resposta recebida seja uma string. A implementação do canal cria um Future<dynamic> independentemente do tipo da resposta, e esse objeto não pode ser atribuído a um Future<String>.

Por que o “basic“ em BasicMessageChannel? Os canais de mensagem parecem ser usados apenas em situações bem restritas, em que você comunica algum tipo de fluxo homogêneo de eventos num contexto implícito. Tipo eventos de teclado, talvez. Na maioria das aplicações de canais de plataforma, você vai precisar comunicar não só valores, mas também o que quer que aconteça com cada valor, ou como ele deve ser interpretado pelo receptor. Uma forma de fazer isso é fazer a mensagem representar uma chamada de método com o valor como argumento. Então você vai querer uma forma padrão de separar o nome do método do argumento na mensagem. E também vai querer uma forma padrão de distinguir respostas de sucesso e de erro. É isso que os canais de método fazem por você. Agora, BasicMessageChannel foi originalmente chamado de MessageChannel, mas foi renomeado para evitar confusão entre MessageChannel e MethodChannel no código. Por ser mais geral, os canais de método ficaram com o nome mais curto.

Canais de método: envelopes padronizados

Canais de método são canais de plataforma projetados para invocar trechos de código nomeados entre Dart e Java/Kotlin ou Objective-C/Swift. Eles usam “envelopes” de mensagem padronizados para transmitir o nome do método e os argumentos do remetente para o receptor, e para distinguir resultados de sucesso e de erro na resposta associada. Os envelopes e o payload suportado são definidos por classes de codec de método separadas, de forma parecida com a maneira como os canais de mensagem usam codecs de mensagem.

Isso é tudo o que os canais de método fazem: combinam um nome de canal com um codec.

Em particular, nenhuma suposição é feita sobre qual código é executado ao receber uma mensagem num canal de método. Mesmo que a mensagem represente uma chamada de método, você não precisa invocar um método. Você pode simplesmente fazer um switch no nome do método e executar algumas linhas de código para cada caso.

Observação. Essa falta de vínculo implícito ou automatizado com métodos e seus parâmetros pode decepcionar você. Tudo bem, a decepção pode ser produtiva. Imagino que dá para construir essa solução do zero usando processamento de anotações e geração de código, ou talvez reaproveitar partes de um framework RPC existente. O Flutter é open source, fique à vontade para contribuir! Canais de método estão disponíveis como alvo para a sua geração de código, se servirem. Enquanto isso, eles são úteis por conta própria no “modo artesanal”.

Os canais de método foram a resposta da equipe do Flutter ao desafio de definir uma API de comunicação funcional para uso pelo ecossistema de plugins, que na época ainda não existia. Queríamos algo que autores de plugins pudessem começar a usar logo, sem muito boilerplate ou configuração de build complicada. Acho que o conceito de canal de método é uma resposta razoável, mas eu ficaria surpreso se ele continuasse sendo a única resposta.

Veja como você usaria um canal de método no caso simples de invocar um pouco de código de plataforma a partir do Dart. O código está associado ao nome bar, que não é um nome de método neste caso, mas poderia ser. Tudo o que ele faz é construir uma string de saudação e devolvê-la ao chamador, então podemos codificar isso com a suposição razoável de que a invocação de plataforma não vai falhar (vamos ver o tratamento de erros mais adiante).

No lado do Dart:

dart
// A basic example of invoking platform methods.
const channel = MethodChannel('foo');
final String greeting = await channel.invokeMethod('bar', 'world');
print(greeting);

No lado do Android:

kotlin
val channel = MethodChannel(flutterView, "foo")
channel.setMethodCallHandler { call, result ->
  when (call.method) {
    "bar" -> result.success("Hello, ${call.arguments}")
    else -> result.notImplemented()
  }
}

No lado do iOS:

swift
let channel = FlutterMethodChannel(
  name: "foo", binaryMessenger: flutterView)
channel.setMethodCallHandler {
  (call: FlutterMethodCall, result: FlutterResult) -> Void in
  switch (call.method) {
  case "bar": result("Hello, \(call.arguments as! String)")
  default: result(FlutterMethodNotImplemented)
  }
}

Adicionando cases ao construto switch, podemos estender facilmente o exemplo acima para tratar múltiplos métodos. A cláusula default trata a situação em que um método desconhecido é chamado (provavelmente por erro de programação).

O código Dart acima é equivalente ao seguinte:

dart
const codec = StandardMethodCodec();
​
final ByteData reply = await BinaryMessages.send(
  'foo',
  codec.encodeMethodCall(MethodCall('bar', 'world')),
);
if (reply == null) {
  throw MissingPluginException();
} else {
  print(codec.decodeEnvelope(reply));
}

As implementações de canais de método para Android e iOS são, de forma parecida, wrappers finos em torno das chamadas às bases de mensagem binária. Uma resposta null é usada para representar um resultado de “não implementado”. Isso faz com que o comportamento do lado receptor seja indiferente a se a invocação caiu na cláusula default do switch ou se nenhum handler de chamada de método foi registrado no canal.

O valor do argumento no exemplo é a string única world. Mas o codec de método padrão, batizado de “codec de método padrão”, usa por baixo dos panos o codec de mensagem para codificar os valores do payload. Isso significa que os valores “gerais, semelhantes a JSON” descritos antes são todos suportados como argumentos de método e como resultados (de sucesso). Em particular, listas heterogêneas suportam múltiplos argumentos, enquanto mapas heterogêneos suportam argumentos nomeados. O valor padrão dos argumentos é null. Alguns exemplos:

dart
await channel.invokeMethod('bar');
await channel.invokeMethod('bar', <dynamic>['world', 42, pi]);
await channel.invokeMethod('bar', <String, dynamic>{
  name: 'world',
  answer: 42,
  math: pi,
}));

O SDK do Flutter inclui dois codecs de método:

  • StandardMethodCodec que por padrão delega a codificação dos valores do payload para StandardMessageCodec. Como este último é extensível, o primeiro também é.

  • JSONMethodCodec que delega a codificação dos valores do payload para JSONMessageCodec.

Você pode configurar canais de método com qualquer codec de método, incluindo codecs customizados. Para entender completamente o que envolve implementar um codec, vamos ver como os erros são tratados no nível da API do canal de método, estendendo o exemplo acima com um método baz que pode falhar.

No lado do Dart:

dart
const channel = MethodChannel('foo');
​
// Invoke a platform method.
const name = 'bar'; // or 'baz', or 'unknown'
const value = 'world';
try {
  print(await channel.invokeMethod(name, value));
} on PlatformException catch(e) {
  print('$name failed: ${e.message}');
} on MissingPluginException {
  print('$name not implemented');
}
​
// Receive method invocations from platform and return results.
channel.setMethodCallHandler((MethodCall call) async {
  switch (call.method) {
    case 'bar':
      return 'Hello, ${call.arguments}';
    case 'baz':
      throw PlatformException(code: '400', message: 'This is bad');
    default:
      throw MissingPluginException();
  }
});

No lado do Android:

kotlin
val channel = MethodChannel(flutterView, "foo")
​
// Invoke a Dart method.
val name = "bar" // or "baz", or "unknown"
val value = "world"
channel.invokeMethod(name, value, object: MethodChannel.Result {
  override fun success(result: Any?) {
    Log.i("MSG", "$result")
  }
  override fun error(code: String?, msg: String?, details: Any?) {
    Log.e("MSG", "$name failed: $msg")
  }
  override fun notImplemented() {
    Log.e("MSG", "$name not implemented")
  }
})
​
// Receive method invocations from Dart and return results.
channel.setMethodCallHandler { call, result ->
  when (call.method) {
    "bar" -> result.success("Hello, ${call.arguments}")
    "baz" -> result.error("400", "This is bad", null)
    else -> result.notImplemented()
  }
}

No lado do iOS:

swift
let channel = FlutterMethodChannel(
  name: "foo", binaryMessenger: flutterView)
​
// Invoke a Dart method.
let name = "bar" // or "baz", or "unknown"
let value = "world"
channel.invokeMethod(name, arguments: value) {
  (result: Any?) -> Void in
  if let error = result as? FlutterError {
    os_log("%@ failed: %@", type: .error, name, error.message!)
  } else if FlutterMethodNotImplemented.isEqual(result) {
    os_log("%@ not implemented", type: .error, name)
  } else {
    os_log("%@", type: .info, result as! NSObject)
  }
}
​
// Receive method invocations from Dart and return results.
channel.setMethodCallHandler {
  (call: FlutterMethodCall, result: FlutterResult) -> Void in
  switch (call.method) {
  case "bar": result("Hello, \(call.arguments as! String)")
  case "baz": result(FlutterError(
    code: "400", message: "This is bad", details: nil))
  default: result(FlutterMethodNotImplemented)
}

Erros são triplas (código, mensagem, detalhes), em que código e mensagem são strings. A mensagem é feita para consumo humano, o código para, bem, código. Os detalhes do erro são algum valor customizado, muitas vezes null, restrito apenas pelos tipos de valor que o codec suporta.

As letras miúdas. Exceções. Qualquer exceção não tratada lançada num método de chamada em Dart ou Android é capturada pela implementação do canal, registrada em log, e um resultado de erro é devolvido ao chamador. Exceções não tratadas lançadas em handlers de resultado também são registradas em log.

Codificação de envelopes. Como um codec de método codifica seus envelopes é um detalhe de implementação, assim como a forma como os codecs de mensagem convertem mensagens em bytes. Como exemplo, um codec de método poderia usar listas: chamadas de método podem ser codificadas como listas de dois elementos [nome do método, argumentos]; resultados de sucesso como listas de um elemento [resultado]; resultados de erro como listas de três elementos [código, mensagem, detalhes]. Esse codec pode então ser implementado simplesmente delegando a um codec de mensagem subjacente que suporte pelo menos listas, strings e null. Os argumentos da chamada de método, os resultados de sucesso e os detalhes de erro seriam valores arbitrários suportados por esse codec de mensagem.

Diferenças de API. Os exemplos de código acima destacam que os canais de método entregam resultados de formas bem diferentes em Dart, Android e iOS:

  • No lado Dart, a invocação é tratada por um método que retorna um future. O future é completado com o resultado da chamada nos casos de sucesso, com um PlatformException nos casos de erro, e com um MissingPluginException no caso de não implementado.

  • No Android, a invocação é tratada por um método que recebe um argumento de callback. A interface de callback define três métodos, dos quais um é chamado, dependendo do resultado. O código do cliente implementa a interface de callback para definir o que deve acontecer em caso de sucesso, de erro e de não implementado.

  • No iOS, a invocação é tratada de forma parecida, por um método que recebe um argumento de callback. Mas aqui, o callback é uma função de um argumento que recebe ou uma instância de FlutterError, a constante FlutterMethodNotImplemented ou, em caso de sucesso, o resultado da invocação. O código do cliente fornece um bloco com lógica condicional para tratar os diferentes casos, conforme necessário.

Essas diferenças, refletidas também na forma como os handlers de chamadas de mensagem são escritos, surgiram como concessões aos estilos das linguagens de programação (Dart, Java e Objective-C) usadas nas implementações de canal de método do SDK do Flutter. Refazer as implementações em Kotlin e Swift talvez remova algumas das diferenças, mas é preciso cuidado para não dificultar o uso de canais de método a partir de Java e Objective-C.

Canais de eventos: streaming

Um canal de eventos é um canal de plataforma especializado, pensado para expor eventos da plataforma ao Flutter como um stream do Dart. O SDK do Flutter atualmente não tem suporte para o caso simétrico de expor streams do Dart para código de plataforma, embora isso pudesse ser construído se houver necessidade.

Veja como você consumiria um stream de eventos da plataforma no lado Dart:

dart
// Consuming events on the Dart side.
​
const channel = EventChannel('foo');
​
channel.receiveBroadcastStream().listen((dynamic event) {
  print('Received event: $event');
}, onError: (dynamic error) {
  print('Received error: ${error.message}');
});

O código abaixo mostra como produzir eventos no lado da plataforma, usando eventos de sensor no Android como exemplo. A principal preocupação é garantir que estamos escutando eventos da fonte da plataforma (o gerenciador de sensores, neste caso) e enviando-os pelo canal de eventos precisamente quando 1) há pelo menos um listener do stream no lado Dart e 2) o Activity ambiente do app está em execução. Empacotar a lógica necessária numa única classe aumenta a chance de fazer isso corretamente:

kotlin
// Producing sensor events on Android.
​
// SensorEventListener/EventChannel adapter.
class SensorListener(private val sensorManager: SensorManager) :
  EventChannel.StreamHandler, SensorEventListener {
  private var eventSink: EventChannel.EventSink? = null
​
  // EventChannel.StreamHandler methods
  override fun onListen(
    arguments: Any?, eventSink: EventChannel.EventSink?) {
    this.eventSink = eventSink
    registerIfActive()
  }
  override fun onCancel(arguments: Any?) {
    unregisterIfActive()
    eventSink = null
  }
​
  // SensorEventListener methods.
  override fun onSensorChanged(event: SensorEvent) {
    eventSink?.success(event.values)
  }
  override fun onAccuracyChanged(sensor: Sensor?, accuracy: Int) {
    if (accuracy == SensorManager.SENSOR_STATUS_ACCURACY_LOW)
      eventSink?.error("SENSOR", "Low accuracy detected", null)
  }
​
  // Lifecycle methods.
  fun registerIfActive() {
    if (eventSink == null) return
    sensorManager.registerListener(
      this,
      sensorManager.getDefaultSensor(Sensor.TYPE_GYROSCOPE),
      SensorManager.SENSOR_DELAY_NORMAL)
  }
  fun unregisterIfActive() {
    if (eventSink == null) return
    sensorManager.unregisterListener(this)
  }
}
​
// Use of the above class in an Activity.
class MainActivity: FlutterActivity() {
  var sensorListener: SensorListener? = null
​
  override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)
    GeneratedPluginRegistrant.registerWith(this)
    sensorListener = SensorListener(
      getSystemService(Context.SENSOR_SERVICE) as SensorManager)
    val channel = EventChannel(flutterView, "foo")
    channel.setStreamHandler(sensorListener)
  }
​
  override fun onPause() {
    sensorListener?.unregisterIfActive()
    super.onPause()
  }
​
  override fun onResume() {
    sensorListener?.registerIfActive()
    super.onResume()
  }
}

Se você usa o pacote android.arch.lifecycle no seu app, poderia tornar SensorListener mais autocontido fazendo dele um LifecycleObserver.

As letras miúdas. Ciclo de vida de um handler de stream. O handler de stream do lado da plataforma tem dois métodos, onListen e onCancel, que são invocados sempre que o número de listeners do stream Dart passa de zero para um e de volta, respectivamente. Isso pode acontecer várias vezes. A implementação do handler de stream deve começar a enviar eventos para o event sink quando o primeiro é chamado, e parar quando o segundo é chamado. Além disso, deve pausar quando o componente ambiente do app não estiver em execução. O código acima dá um exemplo típico. Por baixo dos panos, um handler de stream é, claro, apenas um handler de mensagem binária, registrado na view do Flutter com o nome do canal de eventos.

Codec. Um canal de eventos é configurado com um codec de método, o que permite distinguir eventos de sucesso e de erro da mesma forma como os canais de método conseguem distinguir resultados de sucesso e de erro.

Argumentos e erros do handler de stream. Os métodos de handler de stream onListen e onCancel são invocados por meio de chamadas de canal de método. Assim, temos chamadas de controle do Dart para a plataforma e mensagens de evento na direção contrária, tudo no mesmo canal lógico. Essa configuração permite que argumentos sejam repassados aos métodos de controle e que quaisquer erros sejam reportados de volta. No lado Dart, os argumentos, se houver, são informados na chamada a receiveBroadcastStream. Isso significa que eles são especificados apenas uma vez, independentemente do número de invocações de onListen e onCancel que acontecem durante a vida do stream. Quaisquer erros reportados de volta são registrados em log.

Fim do stream. Um event sink tem um método endOfStream que pode ser invocado para sinalizar que nenhum evento adicional de sucesso ou de erro será enviado. A mensagem binária null é usada para essa finalidade. Ao recebê-la no lado Dart, o stream é fechado.

Ciclo de vida de um stream. O stream Dart é sustentado por um stream controller alimentado pelas mensagens de canal de plataforma recebidas. Um handler de mensagem binária é registrado usando o nome do canal de eventos para receber mensagens de entrada somente enquanto o stream tiver listeners.

Diretrizes de uso

Prefixe os nomes dos canais com o domínio para garantir unicidade

Nomes de canais são apenas strings, mas precisam ser únicos entre todos os objetos de canal usados para finalidades diferentes no seu app. Você pode fazer isso com qualquer esquema de nomes adequado. Porém, a abordagem recomendada para canais usados em plugins é usar um prefixo com o nome do domínio e do plugin, como some.body.example.com/sensors/foo para o canal foo usado pelo plugin sensors desenvolvido por some.body em example.com. Fazer isso permite que quem consome plugins combine quantos plugins quiser nos seus apps sem risco de colisão de nomes de canal.

Considere tratar canais de plataforma como comunicação intramódulo

O código para invocar chamadas de procedimento remoto em sistemas distribuídos parece superficialmente semelhante ao código que usa canais de método: você invoca um método dado por uma string e serializa seus argumentos e resultados. Como componentes de sistemas distribuídos costumam ser desenvolvidos e implantados de forma independente, a verificação robusta de requisições e respostas é crítica, e geralmente feita no estilo verificar-e-registrar-em-log dos dois lados da rede.

Canais de plataforma, por outro lado, unem três peças de código que são desenvolvidas e implantadas juntas, num único componente.

Java/Kotlin ↔ Dart ↔ Objective-C/Swift

Na verdade, muitas vezes faz sentido empacotar uma tríade assim num único módulo de código, como um plugin do Flutter. Isso significa que a necessidade de verificar argumentos e resultados entre invocações de canal de método deve ser comparável à necessidade dessas verificações entre chamadas de método normais dentro do mesmo módulo.

Dentro dos módulos, nossa principal preocupação é nos proteger de erros de programação que estão além das verificações estáticas do compilador e passam despercebidos em tempo de execução, até explodirem de forma não local no tempo ou no espaço. Um estilo de código razoável é tornar as suposições explícitas usando tipos ou asserções, o que nos permite falhar rápido e de forma limpa, por exemplo com uma exceção. Os detalhes variam conforme a linguagem de programação, claro. Exemplos:

  • Se um valor recebido por um canal de plataforma deve ter um determinado tipo, atribua-o imediatamente a uma variável desse tipo.

  • Se um valor recebido por um canal de plataforma deve ser não nulo, prepare as coisas para desreferenciá-lo imediatamente ou afirme que ele não é nulo antes de guardá-lo para depois. Dependendo da sua linguagem de programação, você pode conseguir atribuí-lo a uma variável de tipo não anulável.

O código Dart a seguir espera receber uma lista não nula de inteiros:

dart
for (final int n in await channel.invokeMethod('getFib', 100)) {
  print(n * n);
}

O código Android a seguir espera argumentos name e age não nulos para processamento assíncrono, entregues num mapa indexado por string:

kotlin
channel.setMethodCallHandler { call, result ->
  when (call.method) {
    "bar" -> {
      val name : String = call.argument("name")
      val age : Int = call.argument("age")
      process(name, age, result)
    }
    else -> result.notImplemented()
  }
}
:
fun process(name: String, age: Int, result: Result) { ... }

O código Android explora o método genérico <T> T argument(String key) de MethodCall, que procura a chave nos argumentos, assumidos como um mapa, e converte o valor encontrado para o tipo-alvo (do local de chamada). Uma exceção adequada é lançada se isso falhar por qualquer motivo. Por ser lançada de dentro de um handler de chamada de método, ela seria registrada em log, e um erro seria enviado ao lado Dart.

Não faça mock de canais de plataforma

(Trocadilho intencional.) Ao escrever testes unitários para código Dart que usa canais de plataforma, uma reação automática pode ser fazer mock do objeto do canal, como você faria com uma conexão de rede.

Você certamente pode fazer isso, mas os objetos de canal não precisam ser mockados para funcionar bem com testes unitários. Em vez disso, você pode registrar handlers de mensagem ou de método simulados para fazer o papel da plataforma durante um teste específico. Aqui está um teste unitário de uma função hello que deve invocar o método bar no canal foo:

dart
test('gets greeting from platform', () async {
  const channel = MethodChannel('foo');
  channel.setMockMethodCallHandler((MethodCall call) async {
    if (call.method == 'bar')
      return 'Hello, ${call.arguments}';
    throw MissingPluginException();
  });
  expect(await hello('world'), 'Platform says: Hello, world');
});

Para testar código que configura handlers de mensagem ou de método, você pode sintetizar mensagens de entrada usando BinaryMessages.handlePlatformMessage. No momento, esse método não tem equivalente nos canais de plataforma, embora isso pudesse ser feito facilmente como indicado no código abaixo. O código define um teste unitário de uma classe Hello que deve coletar argumentos de entrada de chamadas ao método bar no canal foo, enquanto devolve saudações:

dart
test('collects incoming arguments', () async {
  const channel = MethodChannel('foo');
  final hello = Hello();
  final String result = await handleMockCall(
    channel,
    MethodCall('bar', 'world'),
  );
  expect(result, contains('Hello, world'));
  expect(hello.collectedArguments, contains('world'));
});
​
// Could be made an instance method on class MethodChannel.
Future<dynamic> handleMockCall(
  MethodChannel channel,
  MethodCall call,
) async {
  dynamic result;
  await BinaryMessages.handlePlatformMessage(
    channel.name,
    channel.codec.encodeMethodCall(call),
    (ByteData reply) {
      if (reply == null)
        throw MissingPluginException();
      result = channel.codec.decodeEnvelope(reply);
    },
  );
  return result;
}

Os dois exemplos acima declaram o objeto do canal dentro do teste unitário. Isso funciona bem — a menos que você se preocupe com o nome e o codec duplicados — porque todos os objetos de canal com o mesmo nome e codec são equivalentes. Você pode evitar a duplicação declarando o canal como um const em algum lugar visível tanto para o seu código de produção quanto para o teste.

O que você não precisa é fornecer uma forma de injetar um canal mockado no seu código de produção.

Considere testes automatizados para a sua interação com a plataforma

Canais de plataforma são simples o bastante, mas fazer tudo funcionar a partir da sua UI em Flutter, por meio de uma API customizada em Dart apoiada por uma implementação separada em Java/Kotlin e Objective-C/Swift, exige algum cuidado. E manter a configuração funcionando conforme o app muda vai exigir, na prática, testes automatizados para proteger contra regressões. Isso não pode ser feito só com testes unitários, porque você precisa de um app real rodando para que os canais de plataforma realmente conversem com a plataforma.

O Flutter vem com o framework de testes de integração flutter_driver, que permite testar apps Flutter rodando em dispositivos reais e emuladores. Mas flutter_driver não está atualmente integrado a outros frameworks para permitir testes que atravessem componentes do Flutter e da plataforma. Tenho confiança de que essa é uma área em que o Flutter vai melhorar no futuro.

Em algumas situações, você pode usar flutter_driver como está para testar o uso do seu canal de plataforma. Isso exige que sua interface em Flutter possa ser usada para disparar qualquer interação com a plataforma e que ela seja então atualizada com detalhes suficientes para permitir que seu teste verifique o resultado da interação.

Se você não estiver nessa situação, ou se estiver empacotando o uso do seu canal de plataforma como um plugin do Flutter para o qual quer um teste de módulo, pode, em vez disso, escrever um app Flutter simples para fins de teste. Esse app deve ter as características acima e pode então ser exercitado usando flutter_driver. Você encontra um exemplo em o repositório do Flutter no GitHub.

Mantenha o lado da plataforma preparado para chamadas síncronas de entrada

Canais de plataforma são somente assíncronos. Mas há bastante API de plataforma por aí que faz chamadas síncronas para componentes do seu app host, pedindo informações ou ajuda ou oferecendo uma janela de oportunidade. Um exemplo é Activity.onSaveInstanceState no Android. Por ser síncrono, tudo precisa estar pronto antes que a chamada de entrada retorne. Agora, você pode querer incluir informações do lado Dart nesse processamento, mas já é tarde para começar a enviar mensagens assíncronas quando a chamada síncrona já está ativa na thread principal da UI.

A abordagem usada pelo Flutter, sobretudo para informações de semântica e acessibilidade, é enviar proativamente informações atualizadas para o lado da plataforma sempre que elas mudam no lado Dart. Assim, quando a chamada síncrona chega, as informações do lado Dart já estão presentes e disponíveis para o código do lado da plataforma.

Recursos

Documentação da API do Flutter:

Guias:

  • O site flutter.io documenta como usar canais de método e as conversões de valores entre Dart, Android e iOS envolvidas no uso do codec de método padrão.

  • O Boring Flutter Development Show, episódio 6: Pacotes e plugins, é um vídeo no YouTube que mostra um plugin do Flutter sendo implementado, ao vivo, usando canais de plataforma.

Exemplos de código:

  • O repositório flutter/flutter no GitHub contém um exemplo básico de uso de canais de método e de evento para acessar informações da bateria do dispositivo, empacotado num app Flutter completo.

  • O repositório flutter/plugins no GitHub contém vários exemplos de uso de canais de plataforma para implementar plugins do Flutter. O código fica na subpasta packages, organizada por plugin. Cada plugin inclui um app de exemplo completo.

Mais do Flutter