频道

实时更新频道指向您的应用程序的特定 JS 包装构建，这将与任何配置为监听该频道的设备共享。 当您 install the Capgo Live Updates SDK 频道不提供保密性

频道控制更新的资格，而不是捆绑包的保密性。即使频道是私有的或自我赋值被禁用，任何未加密的捆绑包上传到__CAPGO_KEEP_0__仍应被视为公共资产，交付给客户端。加密保护了更新的传递路径和真实性，但仍然可以通过足够的努力逆向工程从分发的应用程序中恢复已分发的捆绑包，因为客户端的公共密钥是其中的一部分。请参见

Channels control update eligibility, not bundle secrecy. Even if a channel is private or self-assignment is disabled, any unencrypted bundle uploaded to Capgo should still be treated as a public asset delivered to clients. Encryption protects the delivery path and authenticity of updates, but shipped bundles can still be reverse engineered from the distributed app with enough effort because the public key is part of the client. See Live Update encryption 设备如何选择频道（优先顺序）

Section titled “设备如何选择频道（优先顺序）”

When a device checks for an update, Capgo decides which channel to use in this strict order (highest priority first):

1. – 手动将特定设备 ID 附加到频道。适用于紧急调试或受控测试与单个真实用户。这个总是获胜。 install the __CAPGO_KEEP_0__ Live Updates __CAPGO_KEEP_1__
2. Cloud override (per-device) via Dashboard 或 API – 当您在控制台或通过 API 更改设备的频道时创建。用于 QA 用户在特性 / PR 频道之间切换或重现用户问题。重新安装二进制文件不会清除它；删除设备条目。
3. 插件 setChannel() 本地频道 – 当应用程序调用并且后端验证目标频道允许自我赋值时创建。所选频道在该设备上存储在本地，立即生效，并不显示在设备覆盖 UI 中。 setChannel() 使用 setChannel() 实现即时频道切换

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始（取决于您的主要版本）

它与后端联系以 验证 setChannel() 验证 验证 检查该频道是否允许自我赋值（检查是否为该频道启用了自我赋值），然后将该频道 在设备上 本地存储 defaultChannel。这意味着新的频道立即生效 下一次更新检查时 不需要等待复制

之前 setChannel() 将频道覆盖保存到后端数据库（如控制台或API更改），设备需要等待数据复制（最多2分钟）才能识别新的频道。新行为只从后端读取（用于验证）并本地存储，频道切换立即生效

因为 setChannel() 是本地的 所以 create a Device Override entry in the Capgo dashboard. The Device Override UI only shows overrides created from the dashboard or the Public API.

注意： 即使一个频道在本地设置后被禁止，后端仍会在更新检查期间验证该频道，因此安全性得到维护。

重要： 通过控制台或API修改频道时，可能会有2分钟的延迟，直到所有边缘服务器反映出更改。 setChannel() from your app code—it validates with the backend, then sets the channel locally for immediate effect.

4. Capacitor config defaultChannel (test build default) __CAPGO_KEEP_0__配置 capacitor.config.* (测试构建默认值) beta, qa, pr-123– 如果在
5. 中存在，并且没有强制/覆盖/本地频道，则应用程序以此频道启动（例如，）。 – If you mark a default channel in the dashboard, all normal end‑users (no force, no Dashboard/API override, no plugin local channel, no config defaultChannel) attach here. Change it to roll out or roll back instantly—no new binary. If you have platform-specific defaults (for example, one iOS-only, one Android-only, one Electron-only), each device lands on the default matching its platform. Leaving the cloud default unset is allowed; in that case the device must match on steps 1–4 to receive updates.

最佳实践：

• 将 1–4 视为异常/测试层；当您设置一个云默认值时，真实用户应该流入它。如果您选择不设置一个，请务必明确用户如何附加（通常通过 defaultChannel 在配置或设备级别的覆盖中）。
• 仅在 defaultChannel 您明确向测试者分发的二进制文件中配置。
• 未设置它会将生产逻辑集中在仪表板中。 setChannel() 仅在生产中

