Build e assinatura

No fim desta aula consegues

• Explicar o que uma assinatura digital prova numa app e o que acontece quando a chave se perde, no Android e no iOS.
• Criar um keystore, ligá-lo ao Gradle com key.properties fora do repositório e gerar um app bundle assinado.
• Distinguir versionName de versionCode e aplicar as regras das lojas ao version do pubspec.yaml.
• Configurar flavors dev e prod com application id e ícone diferentes, e injetar configuração de build com --dart-define.
• Descrever certificados, provisioning profiles e automatic signing no iOS.

Assinatura: porque existe (1 de 2)

• Assinar é calcular um resumo (hash) do pacote e cifrá-lo com uma chave privada. O certificado com a chave pública viaja dentro do pacote.
• Prova duas coisas: quem construiu a app (a mesma chave é o mesmo autor) e que o pacote não foi alterado depois de assinado.
• O sistema operativo só aceita uma atualização se o package name e a chave forem os mesmos da versão instalada. É isto que impede uma app falsa de substituir a tua.
• Não prova que a app é segura, nem que o código presta. Prova identidade e integridade, mais nada.
• Toda a app instalada num telemóvel está assinada, incluindo as de debug: o Flutter usa ~/.android/debug.keystore, gerado na primeira compilação, diferente em cada máquina.

Para os testes: a assinatura prova autoria e integridade; não prova qualidade nem segurança.

Assinatura: perder a chave (2 de 2)

Android: keystore, key.properties, signingConfigs

• Keystore (.jks): ficheiro com o par de chaves, protegido por palavra-passe. Cada chave lá dentro tem um alias. Cria-se uma vez com keytool.
• android/key.properties: quatro linhas com o caminho do keystore, o alias e as palavras-passe. O Gradle lê-o. Vai para o .gitignore.
• signingConfigs em android/app/build.gradle.kts: diz ao Gradle que o build type release assina com essa chave.
• Sem isto, flutter build appbundle assina com a chave de debug e a Play Console recusa o upload.
• Em CI, o keystore entra como secret em base64 e o key.properties é escrito no momento do build.

Para os testes: o keystore assina; o key.properties só diz onde ele está e como abri-lo. Nenhum dos dois entra no git.

APK vs AAB

Um AAB não se instala com adb install. Para testar localmente a partir de um bundle usa-se o bundletool da Google, ou gera-se também um APK.

iOS: certificados e provisioning profiles (1 de 2)

• Certificado de desenvolvimento: por programador, para correr no teu iPhone. Certificado de distribuição: por equipa, para TestFlight e App Store. Ambos emitidos pela Apple a partir de um pedido (CSR) e válidos um ano.
• A chave privada do certificado fica no Keychain do Mac que fez o pedido. Para outra máquina ou para CI exporta-se em .p12.
• App ID / bundle identifier: registado em developer.apple.com, em notação DNS invertida (pt.uac.tempoacores). As capacidades (push, associated domains) ficam-lhe associadas.
• Provisioning profile = certificado + App ID + lista de dispositivos (em desenvolvimento e ad hoc) + entitlements. Vai embutido no .ipa.
• Um Apple ID gratuito chega para correr no próprio iPhone: perfil de 7 dias, sem TestFlight nem loja. A conta paga custa 99 USD por ano.

iOS: bundle id e automatic signing (2 de 2)

• Automatically manage signing no Xcode cria certificados, App ID e perfis por ti. Chega para quase todos os projetos, incluindo o vosso.
• Assinatura manual só quando precisas de controlar o perfil: CI, extensões (widgets, notificações ricas), várias equipas. Nesse mundo usa-se fastlane match, que guarda os certificados cifrados num repositório privado.
• O bundle id é único no mundo e não muda depois de publicado. Escolhe-o bem à primeira.
• flutter build ipa gera o ficheiro .ipa; o upload faz-se com o Transporter ou com xcrun altool. Só em macOS.
• O versionamento é o mesmo que no Android: vem do pubspec.yaml, como vais ver a seguir.

Para os testes: no iOS quem assina a app que chega à loja é a Apple; o teu certificado de distribuição só te autoriza a fazer o upload.

Versionamento: version: 1.2.3+45

• O Flutter copia os dois valores para o Gradle (flutter.versionName, flutter.versionCode) e para o Xcode (Generated.xcconfig) em cada build. O pubspec é a fonte única.
• Na linha de comandos podes sobrepor: --build-name=1.2.4 --build-number=46. É o que o CI faz com o número da execução.
• Segue semver no nome: major quando partes compatibilidade, minor quando acrescentas, patch quando corriges.

