频道

当您在应用程序中安装__CAPGO_KEEP_0__实时更新__CAPGO_KEEP_1__时，任何配置为监听该频道的设备都会检查可用更新。您可以随时更改频道指向的构建，并且也可以回滚到以前的构建。 install the Capgo Live Updates SDK 在应用程序中安装__CAPGO_KEEP_0__实时更新__CAPGO_KEEP_1__时，任何配置为监听该频道的本机二进制文件将在应用程序启动时检查可用更新。您可以随时更改频道指向的构建，并且也可以回滚到以前的构建。

Channels 不提供保密性

Channels 控制更新的可用性，而不是 bundle 的秘密。即使一个 channel 是私有的或自赋值被禁用，任何未加密的 bundle 上传到 Capgo 也应该被视为一个公共资产，交付给客户端。加密保护了更新的传递路径和真实性，但仍然可以通过足够的努力从分发的应用中逆向工程，因为公共密钥是客户端的一部分。见 Live Update 加密 了解更多信息。

设备如何选择一个 channel (优先顺序)

当设备检查更新时，Capgo 根据以下严格顺序（最高优先级）决定使用哪个 channel：

1. 强制设备映射 (Dashboard) – 手动将一个特定的设备 ID 映射到一个 channel。用于紧急调试或受控测试。
2. Cloud 强制 (per-device) 通过 Dashboard 或 API – 当您在控制台或 API 中更改设备的 channel 时创建。用于 QA 用户在特征 / PR channel 之间切换或重现用户问题。重新安装二进制文件不会清除它；删除设备条目会清除它。

立即频道切换

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始（取决于您的主要版本）， （取决于您的主要版本）， setChannel() 它与后端通信， 验证 该频道是否允许（检查是否为该频道启用自我赋值），然后在设备上 存储该频道 。这意味着新的频道立即生效 defaultChannel下一次更新检查时—无需等待复制。 __CAPGO_KEEP_0__ __CAPGO_KEEP_0__

之前 setChannel() API

新行为仅从后端读取（用于验证）并在本地存储，使频道切换立即生效。 注意：

即使频道在本地设置后被禁止，后端仍会在更新检查期间验证频道，因此安全性得到维护。 When channel changes are made via the Dashboard or API, there is still a replication lag of up to 2 minutes before all edge servers reflect the change. For instant channel switching, use setChannel() 通过Dashboard或code进行的频道更改仍然存在2分钟的复制延迟，直到所有边缘服务器反映了更改。要实现即时频道切换，请

3. Capacitor defaultChannel 从您的应用程序__CAPGO_KEEP_0__—它与后端验证，然后在本地设置频道以立即生效。 __CAPGO_KEEP_0__配置 capacitor.config.* (测试构建默认值) beta, qa, pr-123– 如果在__CAPGO_KEEP_0__中存在且无强制/覆盖存在，应用程序将在此频道启动（例如，）。
4. Cloud Default Channel (primary path ~99% 的用户) – 如果您在控制台中标记了一个默认频道，所有正常用户（无强制、无覆盖、无配置 defaultChannel）都会附着在这里。立即更改它以进行发布或回滚—无需新二进制文件。如果您有平台特定的默认值（例如，一个 iOS-only、一个 Android-only、一个 Electron-only），每个设备都会在其平台匹配的默认值下。未设置云默认值是允许的；在这种情况下，设备必须匹配步骤 1–3 才能接收更新。

最佳实践：

• 将 1–3 视为异常/测试层；当您设置一个云默认值时，真正的用户应该流入它。如果您选择不设置一个，请务必明确用户如何附着（通常通过 defaultChannel 在配置或设备级别的覆盖中）。
• 仅在您明确向测试者分发的二进制文件中配置。 defaultChannel 在生产环境中使用
• 谨慎—主要用于 QA 或目标诊断。 setChannel() 如果一个频道在平台上被禁用（iOS/Android/Electron 切换）而它将否则被选择，选择过程会跳过它并继续下一项。

摘要： 强制 > 覆盖 > 配置

> 云默认值。 defaultChannel Best practice: Treat 1–3 as exception / testing layers; when you set a cloud default, real users should flow into it. If you choose not to set one, be deliberate about how users attach (typically via in config or per-device overrides).

默认频道行为

设置云端默认值是可选的，但通常作为新设备的通用路径。没有一个，仅匹配强制映射、覆盖或__CAPGO_KEEP_0__配置中的设备才会接收更新。当您选择标记默认值时，请记住这些模式： defaultChannel in the Capacitor config will receive updates. When you do choose to mark defaults, keep these patterns in mind:

