跳过内容
Capgo - 为Capacitor应用提供实时更新 Capgo

Channel API Endpoint

GitHub

Capgo 中的频道是管理应用程序更新的核心机制。在自托管模式下，您需要实现频道端点来处理设备分配、频道查询和频道管理操作。

了解频道

标题：了解频道

频道允许您：

  • 控制更新分发: 将不同应用程序版本分配给不同用户组
  • A/B 测试: 在特定用户群体中测试新功能
  • 阶段性发布: 分阶段发布更新以降低风险
  • 环境隔离: 将开发、测试和生产更新分开

配置

标题：配置

在您的 capacitor.config.json:

{
  "plugins": {
    "CapacitorUpdater": {
      "channelUrl": "https://myserver.com/api/channel_self"
    }
  }
}

频道操作

标题：频道操作

插件执行以下频道操作，需要您的端点处理：

1. 列出兼容频道（GET 请求）

1. 列出兼容的频道（GET 请求）

当插件调用时 listChannels()它会发送一个 GET 请求来检索与设备兼容的所有频道。该请求返回与设备环境（dev/prod，模拟器/真实设备）匹配的频道，并允许公共访问或自我分配。

请求格式

请求格式
// GET /api/channel_self
// Headers:
{
  "Content-Type": "application/json"
}


// Query parameters:
interface ListChannelsRequest {
  app_id: string
  platform: "ios" | "android" | "electron"
  is_emulator: boolean
  is_prod: boolean
  key_id?: string
}

响应格式

响应格式
[
  {
    "id": 1,
    "name": "production",
    "public": true,
    "allow_self_set": false
  },
  {
    "id": 2,
    "name": "beta",
    "public": false,
    "allow_self_set": true
  }
]

了解频道类型

响应中包含每个频道的两个重要标志：

__CAPGO_KEEP_0__

  • public: true: 这是 default channel. 设备无法自行将其分配到该频道中使用 setChannel(). 相反，如果设备移除其频道分配（使用 unsetChannel()），它将自动从公共频道接收更新，如果它匹配设备的条件。

  • allow_self_set: true: 这是 自行分配频道. 设备可以显式将其分配到该频道中使用 setChannel()。这对于测试、A/B测试或允许用户选择特定更新轨迹非常有用。

2. 获取频道（PUT 请求）

标题：2. 获取频道（PUT 请求）

当插件调用 getChannel(),它会发送一个 PUT 请求来获取设备当前的频道分配。

请求格式

复制到剪贴板
// PUT /api/channel_self
// Headers:
{
  "Content-Type": "application/json"
}


// Body:
interface GetChannelRequest {
  device_id: string
  app_id: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
  is_emulator: boolean
  is_prod: boolean
  defaultChannel?: string
  channel?: string  // For newer plugin versions, contains local channel override
}

标题：响应格式

复制到剪贴板
{
  "status": "ok",
  "channel": "production",
  "allowSet": true,
  "message": "",
  "error": ""
}

3. 设定频道 (POST 请求)

标题：3. 设定频道 (POST 请求)

当插件调用 setChannel()它会发送一个 POST 请求来将设备分配到特定的频道。

请求格式

标题：请求格式
// POST /api/channel_self
interface SetChannelRequest {
  device_id: string
  app_id: string
  channel: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
  is_emulator: boolean
  is_prod: boolean
}

响应格式

标题：响应格式
{
  "status": "ok",
  "message": "Device assigned to channel successfully",
  "error": ""
}

错误案例

标题：错误案例

When a device tries to assign itself to a __CAPGO_KEEP_0__ __CAPGO_KEEP_0__ (one with __CAPGO_KEEP_1__) public: trueyour endpoint should return an error:

{
  "status": "error",
  "error": "public_channel_self_set_not_allowed",
  "message": "This channel is public and does not allow device self-assignment. Unset the channel and the device will automatically use the public channel."
}

When a device tries to assign itself to a channel that doesn’t allow self-assignment:

{
  "status": "error",
  "error": "channel_self_set_not_allowed",
  "message": "This channel does not allow devices to self associate"
}

4. 取消频道（DELETE Request）

标题：4. 取消频道（DELETE Request）

When the plugin calls __CAPGO_KEEP_2__ unsetChannel(), it sends a DELETE request to remove the device’s channel assignment.

请求格式

节标题：请求格式
// DELETE /api/channel_self
interface UnsetChannelRequest {
  device_id: string
  app_id: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
}

实现示例

节标题：实现示例

以下是 JavaScript 中如何实现通道端点的示例代码:

interface ChannelRequest {
  device_id: string
  app_id: string
  channel?: string
  platform: "ios" | "android" | "electron"
  plugin_version: string
  version_build: string
  version_code: string
  version_name: string
}


