Platform channels, plugins e API v2

No fim desta aula consegues

• Explicar o que é um platform channel, a diferença entre MethodChannel e EventChannel, e que tipos passam por eles.
• Situar FFI, plugins federados e platform views, e dizer quando cada um se usa.
• Avaliar um package no pub.dev com critérios objetivos antes de o adicionar ao projeto.
• Ler o nível da bateria com um MethodChannel em Kotlin e Swift, e tratar as plataformas onde não existe.
• Migrar os modelos e o repository para a API v2 mantendo a v1 a funcionar atrás de uma feature flag.

MethodChannel e EventChannel

• Um platform channel é um canal de mensagens com nome (pdm/bateria) entre o Dart e o código nativo: Kotlin ou Java no Android, Swift ou Objective-C no iOS. As mensagens são serializadas pelo StandardMessageCodec.
• MethodChannel é pedido-resposta: o Dart chama invokeMethod('nivel'), o nativo responde com result.success(valor) ou result.error(...). Sempre assíncrono.
• EventChannel é um stream do nativo para o Dart: mudanças de bateria, sensores, posição. O nativo emite quando quiser; o Dart faz receiveBroadcastStream().listen.
• Tipos suportados: null, bool, int, double, String, Uint8List e outras listas tipadas, List, Map. Objetos não passam: serializa em Map.
• O handler corre na thread principal da plataforma: trabalho pesado no nativo vai para outra thread e responde depois.
• Um plugin compensa quando o mesmo canal serve mais do que uma app ou queres publicar. Para uma app, um canal dentro do projeto chega.

Para os testes: MethodChannel é pedido-resposta assíncrono; EventChannel é um stream nativo → Dart; os dados passam como primitivos, listas e mapas.

FFI: chamar C diretamente

• dart:ffi chama funções C sem canal nem serialização: o Dart carrega uma biblioteca (.so, .dylib) e chama a função com a assinatura declarada. Microssegundos em vez de milissegundos.
• ffigen gera as ligações Dart a partir de um header C; jnigen faz o mesmo para APIs Java e Kotlin do Android; para Swift há swift2objc, ainda experimental.
• Casos de uso: bibliotecas C existentes (SQLite, criptografia, codecs, processamento de imagem), código partilhado com outras plataformas em Rust ou C++ (flutter_rust_bridge).
• Custos: memória manual com malloc e free do package:ffi, tipos C, compilar a biblioteca para cada arquitetura, e nada de hot reload na parte nativa.
• Exemplo: o package sqlite3 usa FFI e é mais rápido do que o sqflite, que usa um MethodChannel.

Para os testes: FFI chama C diretamente, sem serialização; platform channels trocam mensagens com Kotlin e Swift. FFI para bibliotecas C e desempenho; channels para APIs do sistema.

Plugins federados e platform views

• Um plugin federado divide-se em: a interface (x_platform_interface), uma implementação por plataforma (x_android, x_ios, x_web) e o package que tu importas (x). Cada implementação regista-se sozinha.
• Vantagem: outra pessoa acrescenta Windows ou web sem tocar no plugin principal. É assim que url_launcher, camera e shared_preferences estão feitos.
• flutter create --template=plugin --platforms=android,ios gera o esqueleto; o pubspec.yaml declara flutter: plugin: platforms: com a classe nativa de cada plataforma.
• Platform view: um widget nativo (mapa da Google, WebView, player de vídeo, anúncio) embutido na árvore Flutter. Custa desempenho e tem limitações com gestos e recortes.
• google_maps_flutter e webview_flutter são platform views; o flutter_map da aula 21 não é: desenha os tiles em Dart.

Para os testes: plugin federado = interface + uma implementação por plataforma; platform view = widget nativo dentro da árvore Flutter, mais caro do que um widget Dart.

Avaliar um package no pub.dev

• Dependências: flutter pub deps mostra o que o package traz consigo. Cada uma é uma manutenção que herdas.
• Pergunta final: dá para escrever em 50 linhas? Então não instales.