• – 如果频道启用了iOS、Android和Electron，成为唯一的默认值；任何设备没有覆盖项都会附加到这里。 平台特定默认值
• – 如果您按平台分离频道（例如 仅启用iOS ios-production 仅启用Android android-production 仅启用Electron electron-production 记住云端默认值和

平台特定默认值 defaultChannel In __CAPGO_KEEP_0__ 中，生产环境和测试环境都占据同一决策层。如果您设置了云端的默认值，那么您就不需要在 __CAPGO_KEEP_0__ 配置中重复该值—留空 capacitor.config.* both occupy the same decision layer. If you set a cloud default, you don’t need to duplicate the value in your Capacitor config—leave defaultChannel 用于您希望测试人员或QA在非生产渠道上启动的二进制文件，即使云端的默认值不同。 defaultChannel 您可以随时在控制台中更改默认值。当您切换默认值时，新设备立即遵循新的路由，现有设备在下一次检查时将遵循正常的优先级规则。

设置通道

标题：设置通道

前往 __CAPGO_KEEP_0__ 控制台的“通道”部分

1. Go to the “Channels” section of the Capgo dashboard
2. 输入通道名称并点击“创建”
3. 通道名称可以是您喜欢的任何内容。一个常见的策略是将通道与开发阶段匹配，例如：

__CAPGO_KEEP_0__

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

配置应用中的通道

创建了您的通道后，您需要配置应用以监听适当的通道。在本例中，我们将使用 Development __CAPGO_KEEP_0__.

打开您的 capacitor.config.ts (或 capacitor.config.json)文件。 在 plugins 部分下， facultatively 设置 defaultChannel 用于测试构建 用于生产构建，建议省略以使设备使用 Cloud Default，除非显式覆盖。 复制到剪贴板

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

const config: CapacitorConfig = {
  plugins: {
    CapacitorUpdater: {
      // For a QA/TestFlight build – testers start on the Development channel automatically.
      defaultChannel: 'Development',
      // Production builds usually omit this so users attach to the Cloud Default channel.
    },
  },
};

将更新的配置文件复制到您的 iOS、Android 和 Electron 项目中。如果您跳过此同步步骤，则您的本机项目将继续使用它们之前配置的通道。 npx cap sync 注意

通道选择顺序：强制 > 覆盖（

/控制台）> 配置setChannel > Cloud Default。 defaultChannel 使用