Versionamento: regras das lojas

• Play: o versionCode é um inteiro que tem de ser estritamente maior do que qualquer um já carregado para a app, em qualquer track. Máximo 2 100 000 000. Não se reutiliza nunca.
• App Store: dentro da mesma versão (1.2.3) o build number tem de subir; o TestFlight recusa um build repetido. Uma versão nova pode recomeçar o build em 1, mas ninguém o faz.
• O nome de versão pode repetir-se entre uploads (vários builds da 1.2.3 em teste); o código nunca.
• No telemóvel, instalar um versionCode menor do que o instalado dá INSTALL_FAILED_VERSION_DOWNGRADE. É o mesmo mecanismo que impede que um utilizador seja "atualizado" para trás.
• Estratégia simples para o projeto: 1.0.0+N, com N a subir a cada build que sai do portátil para outra pessoa.

Para os testes: versionName é para humanos e pode repetir-se; versionCode é para a loja e nunca pode descer nem repetir.

Flavors e ambientes

• Porquê: a app de dev fala com a API de dev, a de prod com a de prod; as duas instalam-se lado a lado no mesmo telemóvel; o ícone diz qual é qual; a de prod não tem logs nem menus escondidos.
• Android: productFlavors no Gradle, com applicationIdSuffix (.dev) e source sets por flavor (src/dev/res) para ícone e nome.
• iOS: schemes e configurations (Debug-dev, Release-prod) com ficheiros .xcconfig. Mais trabalho manual; há packages que o automatizam.
• Flutter: flutter run --flavor dev. O nome do flavor tem de existir nas duas plataformas se compilas as duas.
• Dois ambientes chegam para o projeto. Em empresas vês dev, staging e prod, raramente mais.

Para os testes: um flavor muda a identidade da app (id, nome, ícone) e a configuração de build; não muda o código Dart.

--dart-define para configuração e segredos de build

• --dart-define=API_URL=https://... na linha de comandos e String.fromEnvironment('API_URL') no código. É uma constante de compilação: existe também bool.fromEnvironment e int.fromEnvironment.
• Com muitas chaves: --dart-define-from-file=env/prod.json. O ficheiro de prod vai para o .gitignore e para os secrets do CI.
• O valor entra no binário como texto. A ofuscação (--obfuscate) dificulta mas não impede que alguém o extraia de um APK. Serve para configuração e chaves de baixo risco (URL, chave de mapas com restrição por package), não para segredos que dariam acesso a dados.
• O segredo do grupo para a API do curso fica onde já está: obtido em runtime e guardado no flutter_secure_storage, como fizemos na aula 17.
• Flavor e dart-define combinam-se: o flavor muda a identidade da app, o dart-define muda o que o Dart lê.

Para os testes: --dart-define injeta valores em tempo de compilação; tudo o que entra no binário pode ser lido por quem o descompilar.

Assinar, versionar e separar ambientes

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

starter/ é a app Tempo Açores da aula 28 com TODOs numerados no build.gradle.kts, no pubspec.yaml e em lib/config/ambiente.dart. solucao/ tem o estado final, sem o keystore, claro.

1. Criar o keystore e o key.properties

1. Gera a chave, fora da pasta do projeto. Guarda as duas palavras-passe no gestor de palavras-passe do grupo.

   keytool -genkey -v -keystore ~/tempo-acores-upload.jks \
     -keyalg RSA -keysize 2048 -validity 10000 -alias upload

2. Escreve o key.properties dentro de android/, com o caminho absoluto do keystore.

   storePassword=a-tua-palavra-passe
   keyPassword=a-tua-palavra-passe
   keyAlias=upload
   storeFile=/Users/eu/tempo-acores-upload.jks

3. Protege os dois no git antes de fazeres qualquer commit.

   android/key.properties
   **/*.jks
   **/*.keystore

2. signingConfigs no build.gradle.kts

import java.util.Properties
import java.io.FileInputStream

val keystoreProperties = Properties()
val keystorePropertiesFile = rootProject.file("key.properties")
if (keystorePropertiesFile.exists()) {
    keystoreProperties.load(FileInputStream(keystorePropertiesFile))
}

