Channels

实时更新频道指向您的应用程序的特定 JS 包构建，这将与任何配置为监听该频道的设备共享。您在应用程序中安装 __CAPGO_KEEP_0__ 实时更新 __CAPGO_KEEP_1__ 后，任何配置为该频道的原生二进制文件将在应用程序启动时检查可用更新。您可以随时更改频道指向的构建，并且也可以回滚到以前的构建版本，如有需要。 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 实时更新加密 详细信息请参阅。

设备如何选择频道（优先级）

当设备检查更新时，Capgo 将在以下严格顺序（优先级最高）中决定使用哪个频道：

1. 强制设备映射（控制台） – 手动将特定设备 ID 附加到频道。用于紧急调试或在单个真实用户下进行控制测试。总是获胜。
2. 云端覆盖（按设备）通过控制台或API – 当您在控制台或API 中更改设备的频道时创建。用于 QA 用户在特性/PR 频道之间切换或重现用户问题。重新安装二进制文件不会清除它；删除设备条目会清除。
3. 插件 setChannel() 本地频道 – 当应用程序调用时创建 setChannel() 并且后端验证目标频道是否允许自我赋值。 选择的频道会在该设备上存储，立即生效，并不在设备覆盖UI中显示。

使用setChannel()进行即时频道切换

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

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

因为 setChannel() 是本地的，因此它 不 创建一个设备覆盖项在Capgo控制台。设备覆盖UI仅显示从控制台或公共API创建的覆盖项。

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

重要： 当通过控制台或API进行频道更改时，仍然存在最多2分钟的复制延迟，直到所有边缘服务器反映更改。要实现即时频道切换，请 setChannel() 从您的应用code—它与后端验证，然后在本地设置频道以立即生效。

4. Capacitor 配置 defaultChannel (测试构建默认) – 如果存在于 capacitor.config.* 并且没有强制/覆盖/本地频道存在时，应用程序将在此频道启动（例如 beta, qa, pr-123). 供测试者使用，测试者可以自动进入预发布频道。生产构建通常不设置此选项。
5. 云默认频道（主要路径 ~99% 的用户) – 如果您在控制台中标记了一个默认频道，所有正常用户（无强制，无控制台/API 覆盖，无插件本地频道，无配置 defaultChannel）将附加到此频道。您可以立即推出或回滚—无需新二进制文件。如果您有平台特定的默认值（例如，一个 iOS-only，一个 Android-only，一个 Electron-only），每个设备将附加到匹配其平台的默认值。未设置云默认频道是允许的；在这种情况下，设备必须匹配步骤 1–4 才能接收更新。

最佳实践：

• 将 1–4 视为异常/测试层；当您设置云默认频道时，真实用户应该流入它。如果您不设置云默认频道，请务必明确用户如何附加（通常通过 defaultChannel 在配置或设备级别的覆盖中）。
• 仅在 defaultChannel 中配置。将其留空将使生产逻辑集中在控制台中。
• 使用 setChannel() 仅在生产环境中有限使用—主要用于QA或针对性的诊断。

如果一个渠道在平台（iOS/Android/Electron切换）禁用时，选择过程将跳过它并继续下一项。

摘要： 强制 > Dashboard/API Override > 插件 setChannel() 本地渠道 > 配置 defaultChannel > 云默认。

默认渠道行为

设置云默认是可选的，但通常作为新设备的fallback路径。没有一个，仅匹配强制映射、覆盖或在__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，它将成为唯一的默认值；没有覆盖的设备将附着在这里。 – If a channel has iOS, Android, and Electron enabled, it becomes the lone default; any device without overrides will attach here.
• 平台特定默认值 – 如果您根据平台将渠道分开（例如，仅启用 iOS、仅启用 Android、仅启用 Electron），则将每个渠道标记为其平台的默认值。 iOS 设备将前往 iOS 默认值，Android 设备将前往 Android 默认值，Electron 应用将前往 Electron 默认值。 ios-production 请记住，云端默认值和 android-production 在 electron-production 同一决策层。 如果您设置了云端默认值，则无需在您的 __CAPGO_KEEP_0__ 配置中重复该值—在生产构建中留空。 预留

