复制页面选项

复制一个设置提示，包含安装步骤和此插件的完整Markdown指南。

一个Live Update频道指向您的应用程序的特定JS包构建，该构建将与任何配置为监听该频道的设备共享。您在应用程序中安装Live UpdateLive Updates__CAPGO_KEEP_1__后，任何配置为该频道的原生二进制文件将在应用程序启动时检查可用更新。您可以随时更改频道指向的构建，并且也可以回滚到以前的构建版本。安装Capgo Live Updates SDK __CAPGO_KEEP_0__

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

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

强制设备映射（控制台） 控制台和Capgo覆盖写入90天后失效 Console 和 API 将在 90 天后过期.
Cloud 强制更新（设备级）通过控制台或 API – Created when you change the device’s channel in the dashboard or via API. Use for QA users switching between feature / PR channels or to reproduce a user issue. Reinstalling the binary does not clear it; deleting the device override does. The same 90-day retention applies.
Plugin setChannel() 本地频道 – 当应用程序调用时创建 setChannel() 并且后端验证目标频道是否允许自我赋值。选择的频道在该设备上存储本地，立即生效，并不在设备覆盖 UI 中显示。

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始（取决于您的主要版本） (根据您的主要版本) setChannel() 它的工作方式不同：它会联系后端 validate 允许该频道（检查是否为该频道启用了自我赋值），然后存储该频道 本地设备上 as defaultChannelLive Update 立即生效 无需等待数据复制

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

因为 setChannel() 是本地的，所以它不创建Capgo控制台中的设备覆盖条目。设备覆盖UI仅显示从控制台或公共API创建的覆盖。

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

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

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

最佳实践：

将1-4视为异常/测试层；当您设置云默认值时，真实用户应该流入其中。如果您不设置云默认值，请务必明确用户如何附加（通常通过 defaultChannel 在配置或设备级别进行覆盖）。
仅在您向测试人员明确分发的二进制文件中进行配置。 defaultChannel 在生产环境中不配置它，生产逻辑仍然集中在控制台中。
在生产环境中使用 setChannel() 仅在QA或针对性的诊断中使用。

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

总结：强制 > 控制台/ API 覆盖 > 插件 > 本地渠道 > 配置 > 云默认。 setChannel() 控制台和 __CAPGO_KEEP_0__ 覆盖在90天后过期。 defaultChannel 标题：控制台和 __CAPGO_KEEP_0__ 覆盖在90天后过期。

强制映射和控制台或公共 API 渠道覆盖存储在 __CAPGO_KEEP_1__ 中。清理作业在90天后删除这些 assignments

对于每个设备，强制映射和控制台或公共API频道的覆盖都是存储在Capgo中的。清理作业会删除这些 assignments 90天后清理作业删除这些 assignments . 检查更新不重置计时器。只有覆盖写入 (或自己删除) 才能改变时间戳。

这不是设备存储保留 . 90天内未连接到Capgo的设备将被清除。 Override清除将删除设备的映射，即使设备仍然处于活跃状态。

对于未被清除的分配:

在 defaultChannel in capacitor.config.* 从应用程序中调用。从插件 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 和更高版本中，分配是本地的，并且不会被清除。重新安装应用程序会清除它，所以应用程序必须再次调用
如果您仍然想要该频道。 setChannel() 频道 setChannel() 设备存储保留

设备存储保留设备 tab 和设备 Override UI 只列出控制台和公共 API assignments。它们不列出每个设备的频道，并且它们不列出本地 API assignments。 setChannel() assignments.

Capgo频道设备标签页显示 Override保留期弹出窗口：控制台覆盖将在90天后过期 — 默认频道行为

标题：默认频道行为

单个默认值（最常见） defaultChannel 在Capacitor配置中，会接收到更新。当您选择保留默认值时，请记住以下模式：

平台特定默认值 设备
tab 和设备 Override UI 只列出控制台和公共 __CAPGO_KEEP_0__ assignments。它们不列出每个设备的频道，并且它们不列出本地 __CAPGO_KEEP_0__ assignments。 – 如果您根据平台将频道分开（例如， ios-production 记住，云端默认值和 android-production 在 electron-production 同一决策层。如果您设置了云端默认值，您不需要在__CAPGO_KEEP_0__配置中重复该值—留

