Workshop: polish de UI e primeira distribuição a testers

No fim desta aula consegues

• Descrever o fluxo do Firebase App Distribution, do TestFlight e dos testes internos do Google Play, e dizer o que cada um exige.
• Construir um tema claro e escuro a partir de um ColorScheme e usar as cores do tema em vez de cores fixas.
• Internacionalizar a app com gen-l10n, ficheiros .arb em pt e en, plurais e placeholders.
• Gerar ícone e splash com flutter_launcher_icons e flutter_native_splash.
• Fazer um build de release Android e distribuí-lo a testers pela consola e pela CLI do Firebase.

Porque distribuir cedo

• Feedback real. O tester não sabe onde carregar. Tu sabes, e é por isso que nunca encontras o problema.
• Instalação real. Build de release, sem cabo, num telemóvel que não é o teu, com outra versão do Android, outro tamanho de ecrã e outro teclado.
• Crashes reais. Com o Crashlytics ou o Sentry de quarta, dez testers durante uma semana dão mais informação do que cem horas de emulador.
• As grandes apps fazem isto em escala: o Google Maps tem programa beta no Play, o Instagram no TestFlight, com milhares de testers antes de cada versão.
• Custo: uma manhã para montar, cinco minutos por build depois. Sem isto, o primeiro tester é o cliente.

Para os testes: distribuir cedo dá feedback, instalação e crashes reais; o tester não sabe onde carregar, e é por isso que serve.

Firebase App Distribution (1 de 2)

• Serviço grátis do Firebase para entregar builds Android (APK ou AAB) e iOS (IPA) a testers, sem passar pela loja.
• Testers por email, organizados em grupos ("turma-daw", "qa", "cliente"). Recebem um email com link, instalam a app App Tester no Android, e veem todas as versões disponíveis.
• Android: um APK instala diretamente (o tester autoriza "instalar de fontes desconhecidas" uma vez). Um AAB obriga a ligar a conta ao Play para gerar os APKs. Para a turma, APK.
• iOS: precisa de um IPA assinado com um perfil ad hoc que inclua o UDID de cada iPhone, ou de conta enterprise. Por isso, para iOS, o TestFlight é mais simples.
• Cada release tem notas de versão, e o tester pode enviar feedback com screenshot a partir da própria app.

Para os testes: App Distribution entrega APKs a testers por email, sem loja; em iOS exige perfil ad hoc com UDIDs, o que torna o TestFlight preferível.

Firebase App Distribution (2 de 2): consola, CLI e Actions

• Consola: arrastar o APK, escolher grupos, escrever notas. Boa para a primeira vez, má para a décima.
• CLI: firebase appdistribution:distribute app-release.apk --app ID --groups turma-daw. Um comando, repetível, cabe num script.
• GitHub Actions: um job que faz flutter build apk --release e distribui a cada tag ou a cada merge em main. A partir daí, nenhum build de produção sai do portátil de alguém.
• Autenticação da CI: uma service account do Firebase guardada em Secrets do GitHub. Nunca no repositório.
• Alternativas: Diawi (link direto para um APK), o próprio Play internal testing, ou o Codemagic com distribuição integrada.

Para os testes: distribuir a partir do CI garante builds reproduzíveis; a credencial do Firebase vai em Secrets, nunca no repositório.

TestFlight

• O serviço de beta da Apple: os builds sobem para o App Store Connect e os testers instalam pela app TestFlight.
• Precisa de conta paga (99 USD por ano), de um Mac com Xcode para assinar e fazer upload, e de um bundle id registado.
• Testers internos: até 100 membros da equipa no App Store Connect, sem revisão, build disponível minutos depois do processamento.
• Testers externos: até 10 000, por email ou link público; o primeiro build de cada versão passa por Beta App Review (horas a um dia). Os builds expiram ao fim de 90 dias.
• Feedback: screenshots anotados e crash reports chegam ao App Store Connect. Cada build leva notas "What to test".

Para os testes: TestFlight exige conta paga e Mac; internos até 100 sem revisão, externos até 10 000 com Beta App Review; builds expiram em 90 dias.