用于您故意将测试或 QA 的二进制文件发送给测试人员或 QA 时，希望它们从非生产渠道开始，即使云端默认值与之不同。 defaultChannel 您可以在控制台中随时更改默认值。当您切换默认值时，新设备立即遵循新的路由，现有设备在下一次检查时将遵循正常的优先级规则。 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 empty for production builds. Reserve defaultChannel for binaries you intentionally ship to testers or QA when you want them to start on a non-production channel even if the cloud default is different.

You can change defaults at any time in the dashboard. When you swap a default, new devices obey the new routing immediately and existing devices follow the normal precedence rules the next time they check in.

Setting up a Channel

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

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

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

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

在应用中配置频道

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

(或 capacitor.config.ts )文件。频道配置下，选项性地设置 capacitor.config.json用于 plugins 测试构建（内部/QA）。对于生产构建，建议省略它，以便设备使用Cloud Default，除非显式覆盖。 defaultChannel 复制到剪贴板 接下来，构建您的Web应用程序并运行 以将更新的配置文件复制到您的iOS、Android和Electron项目。如果您跳过此同步步骤，则您的本机项目将继续使用它们之前配置的频道。

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.
    },
  },
};

Next, build your web app and run npx cap sync to copy the updated config file to your iOS, Android, and Electron projects. If you skip this sync step, your native projects will continue to use whichever channel they were previously configured for.

注意事项

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

仅在测试/内部构建中使用；在生产环境中不要包含它，以便用户遵循 Cloud Default（如果设置）而不是在本地配置中重复路由。 defaultChannel 您仍然可以强制（固定）设备或应用覆盖后果—这些立即优先于配置值。

渠道名称敏感。

渠道选项和策略

渠道选项和策略

Channels have several options that control who can receive updates and how updates are delivered. The most important ones are below. You can configure these from the web app, the CLI, or the Public API.

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

渐进式发布

A channel can maintain a stable bundle while gradually exposing a separate rollout target to a sticky device cohort. You can pause, resume, promote, roll back, and configure an automatic failure response without switching the channel for everyone. See 渐进式发布 for the delivery model, dashboard workflow, API fields, and CLI commands.

禁用自动更新策略

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

• major: 阻止目标包的主版本号高于设备本地基线的包 (version_buildExample: 1.2.3 -> 2.0.0 被阻止; 1.2.3 -> 1.9.0 允许。
• minor: 阻止目标包的主或次版本号与 version_build。 Example: 1.2.3 -> 1.3.0 被阻止; 1.2.3 -> 1.2.4 被允许。
• 修订：最严格模式。阻止任何对主、次或修订号的更改。仅允许后缀更改。 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 被阻止。
• 元数据：要求每个捆绑包的最小更新版本元数据。通过CLI配置 --min-update-version 或 --auto-min-update-version。如果缺失，通道将被标记为配置错误，更新将被拒绝，直到设置。
• 允许所有更新，根据 兼容性.

这些策略将渠道的目标捆绑与发送为 version_build,而不是当前下载的捆绑发送为 version_name.

有关详细信息和示例，请参阅 /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

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

该 setChannel() 方法允许您的应用程序在运行时程序matic地切换渠道。这对于

• QA/调试菜单，测试人员可以在之间切换渠道
• beta 程序优惠流程
• 功能标志实现
• AB测试场景

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后端发送请求，验证通道是否允许（检查自我赋值权限）
2. 本地存储更新: 如果验证通过，通道将保存到设备的本地存储中 defaultChannel
3. 立即生效: 下一次更新检查将立即使用新的频道（无需等待复制）

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

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

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

频道更改方法的比较：

方法	效果时间	持久存储位置	在设备设置界面中显示	使用场景
setChannel() 场景:Capgo解决方案营销页面。角色:短的UI标签或导航项。位置:页面解决方案/cordova-to-capacitor-ai.astro。关键字`解决方案_cordova_to_capacitor_ai_table_use_case` (Solutions Cordova To Capacitor Ai Table Use Case).	从插件	即刻	仅设备（本地）	否
用户在应用内切换频道	设备设置界面	最多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 都相同）。请参见 插件安装 为版本标签.

分配一个包到一个频道

要部署一个实时更新，您需要上传一个新的 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.

标题：包版本和频道

Capgo

When you version your bundles, we recommend using __CAPGO_KEEP_0__ semantic versioning with Capgo’s Semver Tester and pre-release identifiers for channel-specific builds. For example, a beta release might be versioned as __CAPGO_KEEP_0__ 1.2.3-beta.1.

In CI, if the local version was already uploaded, use __CAPGO_KEEP_0__ npx @capgo/cli@latest bundle upload --auto-bump (optionally __CAPGO_KEEP_0__) major, minor, patch/fix, metadata, or __CAPGO_KEEP_0__) aiso CLI bumps from the channel’s linked bundle until a free name is found. With CLI, Workers AI infers the level from the local vs previous delta manifest (falls back to CLI with no previous CLI version). aiYou cannot combine it with __CAPGO_KEEP_0__. See patch and the Capgo --bundleCI/CD Integration CI/CD Integration CI/CD Integration CLI reference.

