Devices

기기는 Capgo에서 관리하는 앱의 개별 설치를 나타냅니다. 장치 API를 사용하면 번들(버전), 채널 및 업데이트 상태를 포함하여 장치를 추적하고 관리할 수 있습니다.

:::참고[데이터 제외] 기기 데이터는 마지막 기기 활동으로부터 90일 동안 보관됩니다. 이 기간 내에 Capgo에 연결되지 않은 장치는 시스템에서 자동으로 제거됩니다. 활성 장치는 업데이트를 확인하면서 지속적으로 추적됩니다. :::

장치 이해

각 장치에는 고유한 특성과 상태가 있습니다.

• 플랫폼: iOS, Android 또는 Electron
• 번들(버전): 현재 번들(버전) 및 네이티브 빌드 버전
• 환경: 제작 또는 개발, 에뮬레이터 또는 물리적 장치
• 채널: 현재 업데이트 채널 할당
• 맞춤 ID: 추적 목적을 위한 선택적 식별자

모범 사례

1. 번들(버전) 추적: 업데이트 적용을 보장하기 위해 장치 번들(버전) 채택을 모니터링합니다.
2. 채널 관리: 테스트 요구 사항에 따라 적절한 채널에 장치를 할당합니다.
3. 환경 인식: 다양한 환경(프로덕션/개발/에뮬레이터)을 적절하게 처리합니다.
4. 맞춤 식별: 맞춤 ID를 사용하여 기존 시스템과 통합

엔드포인트

포스트

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"
}

받기

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

장치 정보를 검색합니다. 대규모 장치 목록을 효율적으로 검색하기 위해 커서 기반 페이지 매김을 사용합니다.

쿼리 매개변수

• app_id: 필수입니다. 앱의 ID
• device_id: 선택 사항입니다. 단일 장치를 검색하기 위한 특정 장치 ID
• cursor: 선택 사항입니다. 페이지 매김에 대한 이전 응답의 커서
• limit: 선택 사항입니다. 페이지당 장치 수(기본값: 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"
}

삭제

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. 베타 장치 등록

{
  "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. **네이티브 버전 제어**: 호환성을 보장하기 위해 네이티브 앱 버전을 모니터링합니다.