Google Play internal testing, e os três lado a lado

Contas pessoais novas no Play têm de ter 12 testers em closed testing durante 14 dias antes de poderem publicar em produção.

Para os testes: o internal testing do Play aceita até 100 testers sem revisão; closed e open testing são o caminho para produção.

Boas práticas de distribuição

• Notas de versão em cada build: o que testar, o que mudou, o que já sabem que está partido. "Build 47" sem notas é um build que ninguém testa.
• Versionamento: sobe o version: 1.2.0+47 no pubspec.yaml antes de cada distribuição. Dois builds com o mesmo número confundem testers e loja, e o Play recusa.
• Feedback in-app: um botão "Reportar problema" que abre email ou o feedback do App Distribution, com versão e modelo pré-preenchidos.
• Nunca um build de debug: é 2 a 3 vezes mais lento e tem o dobro do tamanho. Os testers vão dizer que a app é lenta, e têm razão.
• Cedo e muitas vezes: um build por semana com notas curtas vale mais do que um build "final" na véspera.

Para os testes: nunca distribuir builds de debug; cada build com número de versão novo e notas de versão.

Workshop: da app no teu telemóvel à app no dos outros

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

O starter/ é uma versão do Tempo Açores com cores fixas, strings em português no código, ícone por defeito e sem splash; tem TODOs numerados de 1 a 8 e testes a falhar em test/. O solucao/ tem o estado final, com os .arb, a configuração do ícone e do splash e o workflow de distribuição.

Bloco 1: tema claro e escuro a partir de uma semente

import 'package:flutter/material.dart';

class AppTheme {
  static const _semente = Color(0xFF0B63C9);

  static ThemeData claro() => _base(ColorScheme.fromSeed(seedColor: _semente));

  static ThemeData escuro() =>
      _base(ColorScheme.fromSeed(seedColor: _semente, brightness: Brightness.dark));

  static ThemeData _base(ColorScheme esquema) => ThemeData(
        useMaterial3: true,
        colorScheme: esquema,
        appBarTheme: AppBarTheme(
          backgroundColor: esquema.surface,
          foregroundColor: esquema.onSurface,
          centerTitle: false,
        ),
        cardTheme: const CardThemeData(margin: EdgeInsets.symmetric(horizontal: 16, vertical: 6)),
        textTheme: const TextTheme(
          headlineSmall: TextStyle(fontWeight: FontWeight.w700, letterSpacing: -0.5),
          bodyMedium: TextStyle(height: 1.4),
        ),
      );
}

Bloco 1: ligar ao MaterialApp e usar nos widgets

MaterialApp(
  theme: AppTheme.claro(),
  darkTheme: AppTheme.escuro(),
  themeMode: context.watch<DefinicoesNotifier>().temaModo, // system, light ou dark
  // ...
)
// Num widget: nunca Colors.blue, sempre o esquema do tema
class AvisoChip extends StatelessWidget {
  const AvisoChip({super.key, required this.nivel});
  final NivelAviso nivel;

  @override
  Widget build(BuildContext context) {
    final esquema = Theme.of(context).colorScheme;
    final (fundo, texto) = switch (nivel) {
      NivelAviso.vermelho => (esquema.errorContainer, esquema.onErrorContainer),
      NivelAviso.laranja || NivelAviso.amarelo => (esquema.tertiaryContainer, esquema.onTertiaryContainer),
      NivelAviso.verde => (esquema.secondaryContainer, esquema.onSecondaryContainer),
    };
    return Chip(
      label: Text(nivel.name, style: TextStyle(color: texto)),
      backgroundColor: fundo,
    );
  }
}

Bloco 1: o que interessa

• ColorScheme.fromSeed gera as cerca de 30 cores do Material 3 a partir de uma só; a versão escura vem da mesma semente com Brightness.dark. Coerência grátis.
• Regra: nenhuma cor fixa em widgets. Colors.white num Container fica branco no tema escuro e cega. Os pares surface/onSurface, primaryContainer/onPrimaryContainer garantem contraste.
• Tipografia: define no textTheme e usa Theme.of(context).textTheme.titleMedium. Não repitas TextStyle(fontSize: 18) em vinte sítios.
• ThemeMode.system por defeito; o toggle da aula 9 guarda a escolha em shared_preferences.
• Testa os dois temas em todos os ecrãs: o estado de erro, o skeleton, o mapa (os tiles OSM são claros; há tiles escuros).

