Android Builds

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

你将学到什么

• 你将学习如何通过Capgo Native build上传你的应用
• 你将学习如何配置Capgo Native Build的凭证

前置条件

• 您需要有一个活跃的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构建。

• You will prepare the credentials for the later Capgo build
• 您将为后续__CAPGO_KEEP_0__构建准备凭据

您将在Play Store控制台上创建一个记录

Before we can start building the app with Capgo, we need to build the app manually with Android Studio.

1. 在我们开始使用__CAPGO_KEEP_0__构建应用之前，我们需要使用Android Studio手动构建应用。

   打开Android Studio bunx cap open android 打开 Android Studio 项目。

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

3. 选择 Android App Bundle 并点击 Next

创建密钥库

目前，您缺少密钥库文件。该文件用于签名您的应用程序，使 Google 知道是您构建了该应用程序。 要生成它，我们将使用 Android Studio 提供的 GUI 方法。 还有一个使用命令行的方法，但我们不会在本教程中介绍它。

1. 点击 Create new

2. 填写 Key Store 路径

   注意

   这 需要保存 - 将在后续使用

3. 设置密钥库密码

   注意

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

   注意

   请填写以下内容 __CAPGO_KEEP_0__ 请勿修改

4. 请填写剩余的表单

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

   

5. 点击 OK

手动构建的最后一步

1. 确保所有密钥库详细信息都已正确填写并点击 Next

2. 选择 release 在Android Studio中选择发布版本 Create

3. 在Android Studio中，构建成功后

   1. 点击
   2. 按钮 - 这将打开文件资源管理器，您应该在其中看到构建 locate 确保您可以在文件资源管理器中看到构建

4. 在Android Studio中，确保您可以在文件资源管理器中看到构建

在 Google Play Console 中创建应用

1. 前往 Google Play Console

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

3. 点击 Create app

4. 选择应用名称和语言

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

6. 接受条款和条件

   注意

   在接受条款之前，请确保您已阅读条款。

7. 点击 Create

创建内部测试组

现在您已经创建了应用程序，可以创建内部测试组了。由于我不会实际在 Play Store 上发布应用程序，因此我需要创建内部测试组。

注意

内部测试仍然是测试您在Play发行前发布的构建的最快方法。

如果您的开发者帐户是创建于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 Google Play Console 发布按钮

3. Google Play Console 创建新发布 Create new release

4. Google Play Console 上传 Upload

5. Google Play Console 选择 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 按钮
   2. 点击 install button
   3. 打开应用并确认它已成功下载

   注意

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

配置Capgo原生构建（Android）

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

要求	标志	描述	必需
存储库文件	--keystore <path>	您的文件路径 .jks/.keystore 用于签署 APK/AAB 的文件。	是
存储库别名	--keystore-alias <alias>	存储库内的密钥别名。	是
存储库密钥密码	--keystore-key-password <password>	__CAPGO_KEEP_0__（密钥的密码）如果密钥/存储密码匹配，则只需提供一个。	查看下面的注释
密钥库存储密码	--keystore-store-password <password>	__CAPGO_KEEP_0__（密钥库的密码）如果密钥/存储密码匹配，则只需提供一个。	查看下面的注释
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.

Keystore, keystore 密码, keystore 密钥密码, keystore 别名

如果您已经遵循了 手动构建指南,您应该已经生成了keystore。 如果您没有遵循指南，请遵循它们来生成keystore。

Google Play 服务账户

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

• 您 必须 成为开发者账户的拥有者 否则您将无法设置服务账户您需要创建一个新的Google Cloud项目（与您的Google Play账户分开）
• 让我们开始

前往

1. Google Cloud控制台 点击项目选择器

2. Google控制台项目选择器

3. 注意

   Note

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

   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 文件保存在安全的地方。 将用于后续步骤。 下载 JSON 文件 JSON 文件应该已经自动下载。您可以点击

11. 关闭窗口。 close Google Console 下载密钥

标题：授予 Play Store API 访问服务帐户

The newly created service account does not yet have access to the Play Store API. To grant it, head to the Play Store Console.

1. Google Play Console 选择正确的开发者帐户
2. Google Play Console 选择正确的开发者帐户
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. 确认用户已被邀请

保存凭据

You are now ready to save the credentials and run your first build. You can save the credentials using the following command:

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）

如果您已经完成 Keystore、Keystore密码、Keystore密钥密码、Keystore别名 和 Google Play服务帐号,您已经具备了CI/CD所需的所有内容。 本节仅介绍如何将这些值作为GitHub Actions机密和环境变量传递。

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

提示

GitHub 秘密应为单行值。 tr -d '\n' 从 base64 输出中移除行尾符。

2) 创建仓库秘密

在 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	内容 play_config_base64.txt

注意

如果密钥和存储密码相同，您只需提供其中一个 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仅通过环境变量发送凭据。您不需要提交签名文件或将它们作为工作流文件上传。

运行构建

恭喜！您现在已经准备好运行第一个构建了。

Run：

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

这将启动构建过程 🍾🥂

提交 Play 发布到审核

默认情况下，Android 发布构建将上传到 Google Play，并可以保持不活动状态，直到您在 Play Console 中完成发布。如果您的 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 changelog，作为备用选项 --store-release-notes-locale "locale=notes" entry 为该地区编写本地化的 Play changelog。Capgo 发送 Play 发布 completed; 如果在 Play Console 中启用了托管发布，Google 可以在获得批准后等待您的手动发布。

从 Android Builds 继续

如果您正在使用 Android Builds 来规划 CI/CD 自动化，连接它与 Capgo CI/CD 在 Capgo CI/CD 中为产品工作流程 Capgo Native Builds 在 Capgo Native Builds 中为产品工作流程 Capgo Integrations 为产品工作流程中的Capgo集成 CI/CD集成 为CI/CD集成中的实现细节 集成GitHub动作 为集成GitHub动作中的实现细节