Capgo频道浏览:如何在运行时切换更新频道

你是否曾经希望可以直接将一个改变发送给特定的用户，让他们能够立即查看和反馈，而不必要求他们下载和安装一个新的测试版？

我曾经有客户要求我改进某些功能，我能够快速实现，但将结果传递给他们以验证意味着需要将更新推送给所有用户（风险较高）或创建一个专门为客户的临时版本（对双方来说是一件麻烦事）。

缺乏的是灵活性。开发者希望能够为不同用户组提供不同的更新，例如非技术人员、QA或整个用户群（在适当的情况下）。

生产版本无法切换到工作版本、收集反馈并返回生产版本。

这就是 频道切换 的作用。一个安装在用户设备上的应用程序可以在运行时切换更新频道，将生产应用程序转变为一个灵活的空间来进行审查和迭代，而不是一个固定的终点。这对于非技术人员来说尤其有用，他们可以在已经安装的应用程序中测试更改并直接给出反馈。

了解更新频道

更新频道是Capgo如何针对特定版本进行更新的方式。每个版本都与一个频道相关联，而该频道决定它将接收哪些更新。

例如，您可以发布更新到一个 preview 频道而不影响其他用户。 production. 在过去，切换频道需要安装不同的本机构建或通过控制台手动更改设备分配。

频道在 Capgo 中允许您：

针对不同特性的用户群进行目标
通过将用户分配到不同的频道来运行 A/B 测试
逐渐推出新功能
创建 beta 测试计划
使用单个用户来调试生产问题

如果您不熟悉更新频道， Capgo 频道文档对它们进行了更详细的介绍。

什么是频道冲浪？

频道冲浪允许安装的应用程序从不同的更新流中拉取，而无需重新安装。安装的应用程序可以在运行时切换更新频道，并且它将继续从新选择的频道接收更新，直到应用程序被卸载或切换到另一个频道。

In实践中，这意味着产品负责人或QA人员可以切换一个 production build到，例如一个 preview channel，尝试最新的更改。当他们完成测试时，他们切换回 production 。不需要重新安装或单独的预览构建。

在背后，频道切换工作是通过让应用程序告诉更新客户端使用哪个频道。这个选择可以在运行时更改，并且直到它被清除或替换为止。

如何实现频道切换

在尝试频道切换之前，需要先在项目中配置Capgo Live Updates。要设置，请遵循 Capgo快速入门指南.

频道切换所需的唯一设置是允许设备自行关联的选项在每个频道上启用，在Capgo控制台中。 不需要code的任何更改或配置修改。

频道切换的核心是由一个API调用驱动的:

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

await CapacitorUpdater.setChannel({ channel: 'your-channel' });

这个设置了用于查询Capgo更新的频道。了解更多关于设置API.

即刻频道切换 (v5.34.0+)

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始 (取决于您的主要版本) setChannel() 工作方式不同且速度更快：

后端验证（只读）: 向Capgo后端发送请求，验证频道是否允许
本地存储更新: 如果验证通过，频道将保存到设备的本地存储
即刻效果: 下一次更新检查将立即使用新频道

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

完整频道切换流程

为了提供更好的用户体验，您通常需要做的不仅仅是切换频道并等待下一次应用重启。一个常见的方法是立即检查更新，下载可用更新并重新加载应用程序，以便用户直接进入所选频道的更新。

典型流程如下：

切换频道（setChannel)
检查更新（getLatest)
获取并应用更新（download, set 或 next)
如果需要重新加载应用程序（reload)

以下是完整的示例：

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

async function switchChannel(selectedChannel: string) {
  try {
    // 1. Set the updates channel (with optional auto-update trigger)
    await CapacitorUpdater.setChannel({
      channel: selectedChannel,
      triggerAutoUpdate: true // Immediately check for updates
    });

    console.log(`Switched to channel: ${selectedChannel}`);

    // If you want more control, handle the update manually:
    // const latest = await CapacitorUpdater.getLatest();
    // if (latest.url) {
    //   const bundle = await CapacitorUpdater.download({
    //     url: latest.url,
    //     version: latest.version
    //   });
    //   await CapacitorUpdater.set({ id: bundle.id });
    // }

  } catch (error) {
    console.error('Failed to switch channel:', error);
  }
}

// Switch to the beta channel
switchChannel('beta');

