android-playstore-setup

Android Play Store 设置

此技能通过 Fastlane 协调完成 Google Play Store 部署设置，并自动发布到内部测试轨道。

功能说明

范围： 仅部署到内部测试轨道（简化流程，便于快速测试）

使用 Fastlane 设置自动部署到 Play Store 所需的一切：

1. 扫描项目 - 分析项目并生成设置清单
2. Fastlane 设置 - 配置 Fastlane、supply 和 screengrab
3. 应用图标 - 生成并放置图标资源
4. 屏幕截图 - 自动截取屏幕截图
5. 商店商品详情 - 功能图片和元数据
6. 隐私政策 - 为 GitHub Pages 生成隐私政策
7. 版本管理 - 设置基于 Git 标签的版本控制
8. 签名配置 - 配置发布签名
9. 服务账号 - Play Store API 访问权限
10. GitHub Actions - 使用 Fastlane 的 CI/CD 工作流

前提条件

• Google Play Developer 账号（一次性支付 $25）
• Google Cloud Platform 账号（免费）
• Play Console 管理员访问权限
• 已在 Play Console 中预留的软件包名称

工作流概览

1. Scan → 2. Review → 3. Setup → 4. Deploy
   ↓          ↓          ↓          ↓
  📋        ✅         🔧         🚀

流程

步骤 1：扫描项目（仅分析）

运行 /devtools:android-playstore-scan

功能：

• 扫描 AndroidManifest.xml 和 build.gradle
• 检测 Health Connect、广告和分析功能
• 检查是否有隐私政策
• 生成预先填写好答案的 PLAY_CONSOLE_SETUP.md

输出： PLAY_CONSOLE_SETUP.md

操作： 查看生成的文件并处理其中的警告

---

步骤 2：生成隐私政策（如需要）

如果 PLAY_CONSOLE_SETUP.md 显示缺少隐私政策：

运行 /devtools:privacy-policy-generate

功能：

• 扫描项目以获取应用信息
• 检测 Health Connect 和第三方 SDK
• 提示填写开发者信息
• 生成 docs/privacy-policy.md
• 创建 GitHub Pages 设置指南

验证：

test -f docs/privacy-policy.md && echo "✓ Privacy policy created"

下一步： 启用 GitHub Pages（Settings → Pages → Source: docs/）

---

步骤 3：设置版本管理

运行 /devtools:version-management，并指定 platform=gradle

功能：

• 创建 scripts/version-manager.sh（核心）
• 创建 scripts/gradle-version.sh（Android 适配器）
• 创建含初始版本的 version.properties
• 更新 app/build.gradle.kts，使其从 version.properties 读取版本信息

验证：

./scripts/version-manager.sh latest
./scripts/gradle-version.sh generate patch

---

步骤 4：生成密钥库

运行 /devtools:android-keystore-generation

功能：

• 生成 production-release.jks（用于 CI/CD）
• 生成 local-dev-release.jks（用于本地测试）
• 创建包含凭据的 KEYSTORE_INFO.txt
• 更新 .gitignore

验证：

