设备

设备是单独的应用程序安装，向 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、平台、更新器和 OS 版本、原生构建、安装的捆绑包、生产和模拟器状态、自定义 ID 和通道覆盖。

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

端点

POST

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

为设备设置特定配置 私有 频道

为设备选择一个包，需要将包赋予频道；不支持直接为设备设置包。配置在90天后过期，除非您再次发送POST请求。

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: 可选的设备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"

上下文：Capgo营销网站。角色：UI标签。位置：页面代理/[slug].astro。消息键 `agents_page_copy_label` (代理页面复制标签)。

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 is populated by a device-specific lookup when Capgo has stored a valid Cloudflare-derived country code. Requests without a valid country do not clear the last valid value; list responses may return null 由设备特定查找填充，当__CAPGO_KEEP_0__存储了一个有效的__CAPGO_KEEP_1__-派生国家__CAPGO_KEEP_2__时。无效国家的请求不会清除最后一个有效值；列表响应可能返回此字段。

示例响应（列表）

{
  "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 字段。常见错误代码包括：

• 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. 常见用例

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

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

   使用 DELETE endpoint

继续从设备

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