这种方法有几个好处:

• 它清晰地表明了构建之间的关系。 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. 使用带有预发布标识符的semver是推荐的方法，但不是严格要求的。关键是找到一个清晰地表达构建之间关系并与团队开发流程一致的版本控制方案。
2. 找到你想回滚到的构建并点击冠军图标
3. 确认操作

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

自动部署

对于更高级的工作流程，您可以将实时更新部署作为您的CI/CD管道的一部分自动化。通过将Capgo集成到您的构建过程中，您可以自动上传新包并将其assign到频道，任何时候您推送到特定分支或创建新发布。

查看 CI/CD集成 docs to learn more about automating Capgo live updates.

了解更多关于自动__CAPGO_KEEP_0__实时更新的信息。

使用一个 应用预览 API

1. Have an organization administrator create a secure API key limited to the preview app and select 应用预览__CAPGO_KEEP_0__ API Keys.
2. 组织管理员创建一个安全的 pr-123__CAPGO_KEEP_0__ --default, --self-assign密钥，仅限预览应用，并选择 --delete-linked-bundle-on-upload.
3. 应用预览

APP_ID="com.example.app"
PREVIEW_CHANNEL="pr-123"
BUNDLE_VERSION="1.2.3-pr.123"

npx @capgo/cli@latest bundle upload "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --path ./dist \
  --channel "$PREVIEW_CHANNEL" \
  --bundle "$BUNDLE_VERSION"

npx @capgo/cli@latest channel delete "$PREVIEW_CHANNEL" "$APP_ID" \
  --apikey "$CAPGO_PREVIEW_KEY" \
  --delete-bundle \
  --success-if-not-found

bundle upload --channel 创建一个缺失的频道，上传包并在一个流程中推广它。清理是原子性的，并且拥有者检查：关键可以删除它创建的频道和其链接但未共享的包。它不能改变、推广或删除一个现有的主频道、另一个预览密钥的频道或另一个密钥的包。

如果审阅者需要一个QR code 或预览 URL，管理员必须为应用程序启用预览一次：

npx @capgo/cli@latest app set "$APP_ID" --preview
npx @capgo/cli@latest get-qr "$APP_ID" --channel "$PREVIEW_CHANNEL" --apikey "$CAPGO_PREVIEW_KEY" --url

一个 App 预览密钥不能启用预览，因为它没有应用设置权限。在 GitHub Actions 中，运行带有秘密的预览作业在 pull_request, 不 pull_request_target, 并将其限制为同仓库 PRs 中的 github.event.pull_request.head.repo.full_name == github.repository.

部署到设备

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

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

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

高级频道使用：用户分段

频道不仅可以用于开发阶段，还可以用于用户分段，提供功能，如:

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

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

继续从频道

如果您正在使用 频道 连接它以规划频道路由和阶段性发布 频道 频道 频道 频道 Beta 测试解决方案 为 Beta 测试解决方案 的产品工作流程 版本目标解决方案 为版本目标解决方案 的产品工作流程, 和 Capgo 环境最佳实践: 使用一个移动应用 ID 进行分期 为 Capgo 环境最佳实践: 使用一个移动应用 ID 进行分期 的实际上下文