interface ChannelResponse {
  status: "ok" | "error"
  channel?: string
  allowSet?: boolean
  message?: string
  error?: string
}


export const handler = async (event) => {
  const method = event.httpMethod || event.method
  const body = JSON.parse(event.body || '{}') as ChannelRequest


  const { device_id, app_id, channel, platform } = body


  try {
    switch (method) {
      case 'GET':
        return await getDeviceChannel(device_id, app_id)


      case 'POST':
        return await setDeviceChannel(device_id, app_id, channel!, platform)


      case 'DELETE':
        return await unsetDeviceChannel(device_id, app_id)


      default:
        return {
          status: "error",
          error: "Method not allowed"
        }
    }
  } catch (error) {
    return {
      status: "error",
      error: error.message
    }
  }
}


async function getDeviceChannel(deviceId: string, appId: string): Promise<ChannelResponse> {
  // Query your database for device channel assignment
  const assignment = await database.getDeviceChannel(deviceId, appId)


  if (assignment) {
    return {
      status: "ok",
      channel: assignment.channel,
      allowSet: assignment.allowSelfAssign
    }
  }


  // Return default channel if no assignment found
  return {
    status: "ok",
    channel: "production", // Your default channel
    allowSet: true
  }
}


async function setDeviceChannel(
  deviceId: string,
  appId: string,
  channel: string,
  platform: string
): Promise<ChannelResponse> {
  // Validate channel exists and allows self-assignment
  const channelConfig = await database.getChannelConfig(channel, appId)


  if (!channelConfig) {
    return {
      status: "error",
      error: "Channel not found"
    }
  }


  if (!channelConfig.allowDeviceSelfSet) {
    return {
      status: "error",
      error: "Channel does not allow self-assignment"
    }
  }


  // Check platform restrictions
  if (platform === "ios" && !channelConfig.ios) {
    return {
      status: "error",
      error: "Channel not available for iOS"
    }
  }


  if (platform === "android" && !channelConfig.android) {
    return {
      status: "error",
      error: "Channel not available for Android"
    }
  }


  if (platform === "electron" && !channelConfig.electron) {
    return {
      status: "error",
      error: "Channel not available for Electron"
    }
  }


  // Save the assignment
  await database.setDeviceChannel(deviceId, appId, channel)


  return {
    status: "ok",
    message: "Device assigned to channel successfully"
  }
}


async function unsetDeviceChannel(deviceId: string, appId: string): Promise<ChannelResponse> {
  // Remove device channel assignment
  await database.removeDeviceChannel(deviceId, appId)


  return {
    status: "ok",
    message: "Device channel assignment removed"
  }
}

通道配置

节标题：通道配置

您的通道系统应支持以下配置选项:

interface ChannelConfig {
  name: string
  appId: string


  // Platform targeting
  ios: boolean              // Allow updates to iOS devices
  android: boolean          // Allow updates to Android devices
  electron: boolean         // Allow updates to Electron apps


  // Device type restrictions
  allow_emulator: boolean   // Allow updates on emulator/simulator devices
  allow_device: boolean     // Allow updates on real/physical devices


  // Build type restrictions
  allow_dev: boolean        // Allow updates on development builds (is_prod=false)
  allow_prod: boolean       // Allow updates on production builds (is_prod=true)


  // Channel assignment
  public: boolean           // Default channel - devices fall back to this when no override
  allowDeviceSelfSet: boolean  // Allow devices to self-assign via setChannel()


  // Update policies
  disableAutoUpdate: "major" | "minor" | "version_number" | "none"
  disableAutoUpdateUnderNative: boolean
}

设备过滤逻辑

节标题：设备过滤逻辑

列出兼容的频道 (GET 请求) 时，您应该根据以下条件过滤频道：

  1. 平台检查: 频道必须允许设备的平台 (ios, android，或 electron)
  2. 设备类型检查:
    • 如果 is_emulator=true: 频道必须具有 allow_emulator=true
    • 如果 is_emulator=false: 频道必须具有 allow_device=true
  3. 构建类型检查:
    • 如果 is_prod=true: 频道必须具有 allow_prod=true
    • If is_prod=false: Channel 必须有 allow_dev=true
  4. Visibility 检查: Channel 必须是 public=true 或 allow_device_self_set=true
// Example filtering logic
function getCompatibleChannels(
  platform: 'ios' | 'android' | 'electron',
  isEmulator: boolean,
  isProd: boolean,
  channels: ChannelConfig[]
): ChannelConfig[] {
  return channels.filter(channel => {
    // Platform check
    if (!channel[platform]) return false


    // Device type check
    if (isEmulator && !channel.allow_emulator) return false
    if (!isEmulator && !channel.allow_device) return false


    // Build type check
    if (isProd && !channel.allow_prod) return false
    if (!isProd && !channel.allow_dev) return false


    // Must be accessible (public or self-assignable)
    if (!channel.public && !channel.allowDeviceSelfSet) return false


    return true
  })
}