空白 defaultChannel 用于生产构建。预留 capacitor.config.* 双方都占据同一决策层。如果您设置了云端的默认值，那么您就不需要在您的Capacitor配置中重复该值—您可以直接 defaultChannel 您可以在任何时候在控制台中更改默认值。打开渠道，然后 defaultChannel 管理应用设置

,它将带您到 应用内设置管理– 应用信息. 该默认值不再是通道页面上的切换开关。当您交换一个默认值时，新设备立即遵循新的路由，现有设备在下一次检查时遵循正常的优先级规则。

设置通道

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

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

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

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

配置应用中的频道

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

打开您的 capacitor.config.ts (或 capacitor.config.json上下文：HTML文本片段来自更长的Capgo UI字符串（父键 `compare_step_build_text`）。页面/区域：Capgo营销网站。角色：长营销或法律段落。见于：页面替代品/expo.astro，页面替代品/voltbuilder.astro。消息键 `compare_step_build_text`（Compare Step Build Text）。 plugins )文件。频道配置下， facultatively 设置 defaultChannel 为 测试构建（内部/QA） （生产构建时，建议省略以使设备使用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 注意

频道选项和策略

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

默认频道：可选地标记频道或平台特定的频道，新设备附加到。在控制台中，这位于应用程序信息（“在应用程序设置中管理 从频道页面）。请参阅“默认频道行为”以了解路由场景。
平台过滤器：启用或禁用向 iOS, Android或 Electron 设备每个频道。
禁用原生自动降级：防止发送更新，当设备的原生应用程序版本新于频道的包（例如，设备在1.2.3时，频道有1.2.2）。
允许开发构建：允许更新开发构建（用于测试）。CLI： --dev / --no-dev.
允许生产构建：允许更新生产（商店）构建。请在频道中留下此选项，频道为真实用户服务。CLI： --prod / --no-prod.
允许模拟器设备：允许更新模拟器/模拟器（用于测试）。 CLI: --emulator / --no-emulator.
允许物理设备：允许更新真实手机和平板电脑。生产渠道保持此设置。 CLI: --device / --no-device.
允许设备自我分配：让应用在运行时切换到此渠道（如果禁用，则会失败）。 __CAPGO_KEEP_0__: setChannel下载格式：选择设备下载完整的zip文件、仅更改的delta文件或两者的最佳组合（）。查看 setChannel will fail for this channel. CLI: --self-assign / --no-self-assign.
下载格式all, zip, delta, zip_from_builtin, delta_from_builtin渐进式发布渐进式发布渐进式发布：一个渠道可以保持稳定的包，同时逐渐向固定的设备群暴露一个单独的发布目标。您可以暂停、恢复、推动、回滚和配置自动失败响应，而不需要切换渠道。查看

下载格式

下载格式渐进式发布用于交付模型、仪表板工作流程、API字段和CLI命令。

禁用自动更新策略

使用此选项来限制通道自动分发的更新类型。选项：

重大：阻止目标包的主要版本高于设备本地基线（version_build示例： 1.2.3 -> 2.0.0 被阻止； 1.2.3 -> 1.9.0 允许。
次要：阻止目标包的主要或次要版本与 version_build示例： 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）。该频道必须已经存在（channel set 不创建它）：

# 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

# Production channel: store builds on real devices, no emulators
npx @capgo/cli@latest channel set production com.example.app --prod --device --no-emulator

context

The setChannel() 标题为“使用 setChannel() 从您的应用程序”

该
方法允许您的应用程序在运行时程序matic地切换频道。这对于以下情况特别有用：
功能标志实现
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
});

什么时候 setChannel() 被调用:

后端验证（只读）: 向Capgo后端发送请求，验证通道是否允许（检查自赋值权限）
本地存储更新: 如果验证通过，通道将保存到设备的本地存储中 defaultChannel
立即生效: 立即使用新频道进行下一次更新检查（无需等待复制）

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

控制台可见性： A channel set with the plugin does not make the device appear as a Device Override in the Capgo UI. Only channel assignments created from the dashboard or the Public API are listed there. Use the dashboard or API when you need an admin-visible override.

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

频道更改方法的比较：

