Android Builds

使用 Capgo 专属基础设施构建和提交 Android 应用到 Google Play 商店。

您将要学习的内容

• 您将学习如何通过 Capgo 原生构建上传您的应用
• 您将学习如何配置 Capgo 原生构建的凭据

前提条件

• 您需要有一个活跃的Google开发者账户
• 您需要安装Android Studio
• 您的应用必须能够在Android Studio中成功构建

注意

我将在教程中使用以下应用 https://github.com/Cap-go/capgo-native-build-tutorial-app

推荐：自动注册

您不需要自己来做这些事情。Capgo的注册过程会为您创建和配置Android签名凭证（keystore + Google Play服务帐户）— 这是推荐的路径：

bunx @capgo/cli@latest build init --platform android

以下的手动指南仅适用于那些希望自己设置凭证或想了解Capgo在幕后做了什么的人。

第一个手动构建

在我们开始使用Capgo构建应用之前，我们应该首先设置它，并手动完成第一个Android构建。 手动构建有几个优势：

• 您将为后续Capgo构建准备凭证
• 您将在Play Store控制台上创建一个记录

在 Android Studio 中手动构建应用

在使用 Capgo 构建应用之前，我们需要先在 Android Studio 中手动构建应用

1. 打开 Android Studio

   运行 bunx cap open android 以打开 Android Studio 项目

2. 点击 Build -> Generate Signed App Bundles / APKs

3. 选择 Android App Bundle 并点击 Next

创建一个 Keystore

您当前缺少密钥库文件。该文件用于签署您的应用程序，Google 可以通过它确定该应用程序是由您开发的。 要生成它，我们将使用 Android Studio 提供的 GUI 方法。 也可以使用命令行来实现，但本教程中不会涵盖此方法。

1. 点击 Create new

2. 填写密钥库路径

   注意

   请记住 它将用于后续操作 设置密钥库密码

3. IS TO BE SAVED

   注意

   我建议使用相同的密码来保护密钥库和密钥别名。

   警告

   这个 需要保存 - 将在后续步骤中使用

4. 填写剩余的表单

   1. 保持密钥别名不变 (key0)
   2. 填写证书详细信息。 我已经填写了假数据，但您应该填写自己的详细信息。

   

5. 点击 OK

手动构建的最后一步

1. 确保所有 keystore 详情都已正确填写并点击 Next

2. 选择 release 构建变体并点击 Create

3. 构建成功后，您应该看到以下屏幕

   1. 此弹出窗口表示构建成功。
   2. 点击 locate 按钮 - 这将打开文件浏览器，您应该在其中看到构建。

4. 确保您可以在文件浏览器中看到构建

在 Google Play 商店控制台创建应用

1. 前往 Google Play 控制台

2. 选择正确的开发者账户

3. 点击 Create app

4. 选择应用名称和语言

5. 选择应用类别并确定应用是否收费或免费

6. 接受条款和条件

   注意

   确保在接受条款和条件之前阅读它们。

7. 点击 Create

创建内部测试组

现在你已经创建了应用，你可以创建一个内部测试组。由于我不会实际在Play Store发布应用，所以我需要创建一个内部测试组。

注意

内部测试仍然是测试你在Play Store发布的构建前进行快速测试的最快方法，直到真正的发布。

如果你的开发者账户是从2023年11月13日后创建的个人账户，内部测试 不 替代生产访问的关闭测试要求。你仍然需要一个至少有12名参与者在14天内连续测试的关闭测试。

1. 前往 internal testing 点击 Test and release -> Testing -> Internal testing

   

2. 点击 Testers

3. 点击 Create email list

4. 命名邮件列表

5. 添加测试者邮箱

6. 按 Enter 并点击 Save

7. 点击 Create group

8. 确保新列表已选中并点击 Save

上传应用到内部测试组

您已创建内部测试组后，可以上传应用到内部测试组。

1. 前往 Test and release -> Testing -> Internal testing

2. 点击 Releases 按钮

3. 点击 Create new release

4. 点击 Upload

5. 选择 AAB 文件

   注意

   确保您选择使用 Android Studio 手动构建的 AAB 文件。如果此文件不使用将用于 Capgo 构建的同一.keystore，则 Capgo 原生构建将失败。

6. 等待 AAB 文件上传

7. 点击 Next

8. 修复错误

   我个人认为，目前这个阶段我看到这个错误

   

   这是因为我还没有验证我的手机号码。 我会做到这一点并继续教程。

9. 点击 Save and publish 这将发布应用程序到内部测试组

10. 确认发布

11. 确保应用程序已发布

12. 获取临时应用程序名称