Bloco 2: i18n com gen-l10n, a configuração

dependencies:
  flutter:
    sdk: flutter
  flutter_localizations:
    sdk: flutter
  intl: any            # a versão é fixada pelo flutter_localizations

flutter:
  uses-material-design: true
  generate: true       # liga o gen-l10n ao flutter pub get

arb-dir: lib/l10n
template-arb-file: app_pt.arb
output-localization-file: app_localizations.dart

Depois de flutter pub get, o gerador escreve lib/l10n/app_localizations.dart e um ficheiro por língua. Não se editam: regeneram-se sempre que um .arb muda.

Bloco 2: os ficheiros .arb

{
  "@@locale": "pt",
  "tituloApp": "Tempo Açores",
  "previsaoDias": "Previsão a {dias} dias",
  "@previsaoDias": {"placeholders": {"dias": {"type": "int"}}},
  "avisosAtivos": "{n, plural, =0{Sem avisos ativos} =1{1 aviso ativo} other{{n} avisos ativos}}",
  "@avisosAtivos": {"placeholders": {"n": {"type": "int"}}},
  "atualizadoHa": "Atualizado há {minutos} min",
  "@atualizadoHa": {"placeholders": {"minutos": {"type": "int"}}},
  "tentarDeNovo": "Tentar de novo",
  "semLigacao": "Sem ligação. A mostrar os últimos dados guardados.",
  "favoritos": "Favoritos",
  "definicoes": "Definições"
}

{
  "@@locale": "en",
  "tituloApp": "Azores Weather",
  "previsaoDias": "{dias}-day forecast",
  "avisosAtivos": "{n, plural, =0{No active warnings} =1{1 active warning} other{{n} active warnings}}",
  "atualizadoHa": "Updated {minutos} min ago",
  "tentarDeNovo": "Try again",
  "semLigacao": "No connection. Showing the last saved data.",
  "favoritos": "Favourites",
  "definicoes": "Settings"
}

Bloco 2: ligar e usar

import 'package:intl/intl.dart';
import 'package:tempo_acores/l10n/app_localizations.dart';

MaterialApp(
  localizationsDelegates: AppLocalizations.localizationsDelegates,
  supportedLocales: AppLocalizations.supportedLocales,   // [pt, en], lidos dos .arb
  onGenerateTitle: (context) => AppLocalizations.of(context)!.tituloApp,
  locale: definicoes.locale,                              // null: segue o telemóvel
  // ...
)

// Num widget
final l10n = AppLocalizations.of(context)!;
Text(l10n.previsaoDias(5));
Text(l10n.avisosAtivos(avisos.length));
Text(l10n.atualizadoHa(DateTime.now().difference(obtidoEm).inMinutes));

// Datas e números na língua ativa, com intl
final locale = Localizations.localeOf(context).toString();
Text(DateFormat.EEEE(locale).format(previsao.dia));       // "segunda-feira" / "Monday"
Text(NumberFormat.decimalPattern(locale).format(19.8));   // "19,8" / "19.8"

Bloco 2: o que interessa

• Nenhuma string na UI. Cada Text('...') fixo é um bug de i18n à espera. Extrair todas as strings é trabalhoso; por isso faz-se cedo e não na véspera.
• Plurais com sintaxe ICU: =0, =1, other. Português e inglês são simples; russo e árabe têm mais categorias, e o intl conhece-as.
• A metadata @chave só é obrigatória no ficheiro template; as traduções só precisam das chaves. Chave em falta no en: o gerador avisa e usa o pt.
• Datas com DateFormat e o locale ativo. DateTime.toString() na UI é proibido.
• Layouts: "Tentar de novo" em alemão é "Erneut versuchen". Botões com largura fixa partem. Testa em inglês e imagina o dobro.
• Uma extensão extension L10n on BuildContext { AppLocalizations get l10n => AppLocalizations.of(this)!; } poupa o ! em todo o lado.