ls keystores/*.jks
cat keystores/KEYSTORE_INFO.txt

---

步骤 5：配置签名

运行 /devtools:android-signing-config

功能：

• 将签名配置添加到 app/build.gradle.kts
• 配置双来源凭据（环境变量 + gradle.properties）
• 更新本地 ~/.gradle/gradle.properties
• 为发布构建添加验证

验证：

./gradlew assembleRelease

---

步骤 6：配置 ProGuard（如尚未配置）

运行 /devtools:android-proguard-setup

功能：

• 使用安全的默认设置创建 app/proguard-rules.pro
• 启用代码混淆和资源缩减
• 根据需要添加特定于库的规则

验证：

grep "isMinifyEnabled = true" app/build.gradle.kts

---

步骤 7：设置 Fastlane

运行 /devtools:android-fastlane-setup

功能：

• 创建包含 fastlane 和 screengrab 的 Gemfile
• 创建含软件包名称的 fastlane/Appfile
• 创建含部署通道的 fastlane/Fastfile
• 创建用于自动截取屏幕截图的 fastlane/Screengrabfile
• 创建 fastlane/metadata/ 目录结构

验证：

bundle exec fastlane --version
bundle exec fastlane lanes

---

步骤 7a：生成应用图标

运行 /devtools:android-app-icon

功能：

• 分析项目以获取应用名称和颜色
• 生成包含 IconKitchen 操作说明的 docs/APP_ICON_SETUP.md
• 提供用于处理 IconKitchen 下载文件的辅助脚本
• 复制 mipmap 资源和 Play Store 图标

验证：

test -f fastlane/metadata/android/en-US/images/icon.png
file fastlane/metadata/android/en-US/images/icon.png | grep "512 x 512"

---

步骤 7b：设置截图自动化

运行 /devtools:android-screenshot-automation

功能：

• 将 screengrab 依赖项添加到 app/build.gradle.kts
• 创建包含所需权限的调试清单
• 创建用于自动截图的 ScreenshotTest.kt
• 创建用于清理状态栏的 DemoModeRule.kt

验证：

bundle exec fastlane screenshots
ls fastlane/metadata/android/en-US/images/phoneScreenshots/

---

步骤 7c：创建应用商店列表素材

运行 /devtools:android-store-listing

功能：

• 生成 docs/STORE_LISTING_GUIDE.md
• 创建元数据模板（标题、描述等）
• 提供功能图片生成脚本
• 指导用户创建素材

验证：

test -f fastlane/metadata/android/en-US/images/featureGraphic.png
wc -c fastlane/metadata/android/en-US/*.txt

---

步骤 8：创建部署工作流

运行 /devtools:android-workflow-internal

功能：

• 创建 .github/workflows/build.yml（仅用于 CI——在推送/PR 时运行）
• 创建 .github/workflows/release-internal.yml（使用 Fastlane 手动发布）
• 添加 Ruby 设置和 bundle 缓存
• 使用 bundle exec fastlane deploy_internal 进行部署
• 所有操作均固定到 SHA

验证：

test -f .github/workflows/build.yml
test -f .github/workflows/release-internal.yml
grep "bundle exec fastlane" .github/workflows/release-internal.yml

---

步骤 9：设置服务账号

运行 /devtools:android-service-account-guide

功能：

• 提供 Google Cloud 设置的分步指南
• 说明如何创建服务账号
• 创建 Play Console 设置文档

需要手动执行的步骤：

1. 在 Google Cloud 中创建服务账号
2. 下载 JSON 密钥
3. 在 Play Console 中授予权限
4. 将 JSON 添加到 GitHub Secrets，名称为 SERVICE_ACCOUNT_JSON_PLAINTEXT

---

步骤 10：将 Keystore 添加到 GitHub Secrets

从 keystores/KEYSTORE_INFO.txt 中获取信息，将以下机密添加到 GitHub：

# From KEYSTORE_INFO.txt, copy the base64 encoded keystore:
SIGNING_KEY_STORE_BASE64: <base64_string>
SIGNING_KEY_ALIAS: upload
SIGNING_STORE_PASSWORD: <password>
SIGNING_KEY_PASSWORD: <password>

---

步骤 11：验证 API 连接

运行 /devtools:android-playstore-api-validation

功能：

• 创建 scripts/validate-playstore.py
• 测试 Play Store API 连接
• 验证服务账号权限

验证：

python3 -m venv .venv
source .venv/bin/activate
pip install google-auth google-api-python-client
python3 scripts/validate-playstore.py /path/to/service-account.json com.example.app

---

步骤 12：首次手动上传（至关重要）

⚠️ 在 GitHub Actions 可以部署之前，必须手动上传首次发布版本。

为什么？

1. Google Play 要求首次手动上传，以完成应用商店列表
2. 你的生产 Keystore 将成为上传密钥
3. Play App Signing 会自动启用

步骤：

# 1. Build release bundle locally
./gradlew bundleRelease

# 2. Verify it's signed
jarsigner -verify -verbose app/build/outputs/bundle/release/app-release.aab

# 3. Manual upload via Play Console

在 Play Console 中：

1. 前往 Release → Internal testing
2. 点击 Create new release
3. 上传 app-release.aab
4. 完成应用商店列表（标题、描述、图标）
5. 完成应用内容声明
6. 发布到内部测试

**重要：**首次上传所用的 Keystore 必须与 GitHub Secrets 中配置的 Keystore 相同！

---

步骤 13：测试 Fastlane 部署

首次手动上传完成后：

# Push to main branch to trigger deployment
git add .
git commit -m "Setup Play Store deployment"
git push origin main

执行内容：

1. GitHub Actions 工作流启动
2. 运行单元测试
3. 构建发布包
4. 部署到内部测试轨道

**查看进度：**前往仓库 → Actions 选项卡

---

了解 Play App Signing

双密钥系统

密钥类型	用途	持有方	可以重置？
App Signing Key	为用户签署 APK	Google	否（永久）
Upload Key	验证你的上传内容	你	可以（通过 Play Console）

自动设置

对于 2021 年 8 月之后创建的应用，Play App Signing 会自动启用：

1. 首次上传：Google 生成应用签名密钥
2. 你的生产 Keystore = 上传密钥
3. Google 在分发前使用应用签名密钥重新签名

无需任何操作——即可正常使用！

---

最终验证清单

# Project files
✓ Fastlane configured (Gemfile, Fastfile, Appfile)
✓ Version management scripts in scripts/
✓ Keystores in keystores/ (gitignored)
✓ Privacy policy in docs/privacy-policy.md
✓ Metadata in fastlane/metadata/android/en-US/
✓ CI workflow in .github/workflows/build.yml
✓ Release workflow in .github/workflows/release-internal.yml

# Build verification
✓ ./gradlew assembleRelease succeeds
✓ Unit tests pass
✓ ProGuard enabled

# GitHub Secrets configured
✓ SERVICE_ACCOUNT_JSON_PLAINTEXT
✓ SIGNING_KEY_STORE_BASE64
✓ SIGNING_KEY_ALIAS
✓ SIGNING_STORE_PASSWORD
✓ SIGNING_KEY_PASSWORD

# Play Console
✓ First manual upload completed
✓ Internal testing track active
✓ Service account has permissions

# API validation
✓ scripts/validate-playstore.py passes

---

后续步骤

Beta/生产环境部署

内部测试正常运行后：

# Add beta track
/devtools:android-workflow-beta

# Add production track
/devtools:android-workflow-production

轨道信息

轨道	受众	审核时间	用途
Internal	最多 100 名测试人员	即时	快速测试，无需审核
Closed (Alpha)	受邀测试人员	< 24h	Beta 测试
Open (Beta)	任何人都可以加入	< 24h	公开 Beta 测试
Production	所有用户	1-7 天	正式发布

---

故障排除

API 验证中出现“找不到软件包”

• 确保应用已在 Play Console 中创建
• 确认软件包名称完全一致
• 完成首次手动上传

“上传密钥不匹配”

• 首次上传所用的密钥库 ≠ GitHub Secrets 中的密钥库
• 解决方法：前往 Play Console → 应用签名 → 请求重置上传密钥
• 使用正确的密钥库重新上传

服务账号出现“权限被拒绝”

• 在 Play Console 中授予“发布到正式版”权限
• 等待 5-10 分钟，让权限生效

GitHub Actions 部署失败

• 确认所有 GitHub Secrets 均设置正确
• 检查工作流日志，查看具体错误
• 确保已完成首次手动上传

---

总结

你已成功完成以下设置：

• ✅ 隐私政策（GitHub Pages 已就绪）
• ✅ 版本管理（基于 Git 标签）
• ✅ 发布签名（正式版 + 本地开发）
• ✅ Fastlane 部署自动化
• ✅ GitHub Actions CI/CD（内部测试轨道）
• ✅ Play Store API 连接

你的应用现已准备好进行持续集成和部署！

每次推送到 main 或提交 PR → 自动构建和测试（CI）✅ 手动触发工作流 → 版本管理 + 部署到内部测试轨道 🚀

所有检查都必须通过，才能将此技能标记为完成。

完成标准

只有在确认以下所有项目后，才能标记为完成：

✅ 服务账号设置

• 已在 Google Cloud 中创建服务账号
• 已下载 JSON 密钥并安全存储
• 已启用 Play Developer API
• 已将服务账号关联到 Play Console
• 已授予“发布”权限

✅ 商店元数据结构

• fastlane/metadata/android/en-US/ 目录已存在
• 至少已配置 en-US 区域设置
• 已创建元数据文件（标题、描述、更新日志）
• 已创建 docs/PLAY_STORE_TRACKS.md 文档

✅ API 验证

• scripts/validate-playstore.py 已存在
• 验证脚本运行成功
• 已确认 API 连接正常
• 已确认软件包访问权限

✅ 文档

• PLAY_CONSOLE_SETUP.md 已存在（项目根目录）
• GITHUB_SECRETS.md 已存在（如有需要）

总结报告

完成后，提供以下总结：

✅ Android Play Store Setup Complete!

🔐 Service Account:
  ✓ Created in Google Cloud
  ✓ JSON key downloaded
  ✓ Linked to Play Console
  ✓ Permissions granted

📝 Store Metadata:
  ✓ Structure created: fastlane/metadata/android/en-US/
  ✓ Locales configured
  ✓ Templates ready

✅ API Validation:
  ✓ Validation script created
  ✓ API connection tested
  ✓ Package access confirmed

📋 Next Steps:

  For GitHub:
    1. Add secrets (see GITHUB_SECRETS.md if it exists)
    2. Create "production" environment with reviewers

  For Deployment:
    1. Run: /devtools:android-playstore-publish
    2. Generate deployment workflows

⚠️  CRITICAL REMINDERS:
  - NEVER commit service account JSON to git
  - Store JSON key in password manager
  - Add all 5 secrets to GitHub before deploying
  - Wait 5-10 minutes after granting permissions

与其他技能集成

此技能是以下技能的前置条件：

• android-playstore-publishing - 使用服务账号进行部署
• android-playstore-pipeline - 完整的流水线设置

故障排除

如果任何技能失败：

1. 修复该技能中的具体问题
2. 重新运行该技能，直到完成
3. 继续执行其余技能
4. 运行最终验证

常见问题：

• 找不到服务账号 → 检查 Google Cloud 项目
• 权限被拒绝 → 授予“发布”权限
• API 验证失败 → 等待 5-10 分钟，让权限生效