Channel selection order: Force > Override ( defaultChannel 仅在测试/内部构建中可用; 在生产环境中请勿包含，以便用户遵循 Cloud Default (当设置时) 而不是在本机配置中重复路由。

您仍然可以强制 (固定) 设备或稍后应用一个覆盖项—这些立即会覆盖配置值。

频道名称敏感。

频道选项和策略

频道有几个选项来控制谁可以接收更新以及如何分发更新。最重要的选项如下。您可以从 Web 应用、CLI 或公共 API 中配置这些选项。

• 默认频道：可选地标记新设备附加到的频道或平台特定的频道。请参阅“默认频道行为”以了解路由场景。
• 平台过滤器：启用或禁用向 iOS, Android、 Electron 或设备发送更新。
• 禁用本机下降级：防止在设备的本机应用程序版本新于频道的包装时发送更新（例如，设备在 1.2.3 版本中，而频道有 1.2.2 版本）。
• 允许开发构建：允许更新开发构建（用于测试时有用）。
• 允许模拟器设备：允许更新模拟器/模拟器（用于测试）。
• 允许设备自我分配：让应用在运行时切换到此通道（ setChannel如果禁用， setChannel 将在此通道上失败。

禁用自动更新策略

使用此选项来限制哪些类型的更新将自动分发。选项：

• 主要：阻止跨主要更新（0.0.0 → 1.0.0）。允许小版本和补丁更新。
• 次要：阻止跨次要更新（例如，1.1.0 → 1.2.0）和主要版本。允许补丁更新。注意：不阻止 0.1.0 → 1.1.0。
• 补丁：非常严格。只允许在同一主要和次要版本中增加补丁版本。示例：0.0.311 → 0.0.314 ✅，0.1.312 → 0.0.314 ❌，1.0.312 → 0.0.314 ❌。
• 元数据：要求每个捆绑包的最低更新版本元数据。通过 CLI 使用 --min-update-version 或 --auto-min-update-version. 如果缺失，会标记通道为配置错误，直到设置为止。
• none: 允许所有根据 semver 兼容性更新。

更多详细信息和示例，请参阅 /docs/cli/commands/#disable-updates-strategy。

示例 (CLI):

# Block major updates on the Production channel
npx @capgo/cli@latest channel set production com.example.app \
  --disable-auto-update major

# Allow devices to self-assign to the Beta channel
npx @capgo/cli@latest channel set beta com.example.app --self-assign

使用 Your App 中的 setChannel()

该 setChannel() 方法允许您的应用程序在运行时程序性切换通道。这对于以下情况特别有用：

• QA/调试菜单，测试人员可以在其中切换通道
• Beta 程序优惠流程
• 功能标志实现
• A/B 测试场景

import { CapacitorUpdater } from '@capgo/capacitor-updater';

// Switch to the beta channel
await CapacitorUpdater.setChannel({ channel: 'beta' });

// Optionally trigger an immediate update check after switching
await CapacitorUpdater.setChannel({
  channel: 'beta',
  triggerAutoUpdate: true
});

如何设置 setChannel() (v5.34.0+ / v6.34.0+ / v7.34.0+ / v8.0.0+)

何时被调用： setChannel() 后端验证（只读）

1. : 发送一个请求到 __CAPGO_KEEP_0__ 后端验证通道是否允许（检查自我赋值权限）: A request is sent to the Capgo backend to validate the channel is allowed (checking self-assignment permissions)
2. : 如果验证通过，通道将被保存到设备的本地存储中作为即时效果 defaultChannel
3. Instant effect: The next update check uses the new channel immediately (no waiting for replication)

为什么这很重要: 在旧版本中， setChannel() 将频道覆盖保存到后端数据库（与API或控制台相同）。设备需要等待后端复制（最多2分钟）才能使频道更改生效。现在， setChannel() 仅从后端读取（用于验证）并在本地存储，从而使频道切换立即生效。

安全注意事项: 即使频道的权限在本地设置后发生更改（例如，自我赋权被禁用），后端仍会在更新检查期间验证频道，从而确保安全性得到维护。

频道更改方法的比较:

方法	效果时间	持久化位置	使用场景
setChannel() 从插件	即刻	仅设备 (本地)	用户在应用内切换频道
设备控制台	最多 2 分钟	后端数据库	管理员针对特定设备的更改
API 频道分配	最多 2 分钟	后端数据库	自动化后端集成

为了获得最佳的用户体验，使用插件的 setChannel() 方法

仅限本地的频道切换的最低版本: 5.34.0, 6.34.0, 7.34.0或 8.0.0 (取决于您的主要版本). 每个次要版本号对应的特性集在所有主要版本中相同（例如，X.34.0，无论X是5、6、7还是8，都包含相同的功能）。请参见 插件安装

为频道分配一个捆绑包

To deploy a live update, you need to upload a new JS bundle build and assign it to a channel. You can do this in one step with the Capgo CLI:

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

将会上传您的构建的 Web 资产，并将新捆绑设置为活动的构建。 Development 频道。任何配置为监听该频道的应用程序将在下一次检查更新时接收更新。

您还可以从“捆绑包”部分的Capgo控制台 Assign builds to channels。点击菜单图标旁边的捆绑包，然后选择“Assign to Channel”以选择该捆绑包的频道。

捆绑包版本和频道

请注意，Capgo中的捆绑包是针对您的应用程序而言的，而不是针对个别频道。同一个捆绑包可以分配给多个频道。

当捆绑包版本时，我们建议使用语义版本 semver 并使用预发布标识符为频道特定的捆绑包。例如，beta 版本可能以 1.2.3-beta.1.

这种方法有几个好处：

• 它清晰地表明了构建之间的关系。 1.2.3-beta.1 显然是频道特定捆绑包的预发布版本 1.2.3.
• 它允许在不同通道之间重用版本号，减少混淆。
• 它使回滚路径清晰可见。如果您需要从 1.2.3中回滚到 1.2.2 是上一个稳定版本。

以下是如何将您的捆绑包版本与典型的通道设置对齐的示例：

• 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集成到您的构建过程中，您可以自动上传新包并将其分配到通道，任何时候您推送到特定分支或创建新发布时。

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

部署到设备

现在您了解了通道的概念，准备好开始将实时更新部署到真实设备了。基本流程是：

1. 在您的应用中安装Capgo SDK
2. 配置应用以监听所需的通道
3. 上传一个构建并将其分配到该通道
4. 启动应用并等待更新！

对于更详细的教程，请参见 实时更新部署 指南。快乐更新！

高级渠道使用：用户分段

除了开发阶段之外，渠道还可以用于其他用途。它们是一种强大的用户分段工具，支持以下功能：

• 不同用户等级的功能标志
• A/B测试
• 逐渐发布新功能
• Beta测试计划

了解如何在我们的指南中实现这些高级用例： 如何根据计划和渠道分段用户并用于功能标志和A/B测试.