Bloco 3: ícone com flutter_launcher_icons

dev_dependencies:
  flutter_launcher_icons: ^0.14.3
  flutter_native_splash: ^2.4.4

flutter_launcher_icons:
  android: true
  ios: true
  image_path: "assets/icon/icon-1024.png"
  adaptive_icon_background: "#0B63C9"
  adaptive_icon_foreground: "assets/icon/icon-foreground.png"
  remove_alpha_ios: true
  min_sdk_android: 21

dart run flutter_launcher_icons

• Fonte: um PNG de 1024×1024. O iOS não aceita transparência (daí o remove_alpha_ios). O adaptive icon do Android tem fundo e primeiro plano separados, e o launcher recorta (círculo, squircle) como quiser: deixa margem no primeiro plano.
• O gerador escreve em android/app/src/main/res/mipmap-* e ios/Runner/Assets.xcassets/AppIcon.appiconset. Não se edita à mão.

Bloco 3: splash com flutter_native_splash

flutter_native_splash:
  color: "#0B63C9"
  color_dark: "#0F141B"
  image: assets/splash/logo.png
  image_dark: assets/splash/logo-dark.png
  android_12:
    color: "#0B63C9"
    color_dark: "#0F141B"
    image: assets/splash/logo-android12.png
  android: true
  ios: true

dart run flutter_native_splash:create

• O splash nativo aparece antes de o Flutter arrancar; não é um widget. O Android 12+ tem o seu próprio splash (ícone no centro, 192 dp) e ignora a imagem grande: daí a secção android_12.
• Cor de fundo igual à do primeiro ecrã, para a transição não piscar. Sem texto: aparece durante 300 ms. Para reverter, dart run flutter_native_splash:remove.

Bloco 4: build de release e instalar no telemóvel de outro grupo

flutter build apk --release
ls -lh build/app/outputs/flutter-apk/app-release.apk
adb install -r build/app/outputs/flutter-apk/app-release.apk

1. Sobe a versão primeiro: version: 0.3.0+3 no pubspec.yaml. O +3 é o versionCode do Android; tem de crescer a cada build distribuído.
2. Build: 2 a 4 minutos na primeira vez. O APK fica em build/app/outputs/flutter-apk/app-release.apk, com cerca de 20 MB.
3. Instala no telemóvel de um colega de outro grupo: por cabo com adb install, ou envia o ficheiro (Drive, Bluetooth, Nearby Share) e abre-o no telemóvel dele.
4. Observa: pede-lhe que use a app dois minutos sem ajuda. Não expliques nada. Anota o que não percebeu.

Bloco 4: o que interessa

• Release: AOT, sem asserts, sem hot reload. Duas a três vezes mais rápido e metade do tamanho do debug. É o único build que se distribui.
• Assinatura: por defeito o build.gradle assina o release com a chave de debug. Instala, mas o Play não aceita e todos os grupos partilham a mesma chave. A chave de release é matéria da aula 31.
• --split-per-abi gera um APK por arquitetura (arm64-v8a, armeabi-v7a, x86_64), cada um com um terço do tamanho. Para a loja, flutter build appbundle.
• Fontes desconhecidas: o Android pergunta ao tester se confia na origem (Ficheiros, Chrome, App Tester). Uma vez por origem, não por app.
• O client-id da API do curso vai no build por --dart-define, como na aula 18. Confirma que não está no repositório antes de distribuir.

Bloco 5: Firebase App Distribution na consola

1. Projeto: em console.firebase.google.com, "Add project" com o nome tempo-acores-grupoNN. O Analytics pode ficar desligado.
2. App Android: "Add app" → Android, com o package name igual ao applicationId em android/app/build.gradle.kts (por exemplo pt.uac.tempoacores.grupo01). O google-services.json só é preciso se usarem Crashlytics ou Analytics.
3. Distribuir: menu "Run" → App Distribution → "Get started" → arrasta o app-release.apk.
4. Testers: separador "Testers and groups" → grupo turma-daw com os emails dos colegas (o docente partilha a lista no Moodle).
5. Release: adiciona o grupo, escreve notas ("v0.3.0: favoritos sincronizados e mapa. Sabemos que o offline no ecrã de avisos falha.") e "Distribute".
6. Do lado do tester: email → aceitar convite → instalar a App Tester → instalar a app. Na consola vês quem aceitou e quem instalou.

