Google Play 上架与签名打包

keytool -genkeypair -v \
  -keystore release.jks \
  -alias myapp \
  -keyalg RSA -keysize 4096 -validity 10000 \
  -storetype JKS   # 交互式输入密码与证书信息，有效期 10000 天

android {
    signingConfigs {
        create("release") {
            // 密钥信息从环境变量读取，绝不提交到仓库
            storeFile = file(System.getenv("KEYSTORE_PATH") ?: "release.jks")
            storePassword = System.getenv("KEYSTORE_PASSWORD")
            keyAlias = System.getenv("KEY_ALIAS")
            keyPassword = System.getenv("KEY_PASSWORD")
        }
    }
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            signingConfig = signingConfigs.getByName("release")
        }
    }
}

路径 A（推荐）：新应用直接用 Play App Signing
  1. Play Console 创建应用时选择「使用 Google 管理密钥」
  2. 上传用上传密钥签名的 AAB，Google 用应用签名密钥重签后分发

路径 B（存量应用迁移）：
  1. 生成新的上传密钥，导出现有应用签名密钥
  2. 在 Play Console 提交密钥迁移申请，之后用上传密钥签名所有版本

关键收益：上传密钥泄露可立刻轮换而不失去更新能力，
          应用签名密钥由 Google 保管，不会因本地硬盘损坏而丢失

./gradlew :app:bundleRelease        # 产出 app/build/outputs/bundle/release/app-release.aab
./gradlew :app:assembleRelease      # 产出 APK，用于第三方渠道或本地验证

android {
    defaultConfig {
        versionCode = 42            // 每次发布必须严格递增，Play 拒绝重复
        versionName = "2.4.0"       // 面向用户的语义化版本
    }
}

// 常见做法：用 CI 构建号自动生成 versionCode，避免人工冲突
val buildNumber = (System.getenv("BUILD_NUMBER") ?: "1").toInt()
android.defaultConfig.versionCode = 10000 + buildNumber

首次上架步骤：
  1. 创建应用：填写应用名、默认语言、应用类型（应用/游戏）、免费或付费
  2. 设置商品详情：应用图标（512x512）、特色图片（1024x500）、截图、描述
  3. 完成内容分级问卷：IARC 问卷，决定分级标签
  4. 填写数据安全表单：声明收集哪些数据、是否加密传输、是否可删除
  5. 声明目标受众与内容：是否面向儿童，是否含广告
  6. 上传 AAB 到测试轨道，验证后再推进到正式轨道并提交审核

关于「目标 API 级别」的硬要求：
  Play 要求新应用与更新每年跟进 targetSdk
  例如 2024 年 8 月 31 日起新应用需 targetSdk 34
  2025 年 8 月 31 日起新应用需 targetSdk 35
  未跟进的应用会被拒绝更新，存量应用可能被限制可见性

自查命令：检查构建产物中声明的 targetSdk
  ./gradlew :app:assembleRelease
  aapt2 dump badging app/build/outputs/apk/release/app-release.apk | grep targetSdkVersion

分阶段发布的典型节奏：
  第 1 天 1% 用户 → 看崩溃率与 ANR 率
  第 2 天 5% 用户 → 看核心指标与用户反馈
  第 3 天 20% 用户 → 看留存与转化
  第 4 天 50% 用户 → 第 5 天 100% 用户

任何一步异常都可以「暂停发布」或「回滚到上一版本」：
  暂停：停止继续放量，已升级用户不受影响
  回滚：需上传 versionCode 更高的旧功能版本，不能直接降级

android {
    buildTypes {
        release {
            isMinifyEnabled = true
            isShrinkResources = true
            proguardFiles(
                getDefaultProguardFile("proguard-android-optimize.txt"),
                "proguard-rules.pro"
            )
        }
    }
}

app/build/outputs/mapping/release/mapping.txt                    # mapping 文件位置
retrace app/build/outputs/mapping/release/mapping.txt crash.txt  # 用 retrace 还原崩溃栈

// AGP 8.x：自动上传 mapping 到 Play（需配置 Play 凭据）
android {
    buildTypes {
        release {
            // 与 Gradle Play Publisher 配合时通常由 GPP 处理
            // 单独使用时可通过 play 服务账号自动上传
        }
    }
}

bundletool build-apks --bundle=app-release.aab --output=app.apks \
  --ks=release.jks --ks-key-alias=myapp        # 生成 APK 集（含所有拆分的 APK）
bundletool install-apks --apks=app.apks        # 按设备配置安装，模拟 Play 的分发行为
bundletool get-size total --apks=app.apks --dimensions=ABI,SCREEN_DENSITY   # 估算下载体积

为什么必须本地验证：
  AAB 的拆分逻辑只在 Play 侧生效，本地 assembleRelease 出来的 APK
  与用户实际下载的 APK 不是同一份，典型问题只会在某个 ABI 或密度下暴露
  验证方式：用 install-apks 装到真机，或 get-size 看拆分是否符合预期

// app/build.gradle.kts
plugins {
    id("com.android.application")
    id("com.github.triplet.play") version "3.12.0"
}

play {
    // 服务账号 JSON，来自 Play Console 的 API 访问设置
    serviceAccountCredentials.set(file(System.getenv("PLAY_JSON_KEY") ?: "play-key.json"))
    track.set("internal")            // 目标轨道：internal / beta / production
    defaultToAppBundles.set(true)    // 默认上传 AAB
    userFraction.set(0.1)            // 分阶段发布：按百分比放量
    resolutionStrategy.set(com.github.triplet.gradle.play.ResolutionStrategy.AUTO)  // 自动递增版本号
}

./gradlew :app:publishReleaseBundle            # 发布到配置的轨道
./gradlew :app:publishReleaseBundle --track production --user-fraction 0.05   # 5% 分阶段
./gradlew :app:publishListing                  # 只更新商品详情，不发新版本

CI 流水线中的发布步骤：
  1. 拉取代码并检出发布 tag
  2. 用 CI Secret 注入 keystore 与 Play 服务账号 JSON
  3. ./gradlew :app:bundleRelease 构建 AAB
  4. ./gradlew :app:publishReleaseBundle --track internal 先发内测
  5. 归档 mapping.txt 与 AAB 到对象存储
  6. 人工确认后推进到 production 并设置 userFraction

注意：GPP 会调用 Play Developer API，服务账号需在 Play Console
      中授予「发布到测试轨道」与「管理正式版发布」权限。

// targetSdk 33 起：通知需要运行时权限
if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    launcher.launch(Manifest.permission.POST_NOTIFICATIONS)
}

// targetSdk 33 起：读取图片用细分权限替代 READ_EXTERNAL_STORAGE
val imagePermission = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.TIRAMISU) {
    Manifest.permission.READ_MEDIA_IMAGES
} else {
    Manifest.permission.READ_EXTERNAL_STORAGE
}

<!-- targetSdk 34 起：前台服务必须声明类型 -->
<service
    android:name=".SyncService"
    android:foregroundServiceType="dataSync"
    android:exported="false" />