디바이스

이 플러그인의 설치 단계와 전체 markdown 가이드가 포함된 설정 프롬프트를 복사하세요.

Device는 Capgo에 업데이트 메타데이터를 보고하는 개별 앱 설치 단위입니다. 이 API을 사용하여 해당 메타데이터를 조회하거나, 디바이스별 전용 private-channel 오버라이드를 설정 및 삭제할 수 있습니다.

디바이스 인벤토리: 디바이스 기록은 다음 기간 동안 유지됩니다: 90일 마지막 디바이스 활동 기준입니다. 업데이트를 설치하지 않아도 디바이스가 나타날 수 있습니다. updater 및 stats check-in을 통해 메타데이터가 갱신될 수 있기 때문입니다.

Channel override: POST override는 삭제됩니다 마지막 override 기록 후 90일이 지나면, 기기가 여전히 체크인 중이더라도 마찬가지입니다. 체크인을 한다고 해서 해당 타이머가 초기화되지는 않습니다. 이러한 정리 작업을 방지하려면 다음을 설정하세요. defaultChannel 앱에서 Capacitor를 호출하세요. setChannel() 해당 @capgo/capacitor-updater 메서드들은 setChannel() 및 unsetChannel() Android 및 iOS에서만 지원됩니다. plugin 5.34.0 / 6.34.0 / 7.34.0 / 8.0.0 이상 버전부터 적용됩니다. setChannel() 로컬에 저장되며 이 cleanup으로 제거되지 않습니다. Android 및 iOS에서 updater 8.51.0 이상을 사용하는 경우, persistDefaultChannelOnReinstall 기본값은 true, 따라서 운영 체제가 앱 데이터를 복구하고 옵션이 계속 활성화되어 있을 때만 로컬 할당이 재설치 후에도 유지될 수 있습니다. 이전 updater로 재설치하거나, 앱 데이터가 복구되지 않은 클린 재설치를 하거나, 재설치 시 persistDefaultChannelOnReinstall: false 설정하면 로컬 할당이 지워질 수 있습니다. 로컬 선택을 명시적으로 지우려면 unsetChannel() 를 사용하세요. 이 작업은 console/API overrides를 삭제하지 않습니다. 위의 local-channel 버전보다 오래된 플러그인은 재설치 후에도 유지되고 이 cleanup으로 제거되는 backend override를 기록합니다. 자세한 내용은 Console 및 API overrides는 90일 후 만료됩니다.

디바이스 메타데이터

각 레코드에는 디바이스 ID, 플랫폼, updater 및 OS 버전, Native Build, 설치된 bundle, 프로덕션 및 에뮬레이터 상태, custom ID, channel override가 포함될 수 있습니다.

사용 가능한 경우, country_code 는 해당 디바이스에 대해 Cloudflare에서 처리한 요청에서 받은 최신 유효 2자리 ISO 3166-1 국가 code입니다. GPS나 앱에서 제공한 위치 값이 아닙니다. 값은 null 사용할 수 없을 때는 비어 있을 수 있습니다. 이 필드가 필요하면 단일 디바이스 조회를 사용하세요.

엔드포인트

POST

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

특정 기기에 대한 override 설정하기 private 설정합니다. 디바이스별 번들을 선택하려면 해당 번들을 채널에 할당하세요. 디바이스별 직접 번들 오버라이드는 지원되지 않습니다. 오버라이드는 다시 POST를 호출하지 않는 한 마지막 쓰기 작업 후 90일이 지나면 만료됩니다.

요청 본문

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/

Public 채널은 디바이스 오버라이드용으로 사용할 수 없습니다.

성공 응답

{
  "status": "ok"
}

GET

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

디바이스 메타데이터를 가져옵니다. 쿼리 파라미터를 생략하면 device_id.

쿼리 파라미터

app_id: 필수 역도메인(reverse-domain) 앱 ID (예: com.example.app.
device_id: 선택 사항인 device ID입니다. ID를 입력하면 페이지네이션된 목록 대신 단일 디바이스 정보를 반환합니다.
customIdMode: 선택 사항인 boolean 값입니다. true 를 사용하여 비어 있지 않은 디바이스만 반환하려면 custom_id.
cursor: 이전 목록 응답에서 받은 선택 사항인 cursor입니다.
limit: 페이지당 디바이스 개수를 지정하는 선택 사항인 number입니다.

요청 예시

# 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 국가 정보를 저장한 경우, 디바이스별 조회를 통해 해당 값이 채워집니다. 유효한 국가 정보가 없는 요청이라도 마지막으로 확인된 유효한 값을 삭제하지는 않습니다. 목록 응답에는 다음이 포함될 수 있습니다: 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/

디바이스의 채널 오버라이드를 제거합니다. 디바이스는 다시 일반적인 채널 선택 방식을 사용하게 됩니다. 이 엔드포인트는 디바이스의 메타데이터 레코드를 삭제하지는 않습니다.

Request body 또는 query parameters

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 body를 사용합니다: 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 API 키에 필요한 권한이 없을 때 발생합니다.

주요 사용 사례

테스트 기기를 프라이빗 베타 채널로 이동

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

기기 채널 선택을 기본값으로 초기화

다음 DELETE 엔드포인트에 앱 및 기기 ID를 사용하세요.

Devices 섹션에서 계속하기

사용 중인 경우 디바이스 채널 라우팅과 단계적 롤아웃을 계획하려면, 이를 다음 항목과 연결하세요 채널 Channels의 구현 세부 사항은, 채널 Channels의 구현 세부 사항은, 채널 Channels의 구현 세부 사항은, Beta Testing 솔루션 Beta Testing 솔루션의 제품 워크플로우는, Version Targeting 솔루션 Version Targeting 솔루션의 제품 워크플로우를 확인하세요.