您如何结构此流程取决于您。您可能会将这些步骤分散在多个交互中，也可能一次性完成。无论您如何结构流程，都要确保考虑到失败。网络问题或无效的频道都可能阻止更新被应用。

唯一的要求：启用自我分配

只需执行以下操作即可启用频道浏览。 在使用 setChannel()切换频道之前，必须在Capgo控制台中为该频道启用自我赋值：

前往你的__CAPGO_KEEP_0__控制台频道 section in your Capgo dashboard
点击要管理的频道名称
启用 “Allow devices to self associate”
保存更改

在频道设置中启用自我赋值

就完成了。无需在应用中进行任何配置更改。 defaultChannel 设置必备。只需在您希望用户可以切换的通道上启用自我赋值即可。

如果此设置被禁用，任何尝试在 setChannel() 中调用 channelPrivate 将会失败，并触发

可用通道列表

您可以获取可用于自我赋值的通道列表:

const { channels } = await CapacitorUpdater.listChannels();

console.log('Available channels:', channels.map(c => c.name));
// Use this to build a channel selector UI

这只返回了自我赋值功能启用的通道。

获取当前通道

检查设备当前被赋值到的通道:

const { channel } = await CapacitorUpdater.getChannel();

console.log('Current channel:', channel);

恢复默认通道

为了移除通道覆盖并返回到默认值：

await CapacitorUpdater.unsetChannel({});

这会将设备从任何特定赋值的通道中解除绑定，导致它回落到默认值 defaultChannel In您的配置或云端默认中。

如何测试频道浏览

要看到频道浏览的效果，您需要一个发布版本 - __CAPGO_KEEP_0__ 是为发布版本设计的。在调试版本中，应用通常从开发服务器加载 JavaScript，而不是使用正常的更新流程。 @capgo/capacitor-updater API is designed for release builds. In debug builds, the app typically loads JavaScript from a development server instead, which bypasses the normal update flow.

频道浏览的唯一要求是启用

“允许设备自我关联” 在您要允许切换的每个频道上。不需要在您的应用中进行任何配置更改。 创建测试版本

按照正常流程构建您的应用：

然后使用 Xcode 或 Android Studio 创建您的本机构建，或者使用您的 CI/CD pipeline。应用将在您的 __CAPGO_KEEP_0__ 控制台中设置为云端默认的频道上启动。

bun run build && npx cap sync

Then create your native builds using Xcode or Android Studio, or use your CI/CD pipeline. The app will start on whichever channel is set as the cloud default in your Capgo dashboard.

__CAPGO_KEEP_0__

安装应用后，发布更新到不同的频道：

# Publish to preview channel
npx @capgo/cli@latest bundle upload --channel preview

# Publish to production channel
npx @capgo/cli@latest bundle upload --channel production

从那里，导航到应用中的频道浏览UI并触发频道切换。应用应该从选定的频道中获取更新并重新加载到新更新中。

构建频道切换器UI

频道浏览通常是您希望限制到一小组用户而不是所有使用应用的用户。例如，您可能有一个按钮可供认证员工切换应用到预览频道。

以下是频道切换器的示例React组件：

import { useState, useEffect } from 'react';
import { CapacitorUpdater } from '@capgo/capacitor-updater';

export function ChannelSwitcher() {
  const [currentChannel, setCurrentChannel] = useState<string>('');
  const [availableChannels, setAvailableChannels] = useState<string[]>([]);
  const [isLoading, setIsLoading] = useState(false);

  useEffect(() => {
    loadChannelInfo();
  }, []);

  async function loadChannelInfo() {
    const { channel } = await CapacitorUpdater.getChannel();
    setCurrentChannel(channel || 'default');

    const { channels } = await CapacitorUpdater.listChannels();
    setAvailableChannels(channels.map(c => c.name));
  }

  async function handleChannelSwitch(channel: string) {
    setIsLoading(true);
    try {
      await CapacitorUpdater.setChannel({
        channel,
        triggerAutoUpdate: true
      });
      setCurrentChannel(channel);
      // App will update in background or on next restart
    } catch (error) {
      console.error('Failed to switch channel:', error);
    } finally {
      setIsLoading(false);
    }
  }

  return (
    <div>
      <p>Current channel: {currentChannel}</p>
      <div>
        {availableChannels.map(channel => (
          <button
            key={channel}
            onClick={() => handleChannelSwitch(channel)}
            disabled={isLoading || channel === currentChannel}
          >
            Switch to {channel}
          </button>
        ))}
      </div>
    </div>
  );
}