sparingly 使用—主要用于 QA 或目标诊断。

Summary: Force > Dashboard/API Override > Plugin setChannel() 摘要： 强制 > 仪表板/__CAPGO_KEEP_0__ Override > 插件 defaultChannel 本地通道 > 配置

> 云默认值。

设置云端默认值是可选的，但通常作为新设备的通用路径。没有一个，仅匹配强制映射、覆盖或 defaultChannel 在Capacitor配置中的设备才能接收更新。当您选择标记默认值时，请记住这些模式：

• 单个默认值（最常见） – 如果一个通道启用了 iOS、Android 和 Electron，则成为唯一的默认值；没有覆盖的设备将附加到这里。
• 平台特定默认值 – 如果按平台分离通道（例如， ios-production 仅启用 iOS, android-production 仅启用 Android, electron-production 仅启用 Electron），则标记每个平台的默认值。iOS 设备将前往 iOS 默认值，Android 设备将前往 Android 默认值，Electron 应用将前往 Electron 默认值。

请记住，云端默认值和 defaultChannel 在 capacitor.config.* 同一决策层中都占据着。 如果您设置了云端的默认值，那么您不需要在您的Capacitor配置中重复该值—留空 defaultChannel 留空用于生产构建。 预留 defaultChannel 用于您希望测试人员或QA在非生产通道上启动的二进制文件，即使云端的默认值不同。

您可以在任何时候在控制台中更改默认值。 当您切换默认值时，新设备立即遵循新的路由，现有设备在下一次检查时遵循正常的优先级规则。

设置通道

在入职过程中，您创建了第一个通道（大多数团队将其命名为“生产”），但没有任何锁定—you可以随时重命名或删除任何通道。 要添加额外的通道：

1. 转到Capgo控制台的“通道”部分
2. 点击“新建通道”按钮
3. 输入通道名称并点击“创建”

通道名称可以是您喜欢的任何内容。 一种常见的策略是将通道与开发阶段匹配，例如：

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

配置应用中的通道

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

打开您的 capacitor.config.ts (或 capacitor.config.json)文件。 在 plugins 部分下， optionally 设置 defaultChannel __CAPGO_KEEP_0__ 测试构建 (内部/测试环境). 对于生产环境，建议省略它，以便设备使用 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.
    },
  },
};

接下来，构建您的 Web 应用并运行 npx cap sync 以将更新的配置文件复制到您的 iOS、Android 和 Electron 项目中。如果您跳过此同步步骤，native 项目将继续使用之前配置的渠道。

注意

渠道选择顺序：强制 > Dashboard/API 设备覆盖 > 插件 setChannel() 本地渠道 > 配置 defaultChannel > Cloud Default。

仅在测试/内部构建中使用；在生产环境中留空，以便用户遵循 Cloud Default（如果设置）而不是在 native 配置中重复路由。 defaultChannel 仅在测试/内部构建中使用；在生产环境中留空，以便用户遵循 Cloud Default（如果设置）而不是在 native 配置中重复路由。

You can still force (pin) a device or apply an override later—those immediately supersede the config value.

频道名称是大小写敏感的。

频道选项和策略

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

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

禁用自动更新策略

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

• major：阻止目标包的主要版本号高于设备本地基线（version_build）的包。示例： 1.2.3 -> 2.0.0 将被阻止； 1.2.3 -> 1.9.0 将被允许。
• minor：阻止目标包的主要或次要版本号与 version_build不同。示例： 1.2.3 -> 1.3.0 is blocked; 1.2.3 -> 1.2.4 is allowed.
• patch: 最严格模式。阻止任何对主版本、次版本或修订版本号的修改。仅允许后缀修改， MAJOR.MINOR.PATCH 保持不变。例如： 1.0.0-beta.1 -> 1.0.0-beta.2 是允许的， 1.0.0+build.1 -> 1.0.0+build.2 是允许的， 1.0.0 -> 1.0.1 是被阻止的.
• metadata: 每个捆绑包都需要最低更新版本的元数据。通过CLI使用 --min-update-version 或 --auto-min-update-version配置。如果缺失，通道将被标记为不配置，更新将被拒绝直到设置。
• none: 根据 兼容性允许所有更新.