Para os testes: pub points, popularidade, data da última versão, issues abertas, publisher e licença; um package sem manutenção é uma dívida que vais pagar.

APIs mudam: versionar e migrar sem partir

• Versionamento por URL (/v1/, /v2/) é o mais comum em mobile: visível, cacheável, fácil de testar. Alternativas: header Accept-Version ou query ?v=2.
• Incompatível: renomear ou remover campos, mudar tipos ou formatos de data, remover endpoints. Compatível: campo novo opcional, endpoint novo. Um cliente bem feito ignora campos que não conhece.
• Deprecação com prazo: a v1 continua a responder depois de a v2 sair, com headers Deprecation e Sunset. No curso: v1 até 09/12, depois 410 Gone.
• A app instalada não atualiza quando queres: há quem fique meses numa versão. O backend serve as duas versões nesse período; a app tolera diferenças pequenas.
• Changelog por versão, com exemplos de resposta. Sem ele, migrar é adivinhar.
• Estratégia: duas factories (fromJsonV1, fromJsonV2), feature flag no repository, testes com amostras reais das duas versões, forced update quando a v1 desligar (aula 30).

Para os testes: versionar por URL, deprecar com prazo, e nunca assumir que todos os utilizadores estão na versão nova da app.

Prática: bateria por MethodChannel e migração para a v2

git clone https://github.com/pdm-daw-2026/pdm-aula-28.git
cd pdm-aula-28/starter
flutter pub get
flutter run

O starter/ tem o Tempo Açores na v1, um ecrã de definições com espaço para a bateria, e TODOs numerados de 1 a 8. Em test/ há testes a falhar: bateria_service_test.dart (com o canal simulado) e previsao_v2_test.dart. O solucao/ tem o estado final nas duas plataformas e com a flag.

Quatro blocos: o canal em Dart, Kotlin e Swift; as plataformas sem canal; os modelos v2; a flag para correr v1 e v2 lado a lado.

1. O lado Dart do canal

import 'package:flutter/services.dart';

class BateriaService {
  BateriaService({MethodChannel? canal})
      : _canal = canal ?? const MethodChannel('pdm/bateria');
  final MethodChannel _canal;

  /// Nível da bateria em percentagem, de 0 a 100.
  Future<int> nivel() async {
    final valor = await _canal.invokeMethod<int>('nivel');
    if (valor == null) throw StateError('A plataforma não devolveu o nível');
    return valor;
  }
}

// No ecrã de definições
FutureBuilder<int>(
  future: context.read<BateriaService>().nivel(),
  builder: (context, snapshot) {
    if (snapshot.hasError) return const Text('Bateria indisponível');
    if (!snapshot.hasData) return const SizedBox.shrink();
    return Text('Bateria: ${snapshot.data} %');
  },
)

1. O lado Android, em Kotlin

package pt.uac.tempoacores

import android.content.Context
import android.os.BatteryManager
import io.flutter.embedding.android.FlutterActivity
import io.flutter.embedding.engine.FlutterEngine
import io.flutter.plugin.common.MethodChannel

class MainActivity : FlutterActivity() {
    override fun configureFlutterEngine(flutterEngine: FlutterEngine) {
        super.configureFlutterEngine(flutterEngine)
        MethodChannel(flutterEngine.dartExecutor.binaryMessenger, "pdm/bateria")
            .setMethodCallHandler { call, result ->
                if (call.method != "nivel") { result.notImplemented(); return@setMethodCallHandler }
                val bm = getSystemService(Context.BATTERY_SERVICE) as BatteryManager
                val nivel = bm.getIntProperty(BatteryManager.BATTERY_PROPERTY_CAPACITY)
                if (nivel == Integer.MIN_VALUE) {
                    result.error("INDISPONIVEL", "Nível de bateria não disponível", null)
                } else {
                    result.success(nivel)
                }
            }
    }
}

1. O lado iOS, em Swift

import Flutter
import UIKit

