Devices

Devices 代表由 Capgo 管理的应用程序的各个安装。Devices API 允许您跟踪和管理设备，包括其版本、渠道和更新状态。

数据保留

设备数据从最后一次设备活动起保留 90 天。在此期间内未连接到 Capgo 的设备将自动从系统中删除。活跃设备在检查更新时会被持续跟踪。

了解 Devices

每个设备都有独特的特征和状态：

• Platform：iOS 或 Android
• Version：当前 bundle 版本和原生构建版本
• Environment：生产或开发环境、模拟器或物理设备
• Channel：当前更新渠道分配
• Custom ID：用于您自己跟踪目的的可选标识符

最佳实践

1. 版本跟踪：监控设备版本以确保更新采用
2. 渠道管理：根据测试需求将设备分配到适当的渠道
3. 环境意识：适当处理不同环境（生产/开发/模拟器）
4. 自定义识别：使用自定义 ID 与现有系统集成

Endpoints

POST

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

将设备链接到特定版本或渠道。

Request Body

interface DeviceLink {
  app_id: string
  device_id: string
  version_id?: string // version name
  channel?: string    // channel name
}

请求示例

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

成功响应

{
  "status": "ok"
}

GET

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

检索设备信息。使用基于游标的分页来高效检索大型设备列表。

查询参数

• app_id：必需。您的应用程序 ID
• device_id：可选。用于检索单个设备的特定设备 ID
• cursor：可选。来自上一个响应的游标，用于分页
• limit：可选。每页设备数（默认值：50）

请求示例s

# Get all devices (first page)
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=app_123"

# Get specific device
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=app_123&device_id=device_456"

# Get next page using cursor
curl -H "authorization: your-api-key" \
  "https://api.capgo.app/device/?app_id=app_123&cursor=2024-01-01T00:00:00Z|device_456"

响应类型（列表）

请求多个设备时（无 device_id 参数）：

interface DeviceListResponse {
  data: Device[];
  nextCursor?: string;  // 将此作为 'cursor' 参数传递以获取下一页
  hasMore: boolean;     // 如果有更多页面可用则为 true
}

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";
  plugin_version: string;
  os_version: string;
  version_build: string;
  is_prod: boolean;
  is_emulator: boolean;
}

响应类型（单个设备）

使用 device_id 参数请求特定设备时，直接返回设备对象：

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";
  plugin_version: string;
  os_version: string;
  version_build: string;
  is_prod: boolean;
  is_emulator: boolean;
}

响应示例（列表）

{
  "data": [
    {
      "device_id": "device_456",
      "custom_id": "test-device-1",
      "version": 1,
      "version_name": "1.0.0",
      "app_id": "app_123",
      "platform": "ios",
      "plugin_version": "5.0.0",
      "os_version": "17.0",
      "version_build": "1",
      "is_prod": true,
      "is_emulator": false,
      "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": "app_123",
  "platform": "ios",
  "plugin_version": "5.0.0",
  "os_version": "17.0",
  "version_build": "1",
  "is_prod": true,
  "is_emulator": false,
  "updated_at": "2024-01-01T00:00:00Z",
  "channel": "production"
}

DELETE

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

从其渠道覆盖中取消链接设备。这会将设备重置为使用其默认渠道。

删除设备

设备数据从最后一次设备活动起保留 90 天。在此期间内未连接到 Capgo 的设备将自动从系统中删除。活跃设备在检查更新时会被持续跟踪。 您无法使用此端点删除设备，它仅影响渠道覆盖。

Query Parameters

interface Device {
  device_id: string
  app_id: string
}

请求示例

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

成功响应

{
  "status": "ok"
}

错误处理

常见错误场景及其响应：

// Device not found
{
  "error": "Device not found",
  "status": "KO"
}

// Invalid version
{
  "error": "Version not found",
  "status": "KO"
}

// Invalid channel
{
  "error": "Channel not found",
  "status": "KO"
}

// Permission denied
{
  "error": "Insufficient permissions to manage devices",
  "status": "KO"
}

常见用例

1. Beta Device Registration

{
  "app_id": "app_123",
  "device_id": "device_456",
  "channel": "beta"
}

2. Version Override

{
  "app_id": "app_123",
  "device_id": "device_456",
  "version_id": "1.1.0"
}

3. Reset to Default Channel

// Use DELETE endpoint to remove overrides

设备管理提示

1. 监控：定期检查设备状态和版本分布
2. 测试：使用自定义 ID 轻松识别测试设备
3. 故障排除：跟踪设备更新和渠道分配
4. 版本控制：监控原生应用版本以确保兼容性