这些策略将渠道的目标包与原生基线进行比较，后者作为 version_build，而不是当前下载的包作为 version_name.

了解更多详细信息和示例，请参见 /docs/cli/commands/#disable-updates-strategy 中的 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

使用 setChannel() 从您的应用程序

The 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
});

如何设置 Channel（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() 仅从后端读取（用于验证）并在本地存储，实现了通道切换的即时性。

控制台可见性： 通过插件设置的通道不会使设备在Capgo UI中显示为设备覆盖。只有从控制台或公共API创建的通道 assignments 才会在那里列出。使用控制台或API时需要管理员可见的覆盖。

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

通道更改方法的比较：

方法	效果时间	持久存储在哪里	在设备Override UI中显示	用例
setChannel() 来自插件	即刻	仅设备（本地）	否	在应用内用户触发的通道切换
仪表盘设备Override	至多2分钟	后端数据库	是	管理员触发的特定设备的更改
API 频道分配	最多 2 分钟	后端数据库	是	自动化后端集成

在构建频道切换 UI 时,为了获得最佳用户体验,请始终使用插件的 setChannel() 方法。

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

分配一个包到一个频道

为了部署一个实时更新，您需要上传一个新的 JS 包构建并分配它到一个频道。您可以在一步完成这个过程使用 Capgo CLI:

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

这将上传您的构建的 Web 资产并将新的包设置为频道的活动构建。任何配置为监听该频道的应用将在下一次检查更新时接收到更新. Development 您也可以从 __CAPGO_KEEP_0__ 的“包”部分分配构建到频道。点击一个构建旁边的菜单图标并选择“分配到频道”来选择该构建的频道.

You can also assign builds to channels from the “Bundles” section of the Capgo dashboard. Click the menu icon next to a build and select “Assign to Channel” to choose the channel for that build.

Section titled “包版本和频道”

It’s important to note that bundles in Capgo are global to your app, not specific to individual channels. The same bundle can be assigned to multiple channels.

当打包版本时，我们建议使用 语义版本控制与Capgo的Semver Tester 并使用预发布标识符为渠道特定构建。例如，一个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. 回滚构建

确认操作

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

For more advanced workflows, you can automate your live update deployments as part of your CI/CD pipeline. By integrating Capgo into your build process, you can automatically upload new bundles and assign them to channels whenever you push to certain branches or create new releases.

对于更高级的工作流程，您可以将实时更新的发布自动化为您的CI/CD管道的一部分。通过将__CAPGO_KEEP_0__集成到您的构建过程中，您可以自动上传新包并将其分配到频道，任何时候您推送到特定分支或创建新发布时。 查看 docs to learn more about automating Capgo live updates.

在设备上部署

现在你理解了通道，你就可以开始在真实设备上部署实时更新了。基本流程是：

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

如果你想了解更多详细的步骤，请参阅 实时更新 部署指南。更新快乐!

高级通道使用：用户分段

Channels可以用来做更多的事情，除了开发阶段。它们是一种强大的工具，用于用户分段，支持功能，如：

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

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

继续从Channels

如果您正在使用 Channels 规划通道路由和分阶段发布，连接它 频道 关于频道的实现细节 频道 关于频道的实现细节 Beta 测试解决方案 关于 Beta 测试解决方案的产品工作流程 版本目标解决方案 关于版本目标解决方案的产品工作流程 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期 关于 Capgo 环境最佳实践：使用一个移动应用 ID 进行分期的实际背景