设备

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

两个 90 天策略

设备清单： 设备记录保留 90 天 自上一次设备活动。设备不需要安装更新即可显示：更新器和统计检查可以刷新其元数据。

频道重写： 一个 POST 重写在 90 天后删除最后一次重写写入即使设备仍在检查连接，检查连接也不会重置时钟。为了避免清理，设置 defaultChannel 在 Capacitor 配置（可在重新安装后生存）或从应用程序中调用 setChannel() 从应用程序中调用。从插件 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 和更高版本中 setChannel() 是本地的，重新安装后会清除，因此应用程序必须再次调用它。较旧的插件会写入一个后端覆盖，生存重新安装，并由此清理移除。请参见 控制台和 API 覆盖在 90 天后过期.

设备元数据

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

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

API端点

POST

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

为设备设置特定的覆盖值到一个 私有 channel. 为设备选择一个包，分配该包到channel; 不支持直接设备包覆盖。 覆盖在最后一次写入后90天过期，除非您再次POST它。

Request body

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

Example request

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：可选设备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时，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"
}

DELETE

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 when the API key lacks the required permission.

或

1. 或

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

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

   使用 DELETE 带有应用程序和设备 ID 的端点。

继续从设备

如果您正在使用 设备 来规划频道路由和阶段性发布，连接它到 频道 频道 频道 为 Channels 的实现细节 Channels 为 Channels 的实现细节 Beta 测试解决方案 为 Beta 测试解决方案的产品工作流程 版本目标解决方案 为版本目标解决方案的产品工作流程