设备

设备是独立的应用程序安装，向 Capgo 报告更新器元数据。使用此 API 来检索该元数据或设置和删除设备特定的私有通道重写。

数据保留

设备数据保留 90 天 从设备最后一次活动开始。设备不需要安装更新即可显示：更新器和统计检查可以刷新其元数据。

设备元数据

每个记录可以包含设备 ID、平台、更新器和 OS 版本、原生构建、安装的捆绑包、生产和模拟器状态、自定义 ID 和渠道覆盖。

当可用时， country_code 是设备从 code 处收到的最新有效的两位字母 ISO 3166-1 国家代码 Cloudflare。它不是 GPS 或您的应用程序提供的位置值。它可以 null 当不可用时，请使用单设备查找时使用此字段。

端点

POST

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

为设备设置特定的覆盖值到 私有 频道。要为设备选择一个包，分配该包到频道；不支持直接设备包覆盖值。

请求体

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/

公共频道不能用作设备覆盖。

成功响应

{
  "status": "ok"
}

GET

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

检索设备元数据。 当您省略时，结果将分页显示。 device_id.

查询参数

• app_id: 必须的反向域名应用 ID，例如 com.example.app.
• device_id: 当前存在时，响应为单个设备而不是分页列表。
• customIdMode：可选布尔值。设置为 true 返回仅非空设备的 custom_id.
• 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/

请求体或查询参数

删除设备的频道覆盖。设备将使用其正常的频道选择；此端点不会删除其元数据记录。

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 错误状态和一个 JSON 体中 error 和 message fields. 常见错误代码包括：

• invalid_app_id 当 app_id 不是一个逆向域名标识符。
• device_not_found 为未知设备查找。
• channel_not_found 当请求的渠道不存在时。
• public_channel_override 当尝试将设备重定向到公共渠道时。
• invalid_version_id 当尝试直接覆盖包时，请使用渠道代替。
• cannot_access_app 或 cannot_access_channel 当API密钥缺少所需的权限时。

常见用例

1. 将测试设备移动到私有beta渠道

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

2. 重置设备到正常频道选择

   使用 DELETE endpoint 和应用程序和设备 ID

从设备继续

如果您正在使用 设备 规划频道路由和阶段性发布， 频道 频道的实现细节在频道中 频道 Channels的实现细节 Channels Channels的实现细节 很给浏览器的浏览器给库端 Version Targeting Solution Version Targeting Solution的产品工作流程 编辑页面