@main
@objc class AppDelegate: FlutterAppDelegate {
  override func application(
    _ application: UIApplication,
    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?
  ) -> Bool {
    let controller = window?.rootViewController as! FlutterViewController
    let canal = FlutterMethodChannel(name: "pdm/bateria", binaryMessenger: controller.binaryMessenger)
    canal.setMethodCallHandler { call, result in
      guard call.method == "nivel" else { result(FlutterMethodNotImplemented); return }
      let device = UIDevice.current
      device.isBatteryMonitoringEnabled = true
      if device.batteryState == .unknown {
        result(FlutterError(code: "INDISPONIVEL", message: "Nível de bateria não disponível", details: nil))
      } else {
        result(Int(device.batteryLevel * 100))
      }
    }
    GeneratedPluginRegistrant.register(with: self)
    return super.application(application, didFinishLaunchingWithOptions: launchOptions)
  }
}

1. O canal: o que interessa

• O nome do canal é um contrato: pdm/bateria nos três lados. Um erro de escrita dá MissingPluginException em runtime, não erro de compilação.
• invokeMethod<int> faz o cast: o Int do Kotlin e o Int do Swift chegam como int em Dart. Um Long também, porque o int do Dart tem 64 bits.
• result.error(code, message, details) chega ao Dart como PlatformException. Códigos em maiúsculas e estáveis, para o Dart poder fazer switch.
• Só se cria um MethodChannel por nome; o handler é o último registado. Regista-o no configureFlutterEngine e no didFinishLaunchingWithOptions, nunca num widget.
• Testar sem telemóvel: TestDefaultBinaryMessenger.setMockMethodCallHandler responde ao canal com um valor fixo. O starter já traz esse teste.

2. Onde o canal não existe: web, desktop, simulador

import 'package:flutter/foundation.dart' show kIsWeb, debugPrint;

  /// null quando a plataforma não tem canal ou não sabe o nível.
  Future<int?> nivelSeguro() async {
    if (kIsWeb) return null;                     // na web não há código nativo
    try {
      return await _canal.invokeMethod<int>('nivel');
    } on MissingPluginException {
      return null;                               // desktop sem handler, ou nome errado
    } on PlatformException catch (e) {
      debugPrint('Bateria: ${e.code} ${e.message}');
      return null;                               // INDISPONIVEL no simulador iOS
    }
  }

• MissingPluginException: não há handler para o canal nesta plataforma. Não é um erro do utilizador; é uma funcionalidade que aqui não existe.
• PlatformException: o nativo respondeu com erro. code para decidir, message para os logs.
• A UI não mostra "erro": esconde a linha ou diz "indisponível". Uma funcionalidade opcional degrada em silêncio.

3. API v2: o que mudou

• Autenticação, favoritos e os headers X-Platform e X-App-Version não mudam. Os avisos mudam ao mesmo estilo: level passa a severity e as datas a ISO 8601.
• A v1 responde até 09/12 com Deprecation: true e Sunset; depois, 410 Gone. O changelog completo está na página API.

3. Um elemento de forecast, nas duas versões

{
  "locationId": "3420300",
  "forecastDate": "2026-11-23",
  "tMin": 14.2,
  "tMax": 19.8,
  "weatherType": "rain",
  "precipProb": 65
}

{
  "location_id": "3420300",
  "date": "2026-11-23T00:00:00-01:00",
  "temperature": { "min": 14.2, "max": 19.8 },
  "weather": "rain",
  "precipitation_probability": 65,
  "issued_at": "2026-11-23T06:12:00-01:00"
}

Os dois excertos estão em test/amostras/ no starter, copiados da API real. É contra eles que os testes correm.

3. Duas factories no mesmo modelo

class Previsao {
  // campos e construtor como na aula 25

  factory Previsao.fromJsonV1(Map<String, dynamic> json) => Previsao(
        localidadeId: json['locationId'] as String,
        dia: DateTime.parse(json['forecastDate'] as String),
        tMin: (json['tMin'] as num).toDouble(),
        tMax: (json['tMax'] as num).toDouble(),
        tipo: TipoTempo.fromApi(json['weatherType'] as String),
        probPrecipitacao: (json['precipProb'] as num?)?.toDouble(),
      );