android {
    // ...namespace, compileSdk, defaultConfig ficam como estão
    signingConfigs {
        create("release") {
            keyAlias = keystoreProperties["keyAlias"] as String
            keyPassword = keystoreProperties["keyPassword"] as String
            storeFile = keystoreProperties["storeFile"]?.let { file(it) }
            storePassword = keystoreProperties["storePassword"] as String
        }
    }
    buildTypes {
        release {
            signingConfig = signingConfigs.getByName("release")   // TODO 1: era "debug"
        }
    }
}

3. Gerar, instalar e verificar o release

1. App bundle para a loja. Fica em build/app/outputs/bundle/release/app-release.aab.

   flutter build appbundle --release

2. APK de release para instalar no telemóvel. Desinstala primeiro a versão de debug: a chave é outra e o Android recusa a atualização.

   flutter build apk --release
   adb uninstall pt.uac.tempoacores
   adb install build/app/outputs/flutter-apk/app-release.apk

3. Verifica quem assinou. O keytool lê o certificado de dentro do APK. Compara o SHA-256 com o do teu keystore.

   keytool -printcert -jarfile build/app/outputs/flutter-apk/app-release.apk
   keytool -list -v -keystore ~/tempo-acores-upload.jks -alias upload

4. Subir a versão, e o que acontece se não subires

name: tempo_acores
description: Previsão meteorológica para os Açores.
publish_to: 'none'

version: 1.0.1+2   # TODO 2: era 1.0.0+1

environment:
  sdk: ^3.5.0

• Instala o novo build por cima do anterior: funciona, porque versionCode 2 > 1 e a chave é a mesma.
• Volta a 1.0.1+1, compila e tenta instalar por cima do 2: INSTALL_FAILED_VERSION_DOWNGRADE. Na Play Console o equivalente é "Version code 1 has already been used".
• Sem tocar no pubspec: flutter build apk --build-name=1.0.1 --build-number=3.

5. Flavors dev e prod no Android

android {
    // ...
    flavorDimensions += "ambiente"
    productFlavors {
        create("dev") {
            dimension = "ambiente"
            applicationIdSuffix = ".dev"          // pt.uac.tempoacores.dev
            versionNameSuffix = "-dev"
            resValue("string", "app_name", "Tempo Açores DEV")
        }
        create("prod") {
            dimension = "ambiente"
            resValue("string", "app_name", "Tempo Açores")
        }
    }
}

• No AndroidManifest.xml, android:label="@string/app_name" passa a usar o valor do flavor.
• Ícone diferente: copia android/app/src/main/res/mipmap-* para android/app/src/dev/res/mipmap-* e troca as imagens. O source set do flavor sobrepõe-se ao main.
• Corre com flutter run --flavor dev. As duas apps ficam instaladas ao mesmo tempo, com nomes e ícones diferentes.

6. --dart-define para o URL da API

class Ambiente {
  // TODO 5: substituir o URL fixo por String.fromEnvironment
  static const apiUrl = String.fromEnvironment(
    'API_URL',
    defaultValue: 'https://api.pdm-daw.pt/v1',
  );
  static const nome = String.fromEnvironment('AMBIENTE', defaultValue: 'prod');
  static const isDev = nome == 'dev';
}

flutter run --flavor dev \
  --dart-define=AMBIENTE=dev --dart-define=API_URL=https://api-dev.pdm-daw.pt/v1
flutter build appbundle --flavor prod --dart-define-from-file=env/prod.json

• env/prod.json é um objeto JSON com as mesmas chaves. Entra no .gitignore; em CI vem de um secret.
• O ApiClient passa a receber Ambiente.apiUrl. Em dev mostra o nome do ambiente na AppBar para ninguém confundir os dois.

7. iOS, para quem tem Mac

1. Abre o projeto no Xcode com open ios/Runner.xcworkspace. Nunca o .xcodeproj: o workspace é o que tem os pods.
2. Runner → Signing & Capabilities. Marca Automatically manage signing e escolhe a tua equipa. Sem conta paga aparece "Personal Team" com o teu Apple ID.
3. Bundle identifier único: pt.uac.pdm.tempoacores.grupoN. O Xcode cria o App ID e o perfil sozinho.
4. Liga o iPhone e corre flutter run. No telemóvel, Definições → Geral → VPN e gestão de dispositivos → confiar no programador.
5. Limites da conta gratuita: o perfil expira em 7 dias, máximo 3 apps, sem push e sem TestFlight. flutter build ipa só com conta paga.

Até à próxima aula