渠道

实时更新渠道指向您的应用的特定 JS bundle 构建,该构建将与配置为监听该渠道更新的任何设备共享。当您在应用中安装 Capgo 实时更新 SDK时,配置为该渠道的任何原生二进制文件都将在应用启动时检查可用更新。您可以随时更改渠道指向的构建,如果需要,还可以回滚到以前的构建。

设备如何选择渠道(优先级)

当设备检查更新时,Capgo 按以下严格顺序决定使用哪个渠道(优先级从高到低):

1. 强制设备映射(仪表板) – 手动将特定设备 ID 固定到渠道。用于紧急调试或与单个真实用户的受控测试。这始终优先。
2. 云覆盖(每个设备)通过 setChannel() 或仪表板 – 当您的应用调用 setChannel()(通常在 QA/调试菜单中公开)或您在仪表板中更改设备的渠道时创建。用于在功能/PR 渠道之间切换的 QA 用户或重现用户问题。重新安装二进制文件不会清除它;删除设备条目会清除。
3. Capacitor 配置 defaultChannel(测试构建默认值) – 如果在 capacitor.config.* 中存在且不存在强制/覆盖,应用将从该渠道开始(例如 beta、qa、pr-123)。适用于 TestFlight/内部构建,以便测试人员自动进入预发布渠道。生产构建通常不设置此项。
4. 云默认渠道(主要路径 ~99% 的用户) – 如果您在仪表板中标记了默认渠道,所有正常最终用户(没有强制、没有覆盖、没有配置 defaultChannel)都将附加到这里。更改它以立即推出或回滚 - 无需新的二进制文件。如果您有平台特定的默认值(一个仅限 iOS,一个仅限 Android),每个设备都会落在与其平台匹配的默认值上。允许不设置云默认值;在这种情况下,设备必须匹配步骤 1-3 才能接收更新。

最佳实践:

• 将 1-3 视为异常/测试层;当您设置云默认值时,真实用户应该流入其中。如果您选择不设置,请明确考虑用户如何附加(通常通过配置中的 defaultChannel 或每个设备的覆盖)。
• 仅在您明确发送给测试人员的二进制文件中配置 defaultChannel。不设置它可使生产逻辑集中在仪表板中。
• 在生产中谨慎使用 setChannel() - 主要用于 QA 或有针对性的诊断。

如果渠道在本应选择时被禁用(iOS/Android 切换),选择过程将跳过它并继续向下列表。

总结:强制 > 覆盖 > 配置 defaultChannel > 云默认值。

默认渠道行为

设置云默认值是可选的,但它通常作为新设备的包罗万象路径。没有默认值时,只有匹配强制映射、覆盖或 Capacitor 配置中的 defaultChannel 的设备才会接收更新。当您确实选择标记默认值时,请记住这些模式:

• 单个默认值(最常见) – 如果渠道同时启用了 iOS 和 Android,它将成为唯一的默认值;任何没有覆盖的设备都将附加到这里。
• 平台特定默认值 – 如果您按平台拆分渠道(例如,仅启用 iOS 的 ios-production 和仅启用 Android 的 android-production),请将每个标记为其平台的默认值。iOS 设备转到 iOS 默认值,Android 设备转到 Android 默认值。

请记住,云默认值和 capacitor.config.* 中的 defaultChannel 都占据相同的决策层。如果您设置了云默认值,则无需在 Capacitor 配置中复制该值 - 为生产构建保留 defaultChannel 为空。为您有意发送给测试人员或 QA 的二进制文件保留 defaultChannel,当您希望他们从非生产渠道开始时,即使云默认值不同。

您可以随时在仪表板中更改默认值。当您交换默认值时,新设备立即遵循新路由,现有设备在下次签入时遵循正常优先级规则。

设置渠道

在入门期间,您创建第一个渠道(大多数团队将其命名为”Production”),但没有锁定 - 您可以随时重命名或删除任何渠道。要稍后添加其他渠道:

1. 转到 Capgo 仪表板的”渠道”部分
2. 点击”新建渠道”按钮
3. 输入渠道名称并点击”创建”

渠道名称可以是您喜欢的任何名称。常见策略是将渠道与您的开发阶段匹配,例如:

• Development - 用于在本地设备或模拟器上测试实时更新
• QA - 供您的 QA 团队在更广泛发布之前验证更新
• Staging - 在类生产环境中进行最终测试
• Production - 用于最终用户从应用商店接收的应用版本

在您的应用中配置渠道

创建渠道后,您需要配置应用以监听适当的渠道。在此示例中,我们将使用 Development 渠道。

打开您的 capacitor.config.ts(或 capacitor.config.json)文件。在 plugins 部分下,可选择为测试构建(内部/QA)设置 defaultChannel。对于生产构建,最好省略它,以便设备使用云默认值,除非明确覆盖。

import { CapacitorConfig } from '@capacitor/cli';

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // 对于 QA/TestFlight 构建 - 测试人员自动从 Development 渠道开始。
      defaultChannel: 'Development',
      // 生产构建通常省略此项,以便用户附加到云默认渠道。
    },
  },
};

接下来,构建您的 Web 应用并运行 npx cap sync 将更新的配置文件复制到您的 iOS 和 Android 项目。如果您跳过此同步步骤,您的原生项目将继续使用它们之前配置的任何渠道。

警告

渠道选择顺序:强制 > 覆盖(setChannel / 仪表板)> 配置 defaultChannel > 云默认值。

仅在测试/内部构建中使用 defaultChannel;在生产中省略它,以便用户遵循云默认值(设置时)而不是在原生配置中复制路由。