  factory Previsao.fromJsonV2(Map<String, dynamic> json) {
    final temp = json['temperature'] as Map<String, dynamic>?;
    if (temp == null) throw const FormatException('v2: falta o objeto "temperature"');
    return Previsao(
      localidadeId: json['location_id'] as String,
      dia: DateTime.parse(json['date'] as String).toLocal(),
      tMin: (temp['min'] as num).toDouble(),
      tMax: (temp['max'] as num).toDouble(),
      tipo: TipoTempo.fromApi(json['weather'] as String),
      probPrecipitacao: (json['precipitation_probability'] as num?)?.toDouble(),
    );
  }
}

3. Os testes da v2

import 'dart:convert';
import 'package:flutter_test/flutter_test.dart';
import 'package:tempo_acores/models/previsao.dart';

const amostraV2 = '''
{"location_id": "3420300", "date": "2026-11-23T00:00:00-01:00",
 "temperature": {"min": 14.2, "max": 19.8}, "weather": "rain",
 "precipitation_probability": 65}
''';

void main() {
  final p = Previsao.fromJsonV2(jsonDecode(amostraV2) as Map<String, dynamic>);

  test('lê as temperaturas do objeto temperature', () {
    expect(p.tMin, 14.2);
    expect(p.tMax, 19.8);
    expect(p.amplitude, closeTo(5.6, 0.001));
  });

  test('converte a data ISO com fuso para hora local', () {
    expect(p.dia.isUtc, isFalse);
    expect(p.dia.toUtc(), DateTime.utc(2026, 11, 23, 1));   // 00:00 nos Açores é 01:00 UTC
  });

  test('lança FormatException se faltar temperature', () {
    expect(() => Previsao.fromJsonV2({'location_id': '1', 'date': '2026-11-23T00:00:00Z', 'weather': 'sun'}),
        throwsFormatException);
  });
}

4. v1 e v2 lado a lado, com uma feature flag

enum ApiVersao { v1, v2 }

class ApiConfig {
  /// flutter run --dart-define=API_V2=true liga a v2; por defeito fica na v1.
  static const versao = bool.fromEnvironment('API_V2') ? ApiVersao.v2 : ApiVersao.v1;
}

class PrevisaoRepositoryHttp implements PrevisaoRepository {
  PrevisaoRepositoryHttp(this._client, {this.versao = ApiConfig.versao});
  final ApiClient _client;
  final ApiVersao versao;

  @override
  Future<List<Previsao>> previsao(String localidadeId) async {
    final (caminho, parse) = switch (versao) {
      ApiVersao.v1 => ('/v1/forecast/$localidadeId', Previsao.fromJsonV1),
      ApiVersao.v2 => ('/v2/forecast/$localidadeId', Previsao.fromJsonV2),
    };
    final json = await _client.getJson(caminho);
    final itens = json['forecast'] as List<dynamic>;
    return itens.map((e) => parse(e as Map<String, dynamic>)).toList();
  }
}

4. A migração: o que interessa

• A flag vive num sítio só. O ecrã não sabe que existe v1 ou v2; o notifier também não. Só o repository muda de caminho e de parser.
• --dart-define é uma flag de build: o CI corre os testes contra as duas. Uma flag de Remote Config (aula 26) troca sem novo build; a lógica é a mesma, muda a origem do valor.
• Ordem: modelos com as duas factories e testes verdes → repository com a flag → build de teste em v2 aos testers → flag por defeito a v2 → apagar a v1 quando o backend desligar e subir a versão mínima (forced update, aula 30).
• Nunca apagues a v1 no PR em que ligas a v2. Se a v2 falhar em produção, o kill switch é voltar a flag atrás.
• O switch sobre o enum é exaustivo: quando aparecer uma ApiVersao.v3, o compilador obriga-te a tratá-la.

Para os testes: migrar uma API é acrescentar a versão nova ao lado da antiga, trocar por flag e só depois remover; nunca substituir num só passo.

Até amanhã