OTA更新陷阱

这些并不是特定于频道浏览的，但在开始在运行时切换频道后，它们会变得很快变得明显。

运行时版本不匹配

Capgo中的更新与原生应用版本绑定。如果更新的原生版本与安装的原生应用版本不匹配，更新将不会下载或应用。当频道浏览时，这通常会显示为应用切换频道但没有更新被应用，即使在该频道上存在更新。

这通常意味着更新是从应用的不同原生版本发布的。确保频道的打包文件与设备上安装的原生版本兼容。

删除或撤销更新

如果应用已经下载了频道的更新，删除该更新从Capgo控制台中不删除设备上已经有的更新。删除只会停止 未来的 下载.

发布一个已知的好更新到同一频道是回滚一个坏更新的可靠方法。这会在频道的历史中创建一个新的更新，客户端会将其视为最新版本并将其应用而不是之前的版本。

Capgo 还提供了回滚机制，可以指示客户端重新应用之前的稳定更新或回退到构建中嵌入的更新。

数据迁移考虑

切换频道会改变应用程序运行的 JavaScript 包。如果您的应用程序依赖于迁移或数据形状，且这些迁移或数据形状在不同频道之间不兼容，频道切换可能会导致问题。

例如，如果一个 beta 更新应用了数据库迁移，生产版本可能无法理解新的 schema。开发人员应该确保更新在切换频道时保持安全，或者在需要时限制切换到一方向。

为什么频道浏览改善了移动迭代

频道浏览尤其适用于在生产环境中快速查看更改。

快速验证

想象一下，需要在广泛发布之前验证紧急修复。通过频道浏览，修复可以被隔离到一小组指定用户中，他们可以在修复发布到生产环境之前对其进行审查。

利益相关者审查

A产品负责人或QA人员可以切换他们的已安装的生产构建到另一个更新频道，验证修复或功能，然后切换回原来的频道一次他们完成了。

Streamlined Testing

这使得非技术人员更容易参与审查和决策，同时保持流畅的工作流程。一个单独的生产构建变成了一个灵活的工具，用于测试、反馈和验证。

Use Cases

QA Testing: QA团队可以在特性分支之间切换
Beta Programs: 用户可以选择进入beta频道，获取早期访问
Stakeholder Review: 产品负责人可以预览更改之前发布
A/B Testing: Assign用户到不同的频道进行实验
调试:切换一个特定用户到一个调试频道以诊断问题

比较:频道切换方法

方法	生效时间	持久存储位置	用例
`setChannel()` 从插件	即刻	仅设备本地	用户在应用内触发的频道切换
设备控制台强制切换	Up to 2 min	后端数据库	管理员为特定设备的更改
API 频道分配	Up to 2 min	后端数据库	自动化后端集成

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

最佳实践

限制访问频道浏览通常用于内部使用 - 不要将其暴露给所有用户
处理错误: 在频道切换时始终优雅地处理错误
验证兼容性: 确保不同频道的更新与安装的原生版本兼容
频道文档: 对每个频道保持清晰的文档
使用情况监控: 为调试目的跟踪哪些设备在哪些频道上

资源

结论

通过频道切换，您可以改变迭代Capacitor应用的方式。相比于将生产版本视为固定的终点，频道切换使其成为测试、验证和快速迭代的灵活工具。

近期插件版本中引入的即时频道切换功能，使得体验更加流畅 - 用户可以在不等待任何时间的情况下切换频道并立即从新频道接收更新。

无论您是在与利益相关者验证bug修复、运行beta测试还是调试特定用户的问题，频道切换都给您了灵活性来在正确的时间向正确的用户发送正确的更新。

继续阅读频道切换的Capgo：如何在运行时切换更新频道

如果您正在使用 频道切换的Capgo：如何在运行时切换更新频道 来规划频道路由和分阶段发布，连接它与频道来获取频道路由和分阶段发布的实现细节，频道为 Channels 的实现细节 Channels 为 Channels 的实现细节 Beta 测试解决方案为 Beta 测试解决方案的产品工作流程，和版本目标解决方案为版本目标解决方案的产品工作流程。

Capgo的频道切换：如何在运行时切换更新频道