设备

Device 指的是向 Capgo 上报 updater 元数据的单个 App 安装实例。你可以通过该 API 来获取这些元数据，或者设置及移除特定设备的 private-channel 覆盖配置。

两项 90 天策略

设备清单： 设备记录保留时间为 90 天 自最后一次设备活动起。设备无需安装更新即可显示：updater 和 stats 的 check-in 可以刷新其元数据。

Channel 覆盖： POST override 将在 最后一次写入 override 后的 90 天被移除，即使设备仍在进行 check-in。Check-in 不会重置该计时器。为避免自动清理，请在 defaultChannel Capacitor 配置中设置（即使重新安装也有效）或从 App 中调用 setChannel() 。 @capgo/capacitor-updater 方法 setChannel() 以及 unsetChannel() 仅在 Android 和 iOS 上受支持。在 plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 及更高版本中， setChannel() 是本地的，且不会被此清理操作移除。在 Android 和 iOS 上使用 updater 8.51.0 及更高版本时， persistDefaultChannelOnReinstall 默认为 true因此，只有当操作系统恢复应用数据且该选项保持启用时，本地赋值才能在重新安装后保留。使用较旧的 updater 重新安装、在不恢复应用数据的情况下进行全新安装，或设置 persistDefaultChannelOnReinstall: false 用于重新安装时，可能会清除本地赋值。使用 unsetChannel() 可显式清除本地选择；它不会删除 console/API 覆盖项。早于上述 local-channel 版本的插件会写入一个在重新安装后依然存在的后端覆盖项，并会被此清理操作移除。请参阅 Console 和 API 覆盖将在 90 天后过期.

设备元数据

每条记录可以包含设备 ID、平台、updater 和 OS 版本、Native Build、已安装的 bundle、生产环境与模拟器状态、自定义 ID 以及 channel override。

如果可用， country_code 是针对该设备从 Cloudflare 处理的请求中收到的最新的、有效的两位 ISO 3166-1 国家 code。它不是 GPS 或由您的应用提供的位置值。它可以是 null 若不可用；在需要此字段时，请使用单设备查询。

端点

POST

https://api.capgo.app/device/

将设备特定的覆盖项设置为 private channel。若要为特定设备选择 bundle，请将该 bundle 分配给该 channel；暂不支持直接进行单设备 bundle 覆盖。除非再次执行 POST，否则覆盖将在最后一次写入 90 天后过期。

请求体

interface DeviceChannelOverride {
  app_id: string; // reverse-domain app ID, for example com.example.app
  device_id: string;
  channel: string; // existing non-public channel name
}

请求示例

curl -X POST \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "device_id": "device_456",
    "channel": "beta"
  }' \
  https://api.capgo.app/device/

公共频道不能用作设备覆盖 (device overrides)。

成功响应

{
  "status": "ok"
}

GET

https://api.capgo.app/device/

获取设备元数据。如果不提供 device_id.

查询参数 (Query parameters)，结果将采用游标分页。

• app_id：必填，反向域名格式的 App ID，例如 com.example.app.
• device_id：可选的 device ID。如果提供，响应将返回单个设备而非分页列表。
• customIdMode：可选布尔值。设置为 true 以仅返回具有非空 custom_id.
• cursor：可选，来自上一次列表响应的 cursor。
• limit：可选，每页显示的设备数量。

请求示例

# Get the first page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app"

# Get one device, including its request-derived country when available
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app&device_id=device_456"

# Get only devices with a custom ID
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app&customIdMode=true"

# Get the next page
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=com.example.app&cursor=2024-01-01T00:00:00Z%7Cdevice_456"

响应类型

interface DeviceListResponse {
  data: Device[];
  nextCursor?: string;
  hasMore: boolean;
}

interface Device {
  updated_at: string;
  device_id: string;
  custom_id: string;
  version?: number;
  version_name: string | null;
  channel?: string;
  app_id: string;
  platform: "ios" | "android" | "electron";
  plugin_version: string;
  os_version: string;
  version_build: string;
  is_prod: boolean;
  is_emulator: boolean;
  key_id: string | null;
  install_source: string | null;
  country_code: string | null;
}

country_code 当 Capgo 存有由 Cloudflare 推导出的有效国家 code 时，会通过设备特定的查询填充。不含有效国家的请求不会清除上一个有效值；列表响应可能返回 null 该字段的值。

响应示例（列表）

{
  "data": [
    {
      "device_id": "device_456",
      "custom_id": "test-device-1",
      "version": 1,
      "version_name": "1.0.0",
      "app_id": "com.example.app",
      "platform": "ios",
      "plugin_version": "5.0.0",
      "os_version": "17.0",
      "version_build": "1",
      "is_prod": true,
      "is_emulator": false,
      "key_id": null,
      "install_source": null,
      "country_code": null,
      "updated_at": "2024-01-01T00:00:00Z"
    }
  ],
  "nextCursor": "2024-01-01T00:00:00Z|device_456",
  "hasMore": true
}

响应示例（单个设备）

{
  "device_id": "device_456",
  "custom_id": "test-device-1",
  "version": 1,
  "version_name": "1.0.0",
  "app_id": "com.example.app",
  "platform": "ios",
  "plugin_version": "5.0.0",
  "os_version": "17.0",
  "version_build": "1",
  "is_prod": true,
  "is_emulator": false,
  "key_id": "MIIB",
  "install_source": null,
  "country_code": "FR",
  "updated_at": "2024-01-01T00:00:00Z",
  "channel": "beta"
}

删除

https://api.capgo.app/device/

移除设备的 channel override。设备将重新使用正常的 channel 选择逻辑；此 endpoint 不会删除其元数据记录。

请求体或查询参数

interface DeviceOverrideRemoval {
  app_id: string;
  device_id: string;
}

请求示例

curl -X DELETE \
  -H "authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "com.example.app",
    "device_id": "device_456"
  }' \
  https://api.capgo.app/device/

成功响应

{
  "status": "ok"
}

错误

错误会返回 HTTP 状态码及包含以下 error 以及 message 字段的 JSON 响应体。常见的错误码包括：

• invalid_app_id 何时 app_id 不是有效的反向域名标识符。
• device_not_found 无法查询到该未知设备。
• channel_not_found 请求的 channel 不存在。
• public_channel_override 尝试将设备覆盖到公共 channel 时出错。
• invalid_version_id 尝试直接覆盖 bundle 时出错；请改用 channel。
• cannot_access_app 或 cannot_access_channel 当 API 密钥缺少必要权限时。

常见使用场景

1. 将测试设备移至私有 Beta 测试频道

   {
     "app_id": "com.example.app",
     "device_id": "device_456",
     "channel": "beta"
   }

2. 将设备重置为常规频道选择

   使用 DELETE 包含 App ID 和设备 ID 的端点。

继续阅读“设备”相关内容

如果你正在使用 设备 要规划 Channel 路由和分阶段发布，请将其与 通道 有关 Channels 的实现细节， 通道 有关 Channels 的实现细节， 通道 有关 Channels 的实现细节， Beta 测试解决方案 适用于 Beta Testing Solution 产品工作流的，以及 版本定向解决方案 适用于 Version Targeting Solution 产品工作流的。