您仍然可以强制(固定)设备或稍后应用覆盖 - 这些立即取代配置值。

渠道名称区分大小写。

渠道选项和策略

渠道有几个选项可以控制谁可以接收更新以及如何传递更新。下面是最重要的选项。您可以从 Web 应用、CLI 或公共 API 配置这些选项。

• 默认渠道:可选择标记新设备附加到的渠道或平台特定渠道。有关路由场景,请参阅”默认渠道行为”。
• 平台过滤器:按渠道启用或禁用向 iOS 和/或 Android 设备的交付。
• 禁用原生下的自动降级:防止在设备的原生应用版本比渠道的 bundle 新时发送更新(例如,设备在 1.2.3 上而渠道有 1.2.2)。
• 允许开发构建:允许更新到开发构建(对测试有用)。
• 允许模拟器设备:允许更新到模拟器/仿真器(对测试有用)。
• 允许设备自我分配:允许应用在运行时使用 setChannel 切换到此渠道。如果禁用,setChannel 将失败此渠道。

禁用自动更新策略

使用此选项限制渠道自动交付的更新类型。选项:

• major: 阻止跨主要更新(0.0.0 → 1.0.0)。仍允许次要和补丁更新。
• minor: 阻止跨次要更新(例如,1.1.0 → 1.2.0)和主要更新。仍允许补丁更新。注意:不会阻止 0.1.0 → 1.1.0。
• patch: 非常严格。仅允许在相同主要和次要版本内增加补丁版本。示例:0.0.311 → 0.0.314 ✅,0.1.312 → 0.0.314 ❌,1.0.312 → 0.0.314 ❌。
• metadata: 要求每个 bundle 上有最小更新版本元数据。通过 CLI 使用 --min-update-version 或 --auto-min-update-version 配置。如果缺失,渠道被标记为配置错误,更新将被拒绝,直到设置。
• none: 根据 semver 兼容性允许所有更新。

在 /docs/cli/commands/#disable-updates-strategy 的禁用更新策略中了解更多详细信息和示例。

示例(CLI):

# 阻止 Production 渠道上的主要更新
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# 允许设备自我分配到 Beta 渠道
npx @capgo/cli@latest channel set beta com.example.app --self-assign

将 Bundle 分配给渠道

要部署实时更新,您需要上传新的 JS bundle 构建并将其分配给渠道。您可以使用 Capgo CLI 一步完成:

npx @capgo/cli@latest bundle upload --channel=Development

这将上传您构建的 Web 资源,并将新 bundle 设置为 Development 渠道的活动构建。任何配置为监听该渠道的应用都将在下次检查更新时接收更新。

您还可以从 Capgo 仪表板的”Bundles”部分将构建分配给渠道。点击构建旁边的菜单图标,然后选择”分配到渠道”以选择该构建的渠道。

Bundle 版本控制和渠道

值得注意的是,Capgo 中的 bundle 对您的应用是全局的,而不是特定于单个渠道的。同一 bundle 可以分配给多个渠道。

在对 bundle 进行版本控制时,我们建议使用语义版本控制 semver,并为特定于渠道的构建使用预发布标识符。例如,beta 版本可能被版本化为 1.2.3-beta.1。

这种方法有几个好处:

• 它清楚地传达了构建之间的关系。1.2.3-beta.1 显然是 1.2.3 的预发布版本。
• 它允许跨渠道重用版本号,减少混淆。
• 它启用清晰的回滚路径。如果您需要从 1.2.3 回滚,您知道 1.2.2 是之前的稳定版本。

以下是您如何将 bundle 版本与典型渠道设置对齐的示例:

• Development 渠道:1.2.3-dev.1、1.2.3-dev.2 等。
• QA 渠道:1.2.3-qa.1、1.2.3-qa.2 等。
• Staging 渠道:1.2.3-rc.1、1.2.3-rc.2 等。
• Production 渠道:1.2.3、1.2.4 等。

使用带有预发布标识符的 semver 是推荐的方法,但不是严格要求的。关键是找到一个版本控制方案,清楚地传达构建之间的关系,并与您团队的开发流程保持一致。

回滚实时更新

如果您部署的实时更新引入了错误或需要撤销,您可以轻松回滚到以前的构建。从仪表板的”渠道”部分:

1. 点击您想要回滚的渠道名称
2. 找到您想要恢复到的构建并点击皇冠图标
3. 确认操作

所选构建将立即再次成为该渠道的活动构建。应用将在下次检查更新时接收回滚的版本。

自动化部署

对于更高级的工作流程,您可以将实时更新部署自动化为 CI/CD 管道的一部分。通过将 Capgo 集成到您的构建过程中,您可以在推送到某些分支或创建新版本时自动上传新 bundle 并将其分配给渠道。

查看 CI/CD 集成文档,了解有关自动化 Capgo 实时更新的更多信息。

部署到设备

现在您了解了渠道,您已准备好开始将实时更新部署到真实设备。基本流程是:

1. 在您的应用中安装 Capgo SDK
2. 配置应用以监听您想要的渠道
3. 上传构建并将其分配给该渠道
4. 启动应用并等待更新!

有关更详细的演练,请参阅部署实时更新指南。祝您更新愉快!

高级渠道使用:用户细分

渠道不仅可以用于开发阶段。它们是用户细分的强大工具,可实现以下功能:

• 针对不同用户层级的功能标志
• A/B 测试
• 逐步功能推出
• Beta 测试程序

在我们的指南中了解如何实现这些高级用例:如何按计划和渠道细分用户以实现功能标志和 A/B 测试。