安卓构建

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

What you will learn

• You will learn how to upload your app via Capgo Native build
• You will learn how to configure the credentials for 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构建。 手动构建有几个优势:

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

手动使用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

创建密钥库

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

1. 点击 Create new

2. 填写密钥库路径

   注意

   这是 必须保存 - 将在后续使用

3. 设置密钥库密码

   注意

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

   警告

   这是需要保存的 - 将在后续使用 填写表单的其余部分

4. 保持密钥别名不变（key0）

   1. Keep the Key Alias as is (key0)
   2. 填写证书详细信息。 我已经用假数据填写了它，但您应该用自己的数据填写它。

   

5. 点击 OK

完成手动构建

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

2. 选择 release Android Studio 选择发布构建变体 Create

3. Android Studio 选择发布构建变体

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

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

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

1. 前往 Google Play 控制台

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 按钮

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. 确认邀请已被接受，点击“在Google Play商店下载”

6. 安装应用

   1. 如果您以前使用Android Studio安装了应用，请点击 uninstall 按钮
   2. 点击 install 按钮
   3. 打开应用并确认已成功下载

   注意事项

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

配置Capgo原生构建（Android）

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

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

Google Play服务账户

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

• 您 context HTML text fragment from a longer Capgo UI string (parent key `you_definition`). Page/area: Capgo marketing website. Role: Long marketing or legal paragraph. Seen in: page disclaimer.astro, page return.astro. Message key `you_definition` (You Definition). 需要成为
• 开发者账户的

拥有者

1. 。否则，您将无法设置服务账户。 Google Cloud Console

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. 下载 JSON 文件 JSON 文件应该已经自动下载。您可以点击 close 关闭窗口。

授予 Play Store API 访问服务帐户

新创建的服务帐户尚未获得 Google Play 商店 API 的访问权限。要授予它，请前往 Google 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所需的所有内容。 本节仅介绍如何将这些值作为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.

使用环境变量在您的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 \
  --android-track production \
  --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"

注意

在 Android 上， --submit-to-store-review 默认为 生产 跟踪 release_status: completed 当您没有设置跟踪时， --android-track internal （或 alpha / beta）— 或设置 PLAY_STORE_TRACK 在 CI 中 — 以便将完成的发布保留在非生产跟踪中。使用 --android-release-status / PLAY_STORE_RELEASE_STATUS 当您需要一个不同的状态时 completed.

This requires the same Google Play service account setup as the normal upload path (PLAY_CONFIG_JSON 在CI或本地保存Android凭据) --store-release-name is used as the Google Play version_name. --store-release-notes is the fallback Play changelog, and each --store-release-notes-locale "locale=notes" entry writes a localized Play changelog for that locale. Capgo sends the Play release as completed __CAPGO_KEEP_0__发送Play发布 --android-release-status除非您覆盖

;如果在Play控制台启用了托管发布，Google仍然可以等待您的手动发布后审批

标题：继续从Android Builds 如果您正在使用 为计划 CI/CD 自动化，连接它 Capgo CI/CD 为产品工作流程在 Capgo CI/CD 中 Capgo 原生构建 为产品工作流程在 Capgo 原生构建 中 Capgo 集成 为产品工作流程在 Capgo 集成 中 CI/CD 集成 为产品工作流程在 Capgo Builder / 原生云构建产品页面中 GitHub Actions Integration GitHub 动作集成