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

__CAPGO_KEEP_0__:

是否曾经希望能够直接将更改发送给特定用户进行他们的即时审阅和反馈 - 而不必要求他们下载并安装来自TestFlight或Google Play的新版本？

我曾经有客户要求改进，我能够快速实施，但将结果传递给他们进行验证意味着需要将更新发送给所有用户（风险性实验性更改）或为客户创建一个单独的构建（对我们双方来说是一项繁琐的任务）。

开发者想要能够为不同用户组提供不同的更新，例如非技术人员、QA或整个用户群（在适当时）。

生产版本无法切换到工作版本、收集反馈并返回生产状态。 这就是所谓的‘频道切换’功能。 让用户设备上的已安装应用在运行时可以切换更新频道，从而将生产应用转变为一个灵活的空间进行审阅和迭代，而不是一个固定的终点。这对于非技术人员来说尤其有用，他们可以在他们已经安装的应用中直接测试更改并提供反馈。

理解更新频道

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

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

Capgo中的频道允许您：

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

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

什么是频道浏览？

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

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

在背后，频道浏览通过让应用程序告诉更新客户端使用哪个频道来实现。这个选择可以在运行时更改，并且直到它被清除或替换为止，仍然有效。

如何实现频道浏览

在尝试频道浏览之前，需要将项目配置为Capgo Live Updates。要设置此项，请遵循 Capgo 快速入门指南.

为了实现频道切换功能，只需在每个频道中启用“允许设备自主关联”选项在 Capgo 控制台中 此外，不需要进行任何 code 配置修改

频道切换的核心是由一个 API 函数驱动的

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

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

此函数设置用于查询 Capgo 更新的频道了解更多关于 setChannel API.

快速频道切换（v5.34.0+）

从插件版本 5.34.0、6.34.0、7.34.0 或 8.0.0 开始（取决于您的主版本） 功能会有所不同，速度也会更快： setChannel() 后端验证（只读）

向 __CAPGO_KEEP_0__ 后端发送请求，验证频道是否允许访问: A request is sent to the Capgo backend to validate the channel is allowed
本地存储更新: 如果验证通过，通道将保存到设备的本地存储中
即刻生效: 下一次更新检查将立即使用新的通道

之前的 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
点击您要管理的频道名称
启用 “允许设备自行关联”
保存更改

在频道设置中启用自我分配

完成了。无需在应用程序中进行任何配置更改。无需设置。只需在您希望用户可以切换到的频道上启用自我分配。 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 在您的配置或云端默认中。

如何测试频道浏览

要看到频道浏览的效果，你需要一个发布版 - @capgo/capacitor-updater API 是为发布版设计的。在调试版中，应用通常从开发服务器加载 JavaScript，而不是使用正常的更新流程。

前置条件

频道浏览的唯一要求是启用 “Allow devices to self associate” 在您希望允许切换的每个频道上。无需在您的应用程序中进行任何配置更改。

创建测试构建

按照如下步骤构建您的应用程序：

bun run build && npx cap sync

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

发布到不同频道的更新

一旦应用程序安装完成，发布到不同频道的更新：

# 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 更新注意事项

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

Runtime Version Mismatches

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

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

删除或撤销更新

如果应用已经下载了某个频道的更新，删除该更新从Capgo控制台中不一定会从已经安装了该更新的设备中删除。删除只会停止将来下载。

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

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

数据迁移考虑

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

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

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

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

快速验证

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

利益相关者审查

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

流程化测试

这使得非技术人员能够参与审查和决策，同时保持流程的顺畅。一个单独的生产版本变成了测试、反馈和验证的灵活工具。

用例

QA测试：让QA团队在特性分支之间切换
Beta Programs: 用户们选择加入 beta 渠道获取早期访问
Stakeholder Review: 产品负责人预览更改之前发布
A/B Testing: 将用户分配到不同渠道进行实验
Debugging: Switch a 特定用户到调试渠道来诊断问题

Comparison: Channel Change Methods

策须名	步日时	导八为一个策须一个图布	使用场景
`setChannel()` 从插件	即刻	设备仅限（本地）	在应用内用户触发的频道切换
仪表盘设备覆盖	至多2分钟	后端数据库	管理员针对特定设备的更改
API 频道分配	至多2分钟	后端数据库	自动化后端集成

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

最佳实践

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

资源

结论

频道切换转变了您可以迭代的 Capacitor 应用程序的方式。不再将生产构建视为固定的终点，它们成为测试、验证和快速迭代的灵活工具。

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

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

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

如果您正在使用 Capgo 中的频道浏览功能：如何在运行时切换更新频道 为了规划频道路由和分阶段发布，频道频道频道频道 Beta 测试解决方案为了产品工作流程在 Beta 测试解决方案中，版本目标解决方案为了产品工作流程在 Version Targeting Solution 中，和 Version Targeting Solution 为产品工作流程在版本目标解决方案中。