方法	效果时间	持久存储位置	在设备设置界面中显示	过期时间	使用场景
`setChannel()` 在Capgo解决方案营销页面中	角色：短语或导航项	页面：解决方案/Cordova To Capacitor Ai	No	来自插件	即刻
仅设备（本地）	否	后端数据库	Yes	上线	90 天后最后一次覆盖写入
API频道分配	最多2分钟	后端数据库	Yes	上线	至多 2 分钟

自动化后端集成 setChannel() method.

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

Assigning a Bundle to a Channel

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

复制到剪贴板 Development 复制到剪贴板（上下文：Capgo营销网站。角色：UI标签。见：页面代理/[slug].astro。消息键`agents_page_copy_label`（代理页面复制标签））。此操作将上传您的构建的Web资产并将新包设置为频道的活动构建。任何配置为监听该频道的应用程序将在下一次检查更新时接收更新。

您也可以从“Capgo”仪表板的“包组”部分分配构建到频道。单击构建旁边的菜单图标并选择“分配到频道”，以选择该构建的频道。

包组版本和频道

请注意，Capgo中的包组是全局的，针对您的应用，而不是针对单个频道。同一个包组可以分配到多个频道。

当版本化包组时，我们建议使用语义版本号与Capgo的Semver Tester 以及预发布标识符来标识频道特定的构建。例如，beta版本可能被版本化为 1.2.3-beta.1.

在CI中，如果本地版本已经上传，使用 npx @capgo/cli@latest bundle upload --auto-bump (可选) major, minor, patch/fix, metadata,或 ai)，以便CLI从频道链接的包组中升级，直到找到一个空闲的名称。使用 ai,Workers AI会推断级别从本地与之前的delta清单（如果没有，则回退到 patch 没有之前的Capgo版本). 您无法将其与 --bundle. See CI/CD 集成 CI/CD集成 CLI 参考.

和

__CAPGO_KEEP_0__参考 1.2.3-beta.1 这种方法有几个好处: 1.2.3.
它清晰地表明了构建之间的关系。
显然是__CAPGO_KEEP_0__的预发布版本。 1.2.3您知道 1.2.2 它使回滚路径清晰。如果您需要从__CAPGO_KEEP_0__回滚到__CAPGO_KEEP_1__，您知道__CAPGO_KEEP_1__是之前的稳定版本。

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

Development channel: 1.2.3-dev.1, 1.2.3-dev.2, 等等。
QA channel: 1.2.3-qa.1, 1.2.3-qa.2, 等等。
Staging channel: 1.2.3-rc.1, 1.2.3-rc.2, 等等。
Production channel: 1.2.3, 1.2.4, 等等。

使用带前发布标识符的semver 是一个推荐的方法，但不是严格要求的。关键是找到一个清晰地表达您的构建之间关系并与您的团队开发过程一致的版本控制方案。

回滚一个 Live Update

如果您部署了一个 live update，引入了错误或需要回滚，很容易回滚到之前的版本。从仪表盘的“频道”部分：

点击您要回滚的频道的名称
找到您要回滚到的版本并点击冠军图标
确认操作

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

自动部署

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

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

最少权限 PR 预览

使用一个 应用预览 API key 在 CI 需要一个临时渠道每个拉取请求，但必须不管理现有的主/默认渠道。该密钥仍然绑定到拥有组织和选择的应用；它只是没有组织级别的角色。每个非公共预览渠道它创建的都将获得其自己的自动、渠道范围的生命周期权限。

组织管理员创建一个安全的 API 密钥，仅限预览应用并选择 应用预览。请参见 API 密钥.
使用一个唯一的、非公共渠道，如 pr-123. 不要传递 --default, --self-assign, 部署选项, 或 --delete-linked-bundle-on-upload.
上传并推广 PR 包装在一个命令，然后删除拥有该频道和包装时 PR 关闭:

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.

部署到设备

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

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

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

高级频道使用：用户分段

Channels 可以用于开发阶段以外的更多用途。它们是一种强大的工具，用于用户分段，支持以下功能：

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

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

继续使用 Channels

如果您正在使用 Channels context 频道为频道的实现细节频道为频道的实现细节测试版解决方案为测试版解决方案的产品工作流版本定位解决方案为版本定位解决方案的产品工作流 Capgo 环境最佳实践：使用一个移动应用ID进行分阶段为Capgo 环境最佳实践：使用一个移动应用ID进行分阶段的实际背景