Bloco 5: o mesmo pela CLI

npm install -g firebase-tools
firebase login
firebase apps:list --project tempo-acores-grupo01
firebase appdistribution:distribute build/app/outputs/flutter-apk/app-release.apk \
  --app 1:123456789012:android:0a1b2c3d4e5f6a7b \
  --groups turma-daw \
  --release-notes "v0.3.0: favoritos sincronizados e mapa. Testar: modo avião no ecrã de avisos."

• O --app é o App ID que apps:list mostra (também está nas definições do projeto). Identifica o projeto e a app; não confundir com o package name.
• --testers "ana@x.pt,rui@y.pt" em vez de --groups para convidar pessoas avulsas; --release-notes-file notas.txt para notas longas.
• Mete isto num tool/distribuir.sh que sobe a versão, faz o build e distribui. Quem corre o script não precisa de saber Firebase.

Bloco 5: a partir do GitHub Actions

name: Distribuir
on:
  push:
    tags: ['v*']

jobs:
  android:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-java@v4
        with: { distribution: temurin, java-version: '17' }
      - uses: subosito/flutter-action@v2
        with: { channel: stable, cache: true }
      - run: flutter pub get
      - run: flutter test
      - run: flutter build apk --release --dart-define=API_CLIENT_ID=${{ secrets.API_CLIENT_ID }}
      - uses: wzieba/Firebase-Distribution-Github-Action@v1
        with:
          appId: ${{ secrets.FIREBASE_APP_ID }}
          serviceCredentialsFileContent: ${{ secrets.FIREBASE_SERVICE_ACCOUNT }}
          groups: turma-daw
          file: build/app/outputs/flutter-apk/app-release.apk
          releaseNotes: ${{ github.ref_name }}

A service account vem de "Project settings → Service accounts → Generate new private key" no Firebase; o JSON inteiro vai para o secret FIREBASE_SERVICE_ACCOUNT. A partir daqui, git tag v0.3.0 && git push --tags distribui.

Bloco 5: o que interessa

• O tester precisa de uma conta Google com o email convidado e da App Tester. É onde mais gente encrava: "não recebi o email" (spam) ou "aceitei com outra conta".
• Cada release tem versão e build: dois uploads com o mesmo versionCode são a mesma release. Sobe o +N antes de cada build.
• Feedback: na App Tester o tester usa o botão de feedback ou abana o telemóvel; chega com screenshot ao separador "Feedback" da release.
• Com o workflow, a tag v0.3.0 dispara build e distribuição. O portátil de ninguém volta a ser a origem dos builds, e os testes correm antes.
• Um projeto Firebase por grupo. Não convidem a turma para o projeto; convidem-na como testers.

Demo do docente: TestFlight ao vivo

1. Xcode → Runner → Signing & Capabilities: equipa e bundle id (pt.uac.tempoacores). Com "Automatically manage signing", o Xcode cria certificado e perfil.
2. Build: flutter build ipa --release cria build/ios/archive/Runner.xcarchive e o .ipa em build/ios/ipa/. Demora 5 a 8 minutos.
3. Upload: abrir o .xcarchive no Xcode → "Distribute App" → App Store Connect → Upload; ou a app Transporter com o .ipa. O processamento demora 5 a 15 minutos e chega um email.
4. App Store Connect → TestFlight: o build aparece. Se pedir "Missing Compliance", é a pergunta sobre encriptação; com ITSAppUsesNonExemptEncryption a false no Info.plist deixa de perguntar.
5. Testers internos: grupo "Equipa", adicionar utilizadores do App Store Connect; disponível de imediato. Externos: link público; o primeiro build de cada versão vai a Beta App Review.
6. No iPhone: app TestFlight → aceitar → instalar. O feedback com screenshot chega ao App Store Connect.

Até segunda