设备

设备代表了您的应用程序的单个安装，且由 Capgo 管理。设备 API 允许您跟踪和管理设备，包括它们的包（版本）、通道和更新状态。

数据保留期

设备数据将保留 90 天 自上次设备活动以来。没有连接到Capgo的设备将在此期间自动从系统中删除。活跃的设备将持续被跟踪以便检查更新。

了解设备

平台

• : iOS、Android或Electron捆绑包（版本）
• : 当前捆绑包（版本）和本机构建版本环境
• 环境: 生产环境或开发环境, 模拟器或物理设备
• Channel: 当前更新频道分配
• Custom ID: 为自己的跟踪目的而设置的可选标识符

Best Practices

1. Bundle (version) Tracking: 监控设备包 (版本) 采用以确保更新率
2. Channel Management: 根据测试需求将设备分配到适当的频道
3. Environment Awareness: 根据环境（prod/dev/emulator）进行适当处理
4. 自定义识别: 使用自定义 ID 与您的现有系统进行集成

接口

POST

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

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

请求体

interface DeviceLink {
  app_id: string
  device_id: string
  version_id?: string // bundle (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: Optional. Specific device ID to retrieve a single device
• cursor: Optional. Cursor from previous response for 分页
• limit: Optional. 每页显示的设备数量 (默认值: 50)

示例请求

# 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;  // Pass this as 'cursor' param to get next page
  hasMore: boolean;     // true if more pages available
}

interface Device {
  updated_at: string;
  device_id: string;
  custom_id: string;
  version?: number; // bundle (version) id
  version_name: string | null; // bundle (version) name
  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; // First 4 chars of encryption key (e.g., "MIIB")
}

响应类型 (单设备)

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

interface Device {
  updated_at: string;
  device_id: string;
  custom_id: string;
  version?: number; // bundle (version) id
  version_name: string | null; // bundle (version) name
  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; // First 4 chars of encryption key (e.g., "MIIB")
}

示例响应 (列表)

{
  "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的设备将在此期间自动从系统中删除。 活跃设备将持续跟踪它们检查更新。

您无法使用此端点删除设备，它只会影响通道重写。

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 bundle (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 设备注册

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

2. 版本覆盖

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

3. 重置为默认频道

// Use DELETE endpoint to remove overrides

设备管理的提示

1. 监控定期检查设备状态和包（版本）分发
2. 测试使用自定义 ID 方便识别测试设备
3. 故障排除: 设备更新跟踪和频道分配
4. 原生版本控制: 确保兼容性，监控原生应用版本

从设备继续

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