跳过主要内容
Capgo logo
[教程]

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

使用Capgo的运行时频道切换，立即将更新发送给特定用户。无需重新安装Capacitor应用即可切换更新频道。

[__CAPGO_KEEP_2__]

[__CAPGO_KEEP_2__]

内容营销人员
[Capgo频道切换]：如何在运行时切换更新频道

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

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

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

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

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

了解更新频道

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

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

Capgo 中的频道允许您：

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

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

什么是频道冲浪？

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

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

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

如何实现Channel Surfing

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

channel surfing所需的唯一设置是允许设备自行关联在Capgo控制台中的每个channel上。 不需要code的任何更改或配置修改。

channel surfing的核心是由一个API调用驱动的：

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

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

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

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

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

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

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

完整频道切换流程

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

典型流程如下：

  1. 切换频道（setChannel)
  2. 检查更新（getLatest)
  3. 获取并应用更新（download, set 或 next)
  4. 如果需要重新加载应用（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(), you must enable self-assignment for that channel in the Capgo dashboard:

  1. 控制台中为该频道启用自我赋值： 进入 section in your Capgo dashboard
  2. 部分
  3. 控制台 点击要管理的频道名称
  4. 启用

Enable self-assignment in channel settings

允许设备自我关联“ 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

Capgo

__CAPGO_KEEP_0__

[__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_KEEP_0__ 下载量。

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

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

数据迁移考虑

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

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

为什么频道切换改善了移动迭代

频道切换尤其有用，当您需要在生产环境中快速查看更改时。

快速验证

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

利益相关者审查

__CAPGO_KEEP_0__

__CAPGO_KEEP_1__

__CAPGO_KEEP_2__

__CAPGO_KEEP_3__

  • __CAPGO_KEEP_4____CAPGO_KEEP_5__
  • __CAPGO_KEEP_6____CAPGO_KEEP_7__
  • __CAPGO_KEEP_8____CAPGO_KEEP_9__
  • __CAPGO_KEEP_10____CAPGO_KEEP_11__
  • 调试:切换到调试频道以诊断问题

频道切换方法比较

方法生效时间持久存储位置使用场景
setChannel() 来自插件立即仅设备本地（本地）用户在应用内触发的频道切换
设备控制台强制切换最多2分钟后端数据库管理员为特定设备的更改
API 频道分配最多2分钟后端数据库自动化后端集成

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

最佳实践

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

资源

结论

通过频道浏览来迭代Capacitor应用。相比于将生产版本视为固定的终点，频道浏览使其成为测试、验证和快速迭代的灵活工具。

通过最近插件版本中引入的即时频道切换功能，体验现在变得更加流畅 - 用户可以切换频道并立即从新频道接收更新，而无需等待任何时间。

无论您是否验证bug修复方案、运行beta测试或调试特定用户的问题，频道浏览都为您提供了灵活性，能够在正确的时间向正确的用户发送正确的更新。

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

如果您正在使用 频道浏览Capgo：如何在运行时切换更新频道 来规划频道路由和分阶段发布，连接它与 频道 来获取频道路由和分阶段发布的实现细节， 频道 Channels的实现细节 Channels Channels的实现细节 帮代测试端权器 为Beta Testing Solution的产品流程 端权器事为第事端权器 端权器事为第事端权器

Capacitor 应用的实时更新

当 web 层面的 bug 活跃时，通过 Capgo 将修复推送给用户，而不是等待几天的 app store 审批。用户在后台接收更新，而原生变化仍然在正常的审批路径中。

立即开始

最新博客文章

Capgo 为您提供了创建真正专业的移动应用所需的最佳见解。

Capacitor 应用的双向通信
开发,移动,更新
2025年4月26日

Capacitor应用的双向通信

避免的5种OTA更新常见错误
开发、安全、更新
2025年4月13日

避免的5种OTA更新常见错误

移动应用实时更新的5种安全最佳实践
开发、移动、更新
2025年1月14日

移动应用实时更新的5种安全最佳实践

查看所有博客文章