接受内部测试小组的邀请

已将应用程序上传到内部测试小组，您可以接受内部测试小组的邀请

1. 前往 Test and release -> Testing -> Internal testing

2. 点击 Testers

3. 点击 Copy link

4. 将链接发送到您的手机，打开浏览器并点击 Accept

5. 确认邀请已被接受并点击“在Play Store下载它”

6. 安装应用

   1. 如果您在使用 Android Studio 之前已经安装了应用，点击 uninstall __CAPGO_KEEP_0__
   2. 点击 install __CAPGO_KEEP_0__
   3. 打开应用并确认它已成功下载

   注意

   如果您无法在Play Store中看到应用程序，请确保您在Play Store中选择了正确的账户。

配置Capgo原生构建（Android）

现在，您已经准备好开始Capgo原生构建的设置了。祝贺！

要求	标志	描述	必需
存储库文件	--keystore <path>	您的文件路径 .jks/.keystore 用于签署APK/AAB的文件。	是
密钥库别名	--keystore-alias <alias>	密钥库内的密钥别名。	是
密钥库密码	--keystore-key-password <password>	密钥密码。如果密钥库密码与密钥密码匹配，可以只提供一个。	请查看下面的注释
密钥库密码	--keystore-store-password <password>	密钥库密码。如果密钥库密码与密钥密码匹配，可以只提供一个。	请查看下面的注释
Google Play服务账户	--play-config <path>	Play Store上传的JSON服务账户文件。	是

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

注意

如果密钥和存储密码相同，请提供其中一个 --keystore-key-password 或 --keystore-store-password.

密钥库、密钥库密码、密钥库密钥密码、密钥库别名

如果您已经遵循了 手动构建指南，您应该已经生成了密钥库。 如果您没有遵循指南，请遵循指南生成密钥库。

Google Play服务账户

生成Google Play服务账户是一个手动且复杂的过程。 然而，这是必须的才能将应用程序上传到Google Play。请记住以下几点:

• 您 必须 是 开发者账户的所有者
• 。否则，您将无法设置服务账户。

您需要创建一个新的Google Cloud项目（与您的Google Play账户分开）

1. 开始吧。 前往

2. 点击项目选择器

3. 如果您已经有一个项目，请选择它。否则，请创建一个新项目：

   注意

   以下截图仅供参考 - 请为您的项目选择一个合适的名称。

   1. 点击 New project
   2. 为您的项目命名并点击 Create
   3. 确保您在正确的项目中

4. 让我们点击搜索栏并搜索 service accounts 并点击它

5. 让我们点击 Create service account

6. 填写服务账户的表单并点击 Done

   1. 我建议将名称设置为 Capgo Native Build Service Account
   2. 对于服务账户 ID，我建议将其设置为 capgo-native-build-service-acc
   3. 对于描述，您不必填写，但我建议填写 Allows Capgo Native Build to build and submit the app to the Play Store

   

7. 点击新创建的服务账户 您现在应该在列表中看到新创建的服务账户。点击它。

   注意

   将此电子邮件地址复制下来，稍后会需要它。

8. 点击 Keys 选项卡

9. 点击 Add Key 并 Create new key

10. 点击 JSON 并 Create

    注意

    点击 Create 会创建一个新的密钥并下载 JSON 文件到您的本地机器上。

    您需要将 JSON 文件保存在安全的地方。它 将 会

11. 被用来 close 下载 JSON 文件 JSON 文件应该已经自动下载了。您可以点击

Granting Play Store API access to the service account

新创建的服务帐户尚未获得Play商店的访问权限 API. 为授予它，请前往Play商店控制台。

1. 前往 Google Play 控制台
2. 选择正确的开发者帐户
3. 点击 Users and permissions
4. 点击 Invite new users
5. 复制服务帐户的电子邮件地址
6. 前往 Account permissions 并授予最少的必要权限：
   • 在 App permissions，授予您的应用程序访问权限。
   • 在 Releases，启用 Create, edit, and roll out releases.
   • 如果您的工作流程使用Play App Signing，启用相关签名权限。
   • 如果您不确定，请使用 Admin 仅在设置期间使用，然后在之后减少权限。
7. 点击 Invite user
8. 确认邀请
9. 确认用户已被邀请

保存凭据

您现在准备好保存凭据并运行第一个构建。 您可以使用以下命令保存凭据：

bunx @capgo/cli@latest build credentials save --platform android \
  --keystore ./path/to/keystore.jks \
  --keystore-alias "your-alias" \
  --keystore-key-password "key-password" \
  --keystore-store-password "store-password" \
  --play-config ./play-store-service-account.json