数据库架构示例

标题：数据库架构示例

您需要存储通道配置和设备 assignments：

-- Channels table
CREATE TABLE channels (
  id SERIAL PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  app_id VARCHAR(255) NOT NULL,


  -- Platform targeting
  ios BOOLEAN DEFAULT true,
  android BOOLEAN DEFAULT true,
  electron BOOLEAN DEFAULT true,


  -- Device type restrictions
  allow_emulator BOOLEAN DEFAULT true,   -- Allow emulator/simulator devices
  allow_device BOOLEAN DEFAULT true,     -- Allow real/physical devices


  -- Build type restrictions
  allow_dev BOOLEAN DEFAULT true,        -- Allow development builds
  allow_prod BOOLEAN DEFAULT true,       -- Allow production builds


  -- Channel assignment
  public BOOLEAN DEFAULT false,          -- Default channel (fallback)
  allow_device_self_set BOOLEAN DEFAULT false,  -- Allow self-assignment


  -- Update policies
  disable_auto_update VARCHAR(50) DEFAULT 'none',
  disable_auto_update_under_native BOOLEAN DEFAULT false,


  created_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(name, app_id)
);


-- Device channel assignments table
CREATE TABLE device_channels (
  id SERIAL PRIMARY KEY,
  device_id VARCHAR(255) NOT NULL,
  app_id VARCHAR(255) NOT NULL,
  channel_name VARCHAR(255) NOT NULL,
  assigned_at TIMESTAMP DEFAULT NOW(),
  UNIQUE(device_id, app_id)
);

错误处理

标题：错误处理

处理常见错误场景：

// Channel not found
{
  "status": "error",
  "error": "Channel 'beta' not found"
}


// Self-assignment not allowed
{
  "status": "error",
  "error": "Channel does not allow device self-assignment"
}


// Platform not supported
{
  "status": "error",
  "error": "Channel not available for this platform"
}


// Invalid request
{
  "status": "error",
  "error": "Missing required field: device_id"
}

最佳实践

名为“最佳实践”的部分
  1. 安全性context: 企业产品/价格页面。角色：UI标签。见于：企业.astro页面。消息键 `enterprise_hero_security_label` (企业英雄安全性标签)。
  2. ：验证所有通道 assignments 与您的商业规则日志
  3. ：为审计和调试目的记录所有通道操作性能
  4. context: 首页问题/解决方案部分。角色：部分或页面标题。见于：premium-support.astro页面。消息键 `ps_help_performance_title` (Ps 帮助性能标题)。：缓存通道配置以减少数据库查询数目
  5. 速率限制: 实现速率限制以防止滥用

与更新的集成

标题：与更新的集成

频道 assignments 与您的 更新 API 接口. 当设备请求更新时，检查其频道 assignments 以确定哪个版本应该提供:

async function getUpdateForDevice(deviceId: string, appId: string) {
  // Get device's channel assignment
  const channelAssignment = await getDeviceChannel(deviceId, appId)
  const channel = channelAssignment.channel || 'production'


  // Get the version assigned to this channel
  const channelVersion = await getChannelVersion(channel, appId)


  return {
    version: channelVersion.version,
    url: channelVersion.url,
    checksum: channelVersion.checksum
  }
}

这创建了一个完整的自托管频道管理系统，使您能够完全控制如何将更新分发给您的用户。

继续从频道 API 接口

标题：继续从频道 API 接口

如果您正在使用 API频道端点 为计划频道路由和阶段性发布，连接它 使用@capgo/capacitor-updater 为native能力在使用@capgo/capacitor-updater中 频道 上下文:Capgo发布频道功能名称。页面/区域:Capgo解决方案营销页面。角色:短UI标签或导航项。见于：页面解决方案/白标签.astro。消息键`solutions_white_label_visual_cell2_value` (解决方案白标签视觉单元2值)。 为频道实现细节 频道 上下文:Capgo发布频道功能名称。页面/区域:Capgo解决方案营销页面。角色:短UI标签或导航项。见于：页面解决方案/白标签.astro。消息键`solutions_white_label_visual_cell2_value` (解决方案白标签视觉单元2值)。 为频道实现细节 频道 上下文:Capgo发布频道功能名称。页面/区域:Capgo解决方案营销页面。角色:短UI标签或导航项。见于：页面解决方案/白标签.astro。消息键`solutions_white_label_visual_cell2_value` (解决方案白标签视觉单元2值)。