CI/CD 设置 (GitHub Actions)

如果您已经完成 存储库、存储库密码、存储库密钥密码、存储库别名 和Google Play服务帐号 您已经拥有CI/CD所需的所有内容。 本节仅介绍如何将这些值传递为__CAPGO_KEEP_0__ Actions机密和环境变量。, you already have everything needed for CI/CD. This section only covers how to pass those values as GitHub Actions secrets and environment variables.

标题：1) 将凭据文件转换为单行base64

# Android keystore (.jks or .keystore)
base64 -i ./path/to/keystore.jks | tr -d '\n' > keystore_base64.txt

# Google Play service account JSON
base64 -i ./play-store-service-account.json | tr -d '\n' > play_config_base64.txt

__CAPGO_KEEP_0__机密应为单行值。

GitHub secrets should be single-line values. tr -d '\n' 2) 创建仓库机密

targetLanguage

In GitHub > Repository > Settings > Secrets and variables > Actions, 添加：

密钥名称	值
CAPGO_TOKEN	您的 Capgo API token
APP_ID	您的 Capgo 应用程序 ID（例如： com.example.app)
ANDROID_KEYSTORE_FILE	内容 keystore_base64.txt
KEYSTORE_KEY_ALIAS	密钥库别名 密钥库、密钥库密码、密钥库密钥密码、密钥库别名
KEYSTORE_KEY_PASSWORD	密钥库密钥密码
KEYSTORE_STORE_PASSWORD	密钥库存储密码
PLAY_CONFIG_JSON	Content of play_config_base64.txt

Note

如果密钥和存储密码相同，您只需提供一个即可 KEYSTORE_KEY_PASSWORD 或 KEYSTORE_STORE_PASSWORD.

3) 在您的GitHub Actions工作流中使用环境变量

.github/workflows/android-build.yml

name: Android Cloud Build

on:
  workflow_dispatch:
  push:
    branches: [main]

jobs:
  android-build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: oven-sh/setup-bun@v2
        with:
          bun-version: latest
      - name: Request Android build with Capgo
        run: bunx @capgo/cli@latest build request ${{ secrets.APP_ID }} --platform android
        env:
          CAPGO_TOKEN: ${{ secrets.CAPGO_TOKEN }}
          ANDROID_KEYSTORE_FILE: ${{ secrets.ANDROID_KEYSTORE_FILE }}
          KEYSTORE_KEY_ALIAS: ${{ secrets.KEYSTORE_KEY_ALIAS }}
          KEYSTORE_KEY_PASSWORD: ${{ secrets.KEYSTORE_KEY_PASSWORD }}
          KEYSTORE_STORE_PASSWORD: ${{ secrets.KEYSTORE_STORE_PASSWORD }}
          PLAY_CONFIG_JSON: ${{ secrets.PLAY_CONFIG_JSON }}

提示

通过此设置，CI仅通过环境变量发送凭据。您不需要提交签名文件或将它们上传为工作流文件。

运行构建

恭喜！您现在可以运行第一个构建了。

运行：

bunx @capgo/cli@latest build request com.example.app --platform android

这将启动构建过程

提交 Play 发布到审核

默认情况下，Android发布构建将上传到Google Play并保持不活动状态，直到您在Play控制台完成发布。如果您的CI发布应该自动提交Play发布，请传递 --submit-to-store-review 与发布构建：

npx @capgo/cli@latest build request com.example.app \
  --platform android \
  --build-mode release \
  --submit-to-store-review \
  --store-release-name "1.2.3" \
  --store-release-notes "General improvements" \
  --store-release-notes-locale "en-US=General improvements" \
  --store-release-notes-locale "nl-NL=Algemene verbeteringen" \
  --store-release-notes-locale "fr-FR=Ameliorations generales"

需要与正常上传路径相同的Google Play服务帐户设置（PLAY_CONFIG_JSON 在CI或本地保存Android凭据。 --store-release-name 用作Google Play发布名称。 --store-release-notes 是Play的回退日志， --store-release-notes-locale "locale=notes" 每个条目为该区域写入本地化的Play日志。Capgo发送Play发布为 completed;如果在Play控制台启用了托管发布，Google仍然可以等待您的手动发布后审批。

从Android Builds继续

如果您正在使用 Android Builds 来规划CI/CD自动化，连接它 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 原生构建 为产品工作流程在 Capgo 原生构建 中 Capgo 集成 为产品工作流程在 Capgo 集成 中 CI/CD 集成 CI/CD 集成的实现细节 GitHub 动作集成 for the implementation